Role Mapping for SSO Configuration

Mappings are based on claims provided by the identity provider.

Common examples include:

Azure AD Groups
Okta Groups
Email Domains
Department Attributes
Custom Claims

This eliminates the need for administrators to manually assign roles after a user's first login via SSO.

How Role Mapping Works

During login:

The identity provider sends user claims
instellix evaluates all configured mappings
Matching instellix roles are assigned automatically.
The user immediately receives the corresponding permissions

Accessing Role Mappings

Navigate to:

Configuration → Global → Access Management

Open an existing SSO configuration and select Add Role Mapping.

Creating a Role Mapping

Each mapping consists of three values:

Field	Description
Claim or Attribute	Name of the claim received from the identity provider.
External Value	Expected value within the claim.
Target Role	instellix role assigned when a match is found.
Sync Mode	Sync mode determines when role mappings are evaluated and applied.

Example: Mapping Azure Groups

Assume Azure AD sends the following claim:

{
  "groups": [
    "Developers",
    "Support"
  ]
}

Configure the mapping as follows:

Field	Value
Claim or Attribute	groups
External Value	Developers
Target Role	Product Manager

Result:

Every user belonging to the Azure group Developers automatically receives the Product Manager role in instellix.

Example: Mapping Email Domains

Some identity providers expose the user's email address.

Example claim:

{
  "email": "[email protected]"
}

Configure the mapping as follows:

Field	Value
Claim or Attribute	email
External Value	@example.com
Target Role	Auditor

Result:

All users with an email address from the specified domain automatically receive the Auditor role.

Multiple Role Assignments

A user can match multiple mappings.

Example:

Claim	Value	Assigned Role
groups	Developers	Product Manager
groups	Finance	Finance Manager

If both mappings match, the user receives both roles.

Available Target Roles

The list of available roles depends on the roles configured within your tenant. Further information on data reports can be found here.

Sync Mode

The Sync Mode determines when information received from the identity provider is synchronized with the local user account.

This includes all data managed by configured identity provider mappers, such as:

First name and last name
Email address
User attributes
Role mappings

Sync Mode	Description	Recommended when	Effect on Changes
Import	Imports user information and role mappings when the user signs in through SSO for the first time. Later changes in the identity provider are not synchronized automatically.	Local user data may be modified after the initial import.	Changes in the identity provider are not synchronized automatically. Local changes remain unchanged.
Force	Synchronizes user information and role mappings every time the user signs in. The identity provider remains the authoritative source for mapped data.	User information and role assignments should always reflect the current state of the identity provider.	Changes in the identity provider are applied during every login. Depending on the mapper, local changes may be overwritten and roles may be added or removed.
Legacy	Uses the synchronization behavior of older Keycloak versions. The exact behavior depends on the configured mapper and is intended for backward compatibility.	Existing Keycloak configurations that rely on the previous synchronization behavior.	Uses Keycloak's legacy synchronization behavior. Not recommended for new configurations.
Inherit	Uses the Sync Mode configured for the identity provider. The mapper follows the provider's synchronization behavior instead of defining its own.	Individual mappers should follow the provider-wide synchronization settings.	The behavior depends entirely on the Sync Mode configured for the identity provider (for example Import or Force).

Note: The Sync Mode only determines when identity provider mappers are executed. Which user information is synchronized depends on the configured mapper.

Role Mappings

Role mappings behave differently depending on the selected Sync Mode.

Import applies role mappings only when a brokered user is created during the first login.
Force evaluates role mappings during every login, allowing roles to be added or removed based on the current claims provided by the identity provider.

Recommendation: Use Force if the identity provider should remain the authoritative source for user roles.

Best Practices

Use Groups Whenever Possible

Group-based mappings are easier to maintain than user-specific mappings.

Recommended:

groups = Developers → Product Manager

Not recommended:

email = [email protected] → Product Manager

Keep Role Assignments Simple

Assign permissions through identity provider groups and manage membership centrally within the identity provider.

Follow Least Privilege Principles

Only assign the permissions required for a user's responsibilities.

Troubleshooting

User Receives Unexpected Permissions

Review:

Overlapping mappings
Multiple matching claims
Group memberships in the identity provider

User receives no role

Verify that:

The user authenticates through the correct SSO provider
The configured claim exists in the token or SAML assertion
The external value matches exactly
Capitalization matches exactly
The target role still exists
The selected sync mode behaves as expected

Role changes are not synchronized

Verify that:

Sync Mode is set to Force
The user logged in again after the change
The claim values actually changed at the identity provider

Additional Information

The exact claims available for mapping depend on your identity provider configuration.

Refer to your identity provider documentation for information about:

Available claims
Group claims
Custom attributes
Token contents

Role mappings are evaluated on every login, ensuring permissions remain synchronized with your identity provider configuration.