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:

1. The identity provider sends user claims
2. instellix evaluates all configured mappings
3. Matching instellix roles are assigned automatically.
4. 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:

Example: Mapping Azure Groups

Assume Azure AD sends the following claim:

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

Configure the mapping as follows:

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:

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:

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

Sync mode determines when role mappings are evaluated and applied.

Force

Recommended for most installations.

With Force mode:

• Role mappings are evaluated on every login
• Changes in groups or roles at the identity provider are automatically reflected in instellix
• The identity provider remains the source of truth for role assignments

Example:

A user is removed from the Azure AD group "Finance".

At the next login, the Finance Manager role is automatically removed from the user in instellix.

Import

With Import mode:

• Role mappings are only evaluated when the user is first created through SSO
• Future changes in the identity provider do not automatically update roles in instellix

Use this mode only if role assignments should be managed manually after initial user creation.

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.