FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    SCIM

    FusionAuth Reactor logo

    This feature is only available in the Enterprise plan. Please visit our pricing page to learn more.

    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.

    • Common SCIM Use Cases

    • Specifications

    • FusionAuth SCIM Support

      • The FusionAuth SCIM Workflow

    • Configuration

    • FusionAuth SCIM API Endpoints

    • Adding Registrations

    • SCIM Client Authentication

    • Limits

    Related Posts

    • Announcing FusionAuth 1.40

    • Announcing FusionAuth 1.39

    • What is SCIM?

    • Announcing FusionAuth 1.36

    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, 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.

    • Overview of the specification and links to all relevant RFCs

    • 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

    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.

      • SCIM Group Request Converter Lambda

      • SCIM User Request Converter Lambda

    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.

      • SCIM Group Response Converter Lambda

      • SCIM User Response Converter Lambda

    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.

    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 from the user response complete lambda. 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 grant 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.

    To correctly integrate with such clients, do the following:

    • Optionally change the JWT duration of the SCIM Client Entity 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, Okta, etc).

    • Gather the SCIM Client Client Id, the SCIM Client Client Secret, 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).

    Performing the Client Credentials grant for a SCIM Client.
    
    # 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.

    Sample JSON returned from the Client Credentials grant.
    
    {
      "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, the SCIM integration will fail. Document how to regenerate the token and update the client configuration.

    Learn more about the Client Credentials grant.

    Limits

    The current SCIM implementation does not support:

    • Bulk operations

    Bulk API operations 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.

    The list operation is limited to 10,000 users if you are using the Elasticsearch search engine. This GitHub issue discusses this limitation.

    You cannot create a FusionAuth Registration for a user provisioned with SCIM. If you need to register the user for one or more Applications, you have a few options. You may:

    • use the SCIM User Request Converter Lambda.

    • use the user.create.complete webhook.

    Either works. The correct choice depends on if you want to do the processing within FusionAuth using a lambda or using an external server.

    While it is not enforced, or a hard limitation, it is recommended to configure at most one SCIM server per tenant.

    While you can have multiple SCIM servers per configured within one tenant, at the end of the day you only have one user data store per tenant.

    Conflicts with creation, updates and deletion could happen; they won’t be automatically resolved by FusionAuth. If you need to use multiple SCIM servers, ensure your clients can handle such conflicts.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates