Role mapping and JIT provisioning

Overview

Just-in-time (JIT) provisioning automatically creates user accounts when users authenticate through SSO for the first time. Role mapping assigns application roles based on groups or attributes from your identity provider, eliminating manual user management.

Key features

Automatic user creation: Create accounts on first SSO login
Default role assignment: Assign default roles to all new users
Group-to-role mapping: Map IdP groups to application roles
Attribute-based assignment: Use custom attributes for role decisions
Dynamic updates: Update roles on each login based on current IdP data

Configuring JIT provisioning

Enable JIT provisioning

JIT provisioning is enabled by default for all SSO providers. When a user authenticates for the first time:

The application checks if the user exists
If not, a new user account is created
Default roles are assigned
Group-to-role mappings are applied
User attributes are populated from IdP claims

Default roles

Configure default roles that are assigned to all new users:

Navigate to provider settings

Go to Admin → SSO Providers and select your provider

Configure default roles

In the “Role Mapping” section, select default roles:

Default roles: viewer, user

Save configuration

Save the provider settings

All users created through this provider will receive these roles automatically.

Group-to-role mapping

Map identity provider groups to application roles for automatic role assignment.

Configuration

Access role mapping settings

In your provider configuration, go to the “Role Mapping” section

Add group mappings

Create mappings between IdP groups and application roles:

IdP Group → Application Role
admin-group → admin
developers → developer
support-team → support

Configure mapping behavior

Choose how mappings are applied:

Additive: Add mapped roles to default roles
Replace: Replace default roles with mapped roles
Merge: Combine all roles and remove duplicates

Save and test

Save the configuration and test with a user account

Mapping examples

OIDC group mapping

For OIDC providers that include groups in the groups claim:

{
  "mappings": [
    {
      "group": "okta-admins",
      "role": "admin"
    },
    {
      "group": "okta-developers",
      "role": "developer"
    },
    {
      "group": "okta-viewers",
      "role": "viewer"
    }
  ]
}

SAML attribute mapping

For SAML providers using the groups or memberOf attribute:

{
  "attribute": "groups",
  "mappings": [
    {
      "value": "CN=Administrators,OU=Groups,DC=company,DC=com",
      "role": "admin"
    },
    {
      "value": "CN=Developers,OU=Groups,DC=company,DC=com",
      "role": "developer"
    }
  ]
}

Multiple group mapping

Map multiple IdP groups to a single application role:

{
  "mappings": [
    {
      "groups": ["admin-group", "super-admin", "root"],
      "role": "admin"
    },
    {
      "groups": ["dev-team", "engineering"],
      "role": "developer"
    }
  ]
}

Wildcard mapping

Use wildcards for pattern matching:

{
  "mappings": [
    {
      "pattern": "admin-*",
      "role": "admin"
    },
    {
      "pattern": "*-developers",
      "role": "developer"
    }
  ]
}

Role synchronization

Roles are synchronized every time a user logs in:

Fetch current groups from identity provider
Apply group-to-role mappings
Update user’s roles in the application
Remove roles that are no longer mapped

Role synchronization ensures users always have the correct permissions based on their current IdP group memberships.

Manual sync

Administrators can manually trigger role synchronization:

Go to Admin → User Management
Select a user
Click “Sync Roles from SSO”

This fetches the latest group information from the identity provider and updates the user’s roles.

Advanced configuration

Conditional role assignment

Assign roles based on multiple conditions:

{
  "conditions": [
    {
      "attribute": "department",
      "value": "Engineering",
      "groups": ["senior-engineers"],
      "role": "senior-developer"
    },
    {
      "attribute": "department",
      "value": "Engineering",
      "role": "developer"
    }
  ]
}

Role hierarchy

Define role hierarchies to automatically grant dependent roles:

{
  "hierarchy": {
    "admin": ["developer", "viewer"],
    "developer": ["viewer"]
  }
}

When a user is assigned the admin role, they automatically receive developer and viewer roles as well.

Custom attribute mapping

Use custom IdP attributes for role assignment:

{
  "attribute_mappings": [
    {
      "attribute": "jobTitle",
      "mappings": [
        {
          "value": "Engineering Manager",
          "role": "admin"
        },
        {
          "value": "Software Engineer",
          "role": "developer"
        }
      ]
    }
  ]
}

Provider-specific configuration

OIDC providers

Ensure your OIDC provider includes groups in the token:

Request the groups scope:
```
Scopes: openid profile email groups
```
Configure your IdP to include groups in the ID token or userinfo response
Verify groups are present in the token by checking audit logs

SAML providers

Configure group attributes in your SAML provider:

Add a group attribute statement in your IdP:

<Attribute Name="groups">
  <AttributeValue>admin-group</AttributeValue>
  <AttributeValue>developer-group</AttributeValue>
</Attribute>

Configure the attribute name in your provider settings:
```
Group attribute: groups
```
Test the integration to verify groups are received

OAuth2 providers

For OAuth2 providers, groups may need to be fetched from a separate endpoint:

Configure a custom groups endpoint (if supported)
Map the response field containing groups
Test with a user account that has group memberships

User attribute mapping

In addition to roles, map other user attributes from your identity provider:

IdP Attribute	Application Field	Description
`email`	Email	User’s email address
`given_name`	First name	User’s first name
`family_name`	Last name	User’s last name
`name`	Display name	User’s full name
`picture`	Avatar URL	User’s profile picture
`phone_number`	Phone	User’s phone number
`department`	Department	User’s department
`title`	Job title	User’s job title

Custom field mapping

Map custom IdP attributes to application fields:

{
  "custom_mappings": {
    "employee_id": "externalId",
    "cost_center": "metadata.costCenter",
    "manager_email": "metadata.manager"
  }
}

Troubleshooting

Groups not syncing

Problem: User groups from IdP aren’t being mapped to roles Solution:

Verify the groups scope is requested (OIDC)
Check that your IdP includes groups in the assertion (SAML)
Review audit logs to see what groups are received
Ensure group attribute name matches your IdP’s configuration
Some IdPs require additional configuration to include groups

Roles not updating

Problem: User roles don’t update when IdP groups change Solution:

Roles only update on login - ask the user to log out and back in
Use manual role sync from the user management page
Verify role synchronization is enabled in provider settings
Check audit logs for role update events

Wrong roles assigned

Problem: Users receive incorrect roles Solution:

Review your group-to-role mapping configuration
Check for typos in group names (case-sensitive)
Verify the mapping behavior (additive vs. replace)
Test with a known user account and review audit logs
Ensure group names match exactly between IdP and application

Default roles not applied

Problem: New users don’t receive default roles Solution:

Verify default roles are configured in provider settings
Check that JIT provisioning is enabled
Review user creation logs in audit logs
Ensure the roles exist in the application

Security considerations

Principle of least privilege

Assign minimal default roles and use group mapping for elevated permissions. Don’t give all users admin access by default.

Regular audits

Regularly review role mappings and user permissions to ensure they align with your security policies.

Group naming conventions

Use clear, consistent group names in your IdP to make role mapping easier to manage.

Test before deploying

Always test role mappings with test accounts before enabling for all users.

Monitor role changes

Review audit logs for unexpected role changes or privilege escalations.

Best practices

Use group-based access control

Manage permissions through IdP groups rather than individual user assignments. This centralizes access control and makes it easier to audit.

Document your mappings

Keep documentation of your group-to-role mappings for future reference and onboarding.

Implement role hierarchy

Use role hierarchies to simplify permission management and reduce configuration complexity.

Regular synchronization

Encourage users to log out and back in periodically to ensure their roles stay synchronized.

Separate environments

Use different group mappings for development, staging, and production environments.

Next steps

User management

Manage users and manually adjust roles

Audit logging

Monitor role changes and user provisioning events

OIDC setup

Configure OIDC providers with group support

SAML setup

Set up SAML with group attributes

Getting started

App features

Development

Authentication

Third party providers

Knowledge Base

​Overview

​Key features

​Configuring JIT provisioning

​Enable JIT provisioning

​Default roles

​Group-to-role mapping

​Configuration

​Mapping examples

​OIDC group mapping

​SAML attribute mapping

​Multiple group mapping

​Wildcard mapping

​Role synchronization

​On login

​Manual sync

​Advanced configuration

​Conditional role assignment

​Role hierarchy

​Custom attribute mapping

​Provider-specific configuration

​OIDC providers

​SAML providers

​OAuth2 providers

​User attribute mapping

​Custom field mapping

​Troubleshooting

​Groups not syncing

​Roles not updating

​Wrong roles assigned

​Default roles not applied

​Security considerations

​Best practices

​Next steps

User management

Audit logging

OIDC setup

SAML setup

Overview

Key features

Configuring JIT provisioning

Enable JIT provisioning

Default roles

Group-to-role mapping

Configuration

Mapping examples

OIDC group mapping

SAML attribute mapping

Multiple group mapping

Wildcard mapping

Role synchronization

On login

Manual sync

Advanced configuration

Conditional role assignment

Role hierarchy

Custom attribute mapping

Provider-specific configuration

OIDC providers

SAML providers

OAuth2 providers

User attribute mapping

Custom field mapping

Troubleshooting

Groups not syncing

Roles not updating

Wrong roles assigned

Default roles not applied

Security considerations

Best practices

Next steps