SCIM

    Overview

    This functionality has been available since 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 provisioning server in a SCIM client/server environment.

    Follow the links below for details about the SCIM specification and detailed information about the protocols and schemas:

    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

    This is an example of a basic interaction between an external SCIM client provisioning request to create a FusionAuth User:

    1. The client would send a SCIM compliant request to the SCIM User endpoint /api/scim/resource/v2/Users. Other SCIM API endpoints are also available.

      Example User Create Request JSON
      {
  "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"
}

    2. FusionAuth will authenticate the incoming request to ensure the request is from a known SCIM client. Each SCIM client and server instance is represented as an Entity and will authenticate using a Client Credentials Grant. An example client credentials grant using Entities.

    3. FusionAuth will call the assigned incoming request lambda, passing the SCIM request data and a FusionAuth User object. The lambda is responsible for converting the incoming SCIM request data into a FusionAuth User object. For example, the name.givenName property shown above could be mapped to user.firstName.

    4. FusionAuth will attempt to create the FusionAuth User using the mapped object from the incoming request lambda.

    5. Upon successful creation of the User, FusionAuth will call the outgoing response lambda, passing the newly created FusionAuth User and the SCIM response. The outgoing lambda is responsible for mapping the FusionAuth User properties to the appropriate SCIM representation.

    The lambdas will need to map the SCIM data to the appropriate FusionAuth object property. Below are some suggested strategies, but the data can be mapped in any way you choose.

    Table 1. 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
    Table 2. 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.honorifixPrefix

    User.data.honorificPrefix

    name.honorifixSuffix

    User.data.honorificSuffix

    name.middleName

    User.middleName

    password

    User.password

    name.givenName

    User.firstName

    phoneNumbers[x].value

    User.mobilePhone

    userName

    User.userName

    The SCIM EnterpriseUser schema is an extension of the SCIM User schema so the suggested mappings would include the ones from Table 1 above and the additional mappings in Table 2 below. This is the suggested mapping strategy for all SCIM schema extensions.

    Table 3. 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

    In order for FusionAuth to accept requests from SCIM clients, you need to perform a few one time configuration steps.

    • You need to enable SCIM support for your tenant.

    • You need to define your incoming request and outgoing response lambdas for each the supported SCIM resource types (User, Enterprise User, Group)

    • You will need to verify that the default SCIM schemas provided match your desired SCIM schema for each of the SCIM resource types or provide your own.

    • You will need an Entity defined for each SCIM client and SCIM Server. Default entity types are provided for you. You can create the entities from those default types or create your own types.

    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.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo