SCIM
On this page
This feature requires an Enterprise plan.
1.36.0
SCIM (System for Cross-domain Identity Management) is a specification for a client to provision users and groups on a server using a standard protocol. FusionAuth can consume SCIM formatted requests and act as the provisioningCreating, updating, and removing user accounts in a system, often by syncing the accounts from another source of truth. server in a SCIM client/server environment.
Common SCIM Use Cases#
SCIM lets you provision and deprovision users from external identity stores into FusionAuth. Here are some scenarios where this is useful:
- When your customers are themselves businesses with a centralized user data store. This is common when you are a business to business SaaS product. Customers want to control access to their instance of your application. They can do so by using SCIM to set up accounts for their users. When an employee leaves the customer's company, the employee account is automatically disabled in FusionAuth. Since SCIM is configured at the FusionAuth tenant level, this is an enterprise feature that FusionAuth makes it easy to offer.
- Ensuring your employees have access to your custom applications which use FusionAuth as an identity store. When a new employee is added into your corporate directory (Azure AD/Microsoft Entra ID, Okta, or otherwise), SCIM can provision them into the custom application, accelerating their onboarding experience. Equally important, when the employee departs, their access to the app also departs.
Specifications#
The links below include details about the SCIM specification as well as detailed information about the protocols and schemas.
- The RFC defining the overall concepts and requirements
- The RFC defining the protocol
- The RFC defining the core schema definitions
FusionAuth SCIM Support#
Any SCIM client can make requests to FusionAuth using the SCIM specification for defining Users and Groups. In this scenario FusionAuth acts as the provisioning server and can respond with SCIM compliant responses.
FusionAuth is not a SCIM compatible client, but if you are interested in similar functionality, review available Webhooks.
The FusionAuth SCIM Workflow#
The following diagram shows a SCIM client creating a FusionAuth User. The SCIM client first gets an access token from FusionAuth with a Client Credentials grant. The SCIM client then sends the create request with the access token. FusionAuth runs the request converter lambda before creating the User, and runs the response converter lambda before responding:
A SCIM client gets an access token, then creates a User, and FusionAuth runs a converter lambda on the request and on the response.
The SCIM client sends the create request to the SCIM User endpoint. The following example shows a create request:
{
"active": true,
"emails": [
{
"primary": true,
"type": "work",
"value": "example@fusionauth.io"
}
],
"externalId": "cc6714c6-286c-411c-a6bc-ee413cda1dbc",
"name": {
"familyName": "Doe",
"formatted": "John Doe",
"givenName": "John",
"honorificPrefix": "Mr.",
"honorificSuffix": "III",
"middleName": "William"
},
"password": "supersecret",
"phoneNumbers": [
{
"primary": true,
"type": "mobile",
"value": "303-555-1234"
}
],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Users"
],
"userName": "johnny123"
}FusionAuth represents each SCIM client and the SCIM server as an EntityA FusionAuth object that represents something other than a user, such as a server or an organization.. The SCIM client uses the SCIM client Entity credentials for the Client Credentials grant. FusionAuth rejects a request without a valid access token. For more information, see Client Credentials Grant.
The request converter lambda maps the SCIM request to a FusionAuth User. For example, the lambda can copy name.givenName from the example request to user.firstName. The response converter lambda maps the created User back to a SCIM User. Groups follow the same flow with the Group lambdas. Each resource type has a request converter lambda and a response converter lambda:
- SCIM User Request Converter Lambda
- SCIM User Response Converter Lambda
- SCIM Group Request Converter Lambda
- SCIM Group Response Converter Lambda
For the other SCIM endpoints, see the SCIM API Overview.
You can map SCIM attributes to FusionAuth properties any way you choose. The following tables show suggested mappings.
Suggested lambda mapping between SCIM Group schema extension and FusionAuth Group
| SCIM Group Attribute | FusionAuth Group and members property |
|---|---|
externalId |
This field is handled automatically so it does not need to be mapped in the lambdas |
displayName |
group.name |
members[x].value |
members[x].userId |
members[x].$ref |
members[x].data.$ref |
Suggested lambda mapping between SCIM User schema and FusionAuth User
| SCIM User Attribute | FusionAuth User property |
|---|---|
active |
user.active |
emails[x].value |
user.email |
externalId |
This field is handled automatically so it does not need to be mapped in the lambdas |
name.familyName |
user.lastName |
name.formatted |
user.fullName |
name.givenName |
user.firstName |
name.honorificPrefix |
user.data.honorificPrefix |
name.honorificSuffix |
user.data.honorificSuffix |
name.middleName |
user.middleName |
password |
user.password |
phoneNumbers[x].value |
user.mobilePhone |
userName |
user.userName |
The SCIM EnterpriseUser schema extends the SCIM User schema. An EnterpriseUser mapping uses the User mappings above plus the mappings below. Use the same approach for other SCIM schema extensions.
Suggested lambda mapping between SCIM EnterpriseUser schema extension and FusionAuth User where schema is urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
| SCIM EnterpriseUser Attribute | FusionAuth User property |
|---|---|
costCenter |
user.data.extensions[schema].costCenter |
department |
user.data.extensions[schema].department |
division |
user.data.extensions[schema].division |
employeeNumber |
user.data.extensions[schema].employeeNumber |
manager.displayName |
user.data.extensions[schema].managerDisplayName |
manager.$ref |
user.data.extensions[schema].managerURI |
Configuration#
To accept requests from SCIM clients, configure FusionAuth once:
- Create an Entity for the SCIM server and an Entity for each SCIM client. FusionAuth provides the [FusionAuth Default] SCIM server and [FusionAuth Default] SCIM client Entity Types. For more information, see SCIM Configuration.
- Create request converter and response converter lambdas for Users and for Groups. FusionAuth provides a default lambda of each type. The User lambdas also handle the Enterprise User extension. For more information, see SCIM Lambdas.
- Navigate to Tenants -> Your Tenant -> SCIM and enable Enable SCIM server.
- Select the SCIM client and SCIM server Entity Types. Then select a request lambda and a response lambda for Users, Enterprise Users, and Groups.
- Review the default Schemas JSON. When your SCIM client uses a different schema, replace the default JSON with your schema.
For a full list of fields, see the Tenant SCIM settings.
Permissions#
Below is a list of available permissions that can be included in your SCIM server entity type. Each controls access to a single API endpoint. You can choose to create as few or as many of these as you require. The names must match exactly.
| Name | Access to API |
|---|---|
scim:enterprise:user:create |
Create an Enterprise User |
scim:enterprise:user:read |
Retrieve an Enterprise User |
scim:enterprise:user:update |
Update an Enterprise User |
scim:enterprise:user:delete |
Delete an Enterprise User |
scim:group:create |
Create a Group |
scim:group:read |
Retrieve a Group |
scim:group:update |
Update a Group |
scim:group:delete |
Delete a Group |
scim:resource-types:read |
Retrieve Resource Types |
scim:schemas:read |
Retrieve Schemas |
scim:service-provider-config:read |
Retrieve Service Provider Configuration |
scim:user:create |
Create a User |
scim:user:read |
Retrieve a User |
scim:user:update |
Update a User |
scim:user:delete |
Delete a User |
FusionAuth SCIM API Endpoints#
In order to use FusionAuth as your SCIM provisioning server for SCIM clients, you will need to call the correct FusionAuth SCIM API endpoint. FusionAuth provides endpoints for retrieving, creating, replacing, and deleting SCIM Users, EnterpriseUsers, and Groups.
See the SCIM API Overview for details about the supported endpoints.
Adding Registrations#
With SCIM, users are provisioned. They are not registered for applications within FusionAuth.
Options to automatically add a registration to a new user include:
- Listen for the user.create.complete webhook and add the registration using an API call on the receiver.
- Make an API call registering the user to an application from the SCIM User Response Converter lambda which is called after the user is created. Ensure this idempotent as the lambda will be called any time the user is updated as well.
- If you enable self service registration for your application, and the user logs in to the application, they will be automatically registered for the application. Learn more.
SCIM Client Authentication#
FusionAuth requires the token from a completed Client Credentials grantAn OAuth 2.0 grant type in which a client uses its own credentials to obtain an access token for itself. for SCIM server authentication, as mentioned above. The token generated from the grant is used in the Authorization header as a Bearer token.
However, some SCIM clients can't dynamically complete a client credentials grant. Instead, they need a static authorization header value.
A long-lived token is a security risk. When your SCIM client supports the Client Credentials grant, use the grant instead.
FusionAuth can't revoke the token. Anyone who holds the token can call the SCIM API until the token expires.
To correctly integrate with such clients, do the following:
- Optionally change the JWT duration of the SCIM Client Entity TypeA category of Entity that defines the Permissions available to Entities of that type. to a larger value, such as a year, which is
31536000. The generated JWT will not be able to be revoked, so pick a duration that balances the security risk with the effort of updating the JWT in the SCIM client configuration (Azure AD/Microsoft Entra ID, Okta, etc). - Gather the Client Id of the SCIM Client, the Client Secret of the SCIM Client, and the SCIM Server Client Id. These values are available from the respective Entity details screen.
- Determine the SCIM permissions you want to grant the SCIM Client.
- Perform the Client Credentials grant manually using a tool like curl (see below for an example).
# This curl script grants all SCIM permissions to the client via the JWT.
# Edit the scope below if you need restricted permissions for this token.
SCIM_CLIENT_CLIENT_ID=...
SCIM_CLIENT_CLIENT_SECRET=...
SCIM_SERVER_CLIENT_ID=...
FUSIONAUTH_HOSTNAME=https://local.fusionauth.io # update this
SCIM_ENTITY_PERMISSIONS='scim:enterprise:user:create,scim:enterprise:user:update,scim:user:update,scim:group:read,scim:group:create,scim:enterprise:user:delete,scim:group:delete,scim:group:update,scim:user:delete,scim:enterprise:user:read,scim:user:create,scim:user:read'
curl -u $SCIM_CLIENT_CLIENT_ID:$SCIM_CLIENT_CLIENT_SECRET $FUSIONAUTH_HOSTNAME/oauth2/token \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scope=target-entity:$SCIM_SERVER_CLIENT_ID:$SCIM_ENTITY_PERMISSIONS"
This script will return JSON, including an access_token value.
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImd0eSI6WyJjbGllbnRfY3JlZGVudGlhbHMiXSwia2lkIjoiZWQzNzU4NThkIiwidXNlIjoic2NpbV9zZXJ2ZXIifQ.eyJhdWQiOiI3MGYxOTViYS0wNzI5LTRiMjAtYjA3YS1kYjhiNjkxNGFjYzQiLCJleHAiOjE2NjM4MDY1NDYsImlhdCI6MTY2MzgwMjk0NiwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIzY2ZiYTdjNi1jMTc4LTQxZTMtOWQ0Yi1hYzU1MjY2NmM2MzkiLCJqdGkiOiI0NWFkYzZhNC0wZDQzLTQ4Y2UtOGI4Ni01OGU2MTJkYmU3MzgiLCJzY29wZSI6InRhcmdldC1lbnRpdHk6NzBmMTk1YmEtMDcyOS00YjIwLWIwN2EtZGI4YjY5MTRhY2M0OnNjaW06ZW50ZXJwcmlzZTp1c2VyOmNyZWF0ZSxzY2ltOmVudGVycHJpc2U6dXNlcjp1cGRhdGUsc2NpbTp1c2VyOnVwZGF0ZSxzY2ltOmdyb3VwOnJlYWQsc2NpbTpncm91cDpjcmVhdGUsc2NpbTplbnRlcnByaXNlOnVzZXI6ZGVsZXRlLHNjaW06Z3JvdXA6ZGVsZXRlLHNjaW06Z3JvdXA6dXBkYXRlLHNjaW06dXNlcjpkZWxldGUsc2NpbTplbnRlcnByaXNlOnVzZXI6cmVhZCxzY2ltOnVzZXI6Y3JlYXRlLHNjaW06dXNlcjpyZWFkIiwidGlkIjoiMzA2NjMxMzItNjQ2NC02NjY1LTMwMzItMzI2NDY2NjEzOTM0IiwicGVybWlzc2lvbnMiOnsiNzBmMTk1YmEtMDcyOS00YjIwLWIwN2EtZGI4YjY5MTRhY2M0IjpbInNjaW06ZW50ZXJwcmlzZTp1c2VyOmNyZWF0ZSIsInNjaW06ZW50ZXJwcmlzZTp1c2VyOmRlbGV0ZSIsInNjaW06ZW50ZXJwcmlzZTp1c2VyOnJlYWQiLCJzY2ltOmVudGVycHJpc2U6dXNlcjp1cGRhdGUiLCJzY2ltOmdyb3VwOmNyZWF0ZSIsInNjaW06Z3JvdXA6ZGVsZXRlIiwic2NpbTpncm91cDpyZWFkIiwic2NpbTpncm91cDp1cGRhdGUiLCJzY2ltOnVzZXI6Y3JlYXRlIiwic2NpbTp1c2VyOmRlbGV0ZSIsInNjaW06dXNlcjpyZWFkIiwic2NpbTp1c2VyOnVwZGF0ZSJdfX0.ZHqaZAn9SFJ10HGfvQ1ACLS3ys8JjzH1W_Cmgq_hOOU",
"expires_in": 3599,
"scope": "target-entity:70f195ba-0729-4b20-b07a-db8b6914acc4:scim:enterprise:user:create,scim:enterprise:user:update,scim:user:update,scim:group:read,scim:group:create,scim:enterprise:user:delete,scim:group:delete,scim:group:update,scim:user:delete,scim:enterprise:user:read,scim:user:create,scim:user:read",
"token_type": "Bearer"
}
Place the access_token in the authorization header configuration field of your SCIM client.
When the token expires, FusionAuth rejects every request from the SCIM client, and provisioning stops. Before the token expires, run the Client Credentials grant again and replace the token in the SCIM client configuration. Write these renewal steps down for your team, and schedule a reminder before the expiration date.
Learn more about the Client Credentials grant.
Limits#
Our SCIM implementation does not support bulk operations using SCIM. Bulk operations on users, such as addition and deletion, are available via FusionAuth APIs, but are not currently supported via SCIM compatible endpoints. If this functionality is required, please file a GitHub issue explaining your use case.
FusionAuth does not support database search with SCIM. Instead, use Elasticsearch or Opensearch. If this functionality is important to you, let us know in the GitHub issue.
The list operation is limited to 10,000 users if you are using the Elasticsearch search engine. See Limitations for more information.
You cannot create a FusionAuth Registration for a user provisioned with SCIM directly during the provisioning process. See Adding Registrations for workarounds.
While it is not enforced, or a hard limitation, it is recommended to configure at most one SCIM client per tenant. While you can have multiple SCIM clients configured to provision users in one FusionAuth tenant, at the end of the day you only have one user data store in each tenant. Conflicts with creation, updates and deletion could happen; they won't be automatically resolved by FusionAuth. If you need multiple SCIM clients provisioning users into a single tenant, ensure you handle conflicts.
Okay, okay, you want multiple SCIM clients to provision users into a single FusionAuth tenant. Let's talk about the complexities. Imagine you have an Okta SCIM client provisioning users into a FusionAuth tenant and an Azure AD/Microsoft Entra ID SCIM client provisioning users into the same tenant.
Issues with this approach include:
- The user and group lambdas would have to include logic to differentiate between a user from Okta and a user from Azure AD/Microsoft Entra ID and handle the fields differently. The incoming SCIM request does not include information about the source, but you might be able to examine an email domain or a marker attribute to determine where the user was coming from.
- User collisions are not handled by FusionAuth. If the Okta SCIM client created an account for a user with the email address
richard@example.comin the tenant, then later the Azure AD SCIM client tried to create an account for a user with the email addressrichard@example.com, the second account creation would fail. One workaround would be for the lambda to resolve the collision, for example by adding a suffix or prefix to make the email address unique. - Update or deletion requests from the Okta SCIM client could modify users created by the Azure AD SCIM client and vice versa.
- The bearer access token used to authenticate each SCIM client can be different, but they must have the same lifetime, since that is configured at the Entity Type level. You couldn't have Okta's credentials be valid for a year but Azure AD's credentials be valid for six months.
Related
Learn about the APIs for provisioning SCIM Resources in FusionAuth using a SCIM Client.
Learn about the APIs for provisioning SCIM EnterpriseUsers in FusionAuth using a SCIM Client.
Learn about the APIs for provisioning SCIM Groups in FusionAuth using a SCIM Client.
Learn about the APIs for provisioning SCIM Users in FusionAuth using a SCIM Client.