Skip to main content

SCIM Source

The SCIM source allows other applications to directly create users and groups within authentik. SCIM provides a predefined schema for users and groups, along with a RESTful API, to enable automatic user provisioning and deprovisioning. SCIM is supported by applications such as Microsoft Entra ID, Google Workspace, and Okta.

The base SCIM URL is in the format of https://authentik.company/source/scim/<source-slug>/v2. Authentication is done via Bearer tokens that are generated by authentik. When an SCIM source is created, a service account is created and a matching token is provided.

First steps​

To set up an SCIM source, log in to authentik as an administrator. Navigate to Directory->Federation & Social login, and click on Create. Select the SCIM Source type, and give the source a name.

After the source is created, click on the name of the source in the list, and you will see the SCIM Base URL which is used by the SCIM client. Use the Click to copy token button to copy the token which is used by the client to authenticate SCIM requests.

Supported Options & Resource types​

/v2/Users​

Endpoint to list, create, update and delete users.

/v2/Groups​

Endpoint to list, create, update and delete groups.

There are also /v2/ServiceProviderConfig and /v2/ResourceTypes, which are used by SCIM-enabled applications to find out which features authentik supports.

Trust model and security​

The SCIM source Bearer token is a high-trust provisioning credential. Anyone who can use the token can manage users and groups through the SCIM endpoints for that source. Treat it like a secret with roughly the same sensitivity as an administrative provisioning integration, not like a narrowly scoped API key.

By default, authentik applies the following behavior for inbound SCIM requests:

User and group correlation​

On create and update, authentik may correlate SCIM resources to existing directory objects in the same tenant:

  • Users are matched by userName across the entire tenant, not only users already linked to this SCIM source.
  • Groups are matched by displayName (mapped to the group name) across the entire tenant, not only groups already linked to this SCIM source.

If a matching object exists, the SCIM source adopts and updates that object.

Group membership​

Group members operations accept any user UUID in the tenant. authentik does not require that member users were originally created by, or are exclusively managed by, the same SCIM source.

Deprovisioning (DELETE)​

SCIM DELETE on a user or group removes the underlying authentik User or Group object, not only the SCIM source link. This applies to correlated objects as well as objects created through SCIM.

Default bootstrap layout​

Fresh installs create a superuser group named authentik Admins (is_superuser=true) and an initial admin user. Because group correlation is tenant-wide, a SCIM token holder can interact with that group if they use the same displayName, including changing membership or deleting the group after correlating to it.

Recommendations​

  • Restrict network access to SCIM endpoints where possible.
  • Rotate and revoke SCIM tokens when an IdP integration is decommissioned.
  • Do not share SCIM tokens across untrusted systems.
  • If you do not require tenant-wide correlation, enable Managed objects only on the SCIM source (see below).

Managed objects only​

SCIM sources support an optional Managed objects only setting (managed_objects_only). When enabled:

  • Users and groups are not correlated to existing tenant objects by name during create.
  • Group membership changes are limited to users managed by the same SCIM source.
  • SCIM DELETE removes only the SCIM source link; the underlying user or group is retained.

This mode is recommended for integrations where the IdP should only manage objects it created through SCIM, or where tenant-wide correlation is not desired.

SCIM source property mappings​

See the overview for information on how property mappings work.

Expression data​

Each top-level SCIM attribute is available as a variable in the expression. For example, given a SCIM request with the payload of

{
    "schemas": [
        "urn:scim:schemas:core:2.0",
        "urn:scim:schemas:extension:enterprise:2.0"
    ],
    "userName": "foo.bar",
    "name": {
        "familyName": "bar",
        "givenName": "foo",
        "formatted": "foo.bar"
    },
    "emails": [
        {
            "value": "foo.bar@authentik.company",
            "type": "work",
            "primary": true
        }
    ],
    "title": "",
    "urn:scim:schemas:extension:enterprise:2.0": {
        "department": ""
    }
}

The following variables are available in the expression:

  • schemas as a list of strings

  • userName as a string

  • name as a dictionary

  • emails as a dictionary

  • title as a string

  • urn_scim_schemas_extension_enterprise_2_0 as a dictionary

    info

    Top-level keys which include symbols not allowed in Python syntax are converted to _.