Configure Inbound SCIM

Before you start

Your Auth0 plan or custom agreement must include Enterprise Connections to use this feature. To learn more, read Auth0's Pricing Page.

Postman must be installed on a local machine to test your Inbound SCIM connections.

SCIM is a protocol and schema standard used by enterprise organizations to provision, de-provision, and manage user identity-related information.

Auth0's Inbound SCIM feature supports B2B SaaS developer integrations with Enterprise identity providers. The following Auth0 connection types are currently supported: SAML, OpenID Connect, Okta Workforce Identity Cloud, and Microsoft Azure AD / Entra ID.

Enable Inbound SCIM for an Enterprise Connection

  1. Launch the Auth0 Dashboard, then choose the tenant you want to configure.

  2. Navigate to Authentication > Enterprise, then select from SAML, OpenID Connect, Okta Workforce, or Microsoft Azure AD.

  3. Choose an existing connection or create a new one using Create Connection.

  4. Under the Provisioning tab for your connection, toggle Sync user profile attributes at each login to Off, then switch Sync user profiles using SCIM to On.

  5. Select the Setup tab under Sync user profiles using SCIM to get the SCIM endpoint URL and SCIM tokens needed for testing with Postman.

Test with Postman

You can download the Postman collection below to test your SCIM configuration:

  1. Launch Postman, then select File > Import… and move the file scim_postman_collection.json into the import dialog box.

  2. Select the SCIM 2.0 Tests collection, then choose the Variables tab.

  3. Copy the SCIM Endpoint URL value from the Auth0 Dashboard and paste it into the Current Value field next to the SCIM-ENDPOINT-URL variable.

  4. In the Auth0 Dashboard choose Generate New Token, then pick Generate Token and select Copy and Close.

  5. Switch back to Postman, select the Authorization tab, and paste the token value into the Token field. 

  6. Choose Save.

  7. Run the tests in the order shown, starting with the POST command and finishing with DELETE. The result of each user operation is in your Auth0 Dashboard under User Management > Users and in the tenant logs under Monitoring > Logs.

To test with specific identity providers, see Configure Inbound SCIM for Identity Providers using SAML or OpenID.

Supported SCIM Operations

Auth0 supports the following SCIM 2.0 operations for managing users:

Command Description
POST Creates a user in Auth0 with attributes from the SCIM 2.0 core schema and enterprise schema extension, described in RFC7644 Section 3.3.
GET Retrieves a user that has already been created in Auth0, using their user_id value in Auth0 and described in RFC7644 Section 3.4.1.
PUT Replaces a user in Auth0 with attributes from the SCIM 2.0 core schema and enterprise schema extension, described in RFC7644 Section 3.5.1.
PATCH Updates a user in Auth0 with attributes from the SCIM 2.0 core schema and enterprise schema extension, described in RFC7644 Section 3.5.2.
DELETE Deletes a user in Auth0, using their user_id value in Auth0, described in RFC7644 Section 3.6.
SEARCH Searches for a user in Auth0 using a SCIM filter, described in RFC7644 Section 3.4.2. Supported operators are Equals (EQ), and (AND), and or (OR).
PUT (Deactivate) Replaces a user stored in Auth0 and sets the SCIM active attribute to false, which results in the user being blocked in Auth0.
PATCH (Deactivate) Updates a user stored in Auth0 and sets the SCIM active attribute to false, which results in the user being blocked in Auth0.

Auth0 uses the SCIM 2.0 core schema for user resources and Enterprise schema for user resources, as well as client authentication bearer tokens for broad compatibility with multiple Enterprise identity providers.

SCIM endpoints and tokens

Each enterprise customer gets a connection-specific SCIM endpoint and token that allows them to provision, de-provision, and manage their user accounts stored in the Auth0 tenant.

The endpoints and tokens are visible and configurable in the Auth0 Dashboard at Authentication > Enterprise > [connecton-type] > [your-connection] > Provisioning >  Sync user profiles using SCIM >  Setup.

Dashboard screenshot of SCIM setup

The SCIM Endpoint URL allows SCIM clients to manage user accounts stored in Auth0 for a given identity provider.

The Generate New Token option generates up to two active tokens for this SCIM endpoint, allowing the token used by the SCIM client to be updated without downtime. Tokens may also be revoked on this screen by choosing Delete.

Dashboard screen for the SCIM token settings

The following token generation settings are available:

  • No expiration date: Select whether the token expires or not.

  • Expiration date in seconds: if the token has no expiration date, you can choose an expiration time for the token. When the token expires, the SCIM endpoint will return an error response the next time it is used. The minimum allowed expiration time is 900 seconds.

  • List of permissions (scopes): details which SCIM operations may be performed using this token. The available permissions are:

    • get:users - Allows users to be retrieved and searched.

    • post:users - Allows users to be created

    • put:users - Allows users to be updated using the PUT method.

    • patch:users - Allows users to be updated using the PATCH method.

    • delete:users - Allows users to be deleted.

Attribute mapping

Each new connection uses the default attribute map found in the Auth0 Dashboard at Authentication > Enterprise > [connecton-type] > [your-connection] > Provisioning >  Sync user profiles using SCIM >  Mapping, where the map can be edited and customized to fit your connection's needs.

Core SCIM user attributes defined RFC 7643 sections 3.1, 4.1,  and 4.3 may be used.

Notes
One-to-one mapping A selected SCIM attribute (or sub-attribute) can only be mapped to one Auth0 attribute.
Sub-attribute mapping Sub-attribute values within multi-value SCIM attributes such as emails and phoneNumbers can be referenced using SCIM filter syntax with the eq operator. See the default attribute maps for examples.
Unmappable attributes The SCIM id and meta attributes cannot be mapped, as they are only sent by Auth0 in the SCIM protocol responses. The id value in SCIM responses is always set to the Auth0 user_id, and the SCIM password attribute is not usable for Enterprise connections.
Omitting SCIM attributes If a specific SCIM attribute is not configured to be handled in your attribute map, it will be ignored in all SCIM requests and responses.

These SCIM attributes can be mapped to Auth0 root and metadata attributes on the user profile.

Notes
One-to-one mapping A selected Auth0 attribute can only be mapped to one SCIM attribute.
Root attribute mapping When mapping to root attributes, note that only the root attributes listed in User profile attributes can be searched using a SCIM query. If you need an attribute to be searchable that is not in this list, place it in app_metadata.
Metadata attribute mapping The use of user_metadata is allowed, but generally not recommended for synchronized attributes as it is intended to store attributes that can be edited directly by the end user. Use app_metadata or root attributes instead.
Blocked attribute behavior The mapping to the Auth0 blocked attribute has a special behavior when it is mapped to the SCIM active attribute. When active contains a value of true or false, Auth0 reverses the value and sets Auth0 blocked attribute to false or true, respectively.

Auth0 also allows you to provision attributes using SCIM in parallel with attributes provisioned during login. For more information, see Sync additional attributes at login below.

Logs and outbound notifications

You can view the full details of all the SCIM requests that Auth0 receives in the Monitoring > Logs section of the Auth0 Dashboard. In addition, you can integrate with Custom Log Streams to be notified when a user is created, updated, or deleted using SCIM.

Session revocation and backchannel logout

When Auth0 receives a SCIM message to deactivate and block a user, it terminates all Auth0 sessions for the user, revokes refresh tokens, and (if configured) triggers OpenID Connect backchannel logout for your applications.

Deployment guidelines

Leverage integration galleries for streamlined setup

To give your customers a tailored experience for setting up both SCIM and SSO, consider listing your application in the Okta Integration Network and other workforce identity provider integration galleries that you plan to integrate with.

Test SCIM in lower-level environments first

Do not enable SCIM in a production Auth0 tenant before thoroughly testing your integration in a development or staging Auth0 tenant.

Send SCIM tokens securely

Never send SCIM tokens in plaintext, over email, or via insecure channels. Use a secure communication service like SendSafely or integrate your app's self-service console with the Auth0 Management API to issue SCIM tokens directly to your customers.

Information exchange

When providing an Auth0 SCIM endpoint to your customer, they will require the following information to use it successfully:

  • The SCIM endpoint URL for the Auth0 connection

  • The SCIM token required for the SCIM endpoint URL

These are also recommended:

  • The list of SCIM attributes supported for the Auth0 connection, as configured in your SCIM attribute map

  • Any additional instructions required to configure their SCIM client to work with your SCIM configuration. For Okta Workforce and Microsoft Entra ID setup guidance, see Configure Inbound SCIM for Identity Providers using SAML or OpenID

Advanced topics 

Sync additional attributes at login

If you are integrating with an identity provider that does not support the same set of user attributes across SAML/OIDC, and SCIM, you can access the additional attributes by enabling Sync user profile attributes at login in parallel with SCIM provisioning.

When Sync user profile attributes at login is enabled, all root attributes on the user profile are overwritten each time a user logs in. To avoid potential conflicts between SCIM and login sync, follow these guidelines:

  • Ensure common Auth0 root attributes like email and username are mapped in your SAML or OpenID Connect attribute map if they are also present in your SCIM attribute map.

  • In your SCIM attribute map, map all of the other SCIM attributes (except the active attribute) to values inside the Auth0 app_metadata attribute.

Sync roles

Auth0 supports syncing the SCIM 2.0 roles user attribute as defined in RFC7643. To accept roles, ensure the SCIM attribute map for your connection maps the SCIM roles attribute to an Auth0 user attribute like app_metadata.roles.

To learn how to sync application-specific roles from Okta Workforce Identity Cloud, read How to Add Multi-value Roles in SCIM Cloud Integration. For Microsoft Entra ID roles, read Customize user provisioning attribute-mappings for SaaS applications in Microsoft Entra ID.

Sync groups

Auth0 does not support a /groups endpoint for provisioning full group objects and group memberships as defined in RFC7644 Section 3.2. However, if an identity provider supports sending a list of groups over SAML or OpenID Connect, read the previous section for guidelines on how to sync attributes at login.

Organizations

For SCIM-provisioned users to become members of an Organization, the connection must be configured to Enable Auto-Membership as described in Grant Just-In-Time Membership to an Organization Connection.

Account linking

When using user account linking, the SCIM-provisioned user account must be set as the primary user account. Setting as a secondary account will change the SCIM id attribute which goes against the SCIM 2.0 core schema specification. Account linking Enterprise user accounts to social and personal user accounts is not recommended.

Learn more