How to Configure SCIM for User and Group Synchronization in authentik

Use authentik's native SCIM 2.0 provider to automatically provision, update, and deprovision users and groups in external applications using token or OAuth authentication with vendor-specific compatibility modes.

To configure SCIM in authentik, you create a SCIMProvider instance that connects your identity store to external services. The provider operates as a BackchannelProvider and integrates with authentik's outgoing sync framework. According to the authentik source code, this implementation supports full lifecycle management—create, update, and delete operations—through a flexible mapping system that transforms authentik objects into SCIM-compliant payloads.

Core Architecture of authentik's SCIM Implementation

The SCIM provider in authentik/providers/scim/models.py consists of several interconnected components that handle authentication, data transformation, and synchronization.

SCIMProvider Model

The central class SCIMProvider (lines 91-142 in authentik/providers/scim/models.py) stores all connection parameters and implements the sync logic. Key fields include:

• url: Base URL of the external SCIM service
• auth_mode: Authentication method (token or OAuth)
• token: Static bearer token for token-based auth
• oauth_source: Reference to an OpenID OAuth Source for OAuth flows
• group_filters: Many-to-many relationship limiting which groups sync
• compatibility_mode: Vendor-specific protocol adjustments

The model's save() method clears cached ServiceProviderConfig responses to ensure fresh configuration on each request (lines 86-92).

Authentication Modes

The SCIMAuthenticationMode enum (lines 71-77) defines three authentication methods:

1. TOKEN – Static bearer token authentication
2. SILENT_OAUTH – OAuth without user interaction
3. OAUTH – Interactive OAuth flow

Compatibility Modes

The SCIMCompatibilityMode enum (lines 79-88) handles vendor-specific deviations from the SCIM 2.0 specification. Supported targets include AWS, Slack, GitLab, and generic implementations.

Sync Clients and Mappings

The actual HTTP operations are performed by SCIMUserClient and SCIMGroupClient, referenced in the provider's client_for_model method (lines 174-179). These clients use SCIMMapping instances—property mappings that transform authentik users and groups into SCIM JSON payloads.

Creating a SCIM Provider

Method 1: Admin UI (Token Authentication)

The recommended path for most administrators uses the visual wizard documented in website/docs/add-secure-apps/providers/scim/create-scim-provider.md:

• Navigate to Applications → Applications → New Application
• Select SCIM as the provider type
• Enter the base URL (e.g., https://scim.example.com/v2/)
• Choose Token authentication mode
• Paste your service provider's SCIM token
• Complete the wizard

Method 2: Admin UI (OAuth Authentication)

For services requiring OAuth:

• First create an OpenID OAuth Source at Directory → Federation and Social login → New Source
• Configure the source with your external SCIM service's OAuth endpoints
• During SCIM provider creation, select your OAuth source in the Authentication Mode dropdown

Method 3: Programmatic Creation

For infrastructure-as-code or automated deployments, create providers directly via Django ORM:

from authentik.providers.scim.models import SCIMProvider, SCIMAuthenticationMode

provider = SCIMProvider.objects.create(
    name="My SCIM Provider",
    url="https://scim.example.com/v2/",
    auth_mode=SCIMAuthenticationMode.TOKEN,
    token="s3cr3t-token-here",
    verify_certificates=True,
)

Binding to Applications and Configuring Scope

Add as Backchannel Provider

After creation, bind the SCIM provider to your application:

• Edit the target application
• Navigate to Backchannel Providers
• Add the SCIM provider to the list

This binding triggers synchronization events when users or groups change.

Filter Synchronized Groups

Limit which groups sync using the group_filters many-to-many field. In the Admin UI, select specific groups; programmatically:

from authentik.core.models import Group

engineering = Group.objects.get(name="Engineering")
provider.group_filters.add(engineering)

Customizing Property Mappings

The default mappings ship in blueprints/system/providers-scim.yaml. Override or extend these by creating SCIMMapping instances with Python expressions:

from authentik.providers.scim.models import SCIMMapping

SCIMMapping.objects.create(
    name="Username as email",
    expression="""
        return {
            "userName": request.user.email,
            "emails": [{"value": request.user.email, "primary": True}]
        }
    """,
    provider=provider,
)

The expression receives request context and must return a dictionary matching the SCIM schema for users or groups.

Running Synchronization

Scheduled Sync

authentik automatically queues sync tasks when the provider is active. The scim_sync task processes the provider's configured queryset and invokes the appropriate client for each object.

Manual Sync (Testing)

Trigger immediate synchronization from the command line:

ak scim_sync --provider-id <provider-pk>

Use this during initial configuration or debugging to verify connectivity and mapping output.

Key Source Files Reference

File	Purpose
authentik/providers/scim/models.py	SCIMProvider, SCIMAuthenticationMode, SCIMCompatibilityMode, SCIMMapping classes
authentik/providers/scim/clients/users.py	SCIMUserClient for user CRUD operations
authentik/providers/scim/clients/groups.py	SCIMGroupClient for group CRUD operations
blueprints/system/providers-scim.yaml	Default user and group mappings
website/docs/add-secure-apps/providers/scim/create-scim-provider.md	Official UI documentation

Summary

• SCIM provider configuration centers on the SCIMProvider model in authentik/providers/scim/models.py, which stores connection settings and drives synchronization
• Authentication flexibility through token-based or OAuth modes (SCIMAuthenticationMode enum)
• Vendor compatibility handled via SCIMCompatibilityMode for services like AWS, Slack, and GitLab
• Data transformation uses SCIMMapping expressions to convert authentik objects to SCIM payloads
• Default mappings ship in blueprints/system/providers-scim.yaml and cover standard user and group attributes

Frequently Asked Questions

What SCIM version does authentik support?

authentik implements SCIM 2.0 according to the RFC 7643 and 7644 specifications. The SCIMProvider class and associated clients generate RFC-compliant requests. Use SCIMCompatibilityMode when target services deviate from the standard.

Can I sync only specific users or groups to my SCIM application?

Yes. For groups, use the group_filters many-to-many field on the provider to whitelist specific groups. For users, configure the application's policy bindings or use expression-based mappings to conditionally include users based on attributes.

How do I debug SCIM synchronization failures?

Run manual sync with ak scim_sync --provider-id <pk> and check authentik's logs. Enable compatibility mode if the target service returns schema errors. Verify authentication tokens or OAuth source configuration in the provider settings. The sync clients in authentik/providers/scim/clients/ log request details at debug level.

Is OAuth authentication required for SCIM providers?

No. Token authentication (SCIMAuthenticationMode.TOKEN) is the simplest option and works with any SCIM service that accepts static bearer tokens. OAuth modes are available for services that require delegated authorization or short-lived tokens.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}