# How to Configure SCIM for User and Group Synchronization in authentik

> Configure SCIM in authentik for seamless user and group synchronization with external apps. Automate provisioning, updates, and deprovisioning using token or OAuth.

- Repository: [Authentik Security/authentik](https://github.com/goauthentik/authentik)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/goauthentik/authentik/blob/main/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`](https://github.com/goauthentik/authentik/blob/main/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`](https://github.com/goauthentik/authentik/blob/main/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:

```python
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:

```python
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`](https://github.com/goauthentik/authentik/blob/main/blueprints/system/providers-scim.yaml). Override or extend these by creating `SCIMMapping` instances with Python expressions:

```python
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:

```bash
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`](https://github.com/goauthentik/authentik/blob/main/authentik/providers/scim/models.py) | `SCIMProvider`, `SCIMAuthenticationMode`, `SCIMCompatibilityMode`, `SCIMMapping` classes |
| [`authentik/providers/scim/clients/users.py`](https://github.com/goauthentik/authentik/blob/main/authentik/providers/scim/clients/users.py) | `SCIMUserClient` for user CRUD operations |
| [`authentik/providers/scim/clients/groups.py`](https://github.com/goauthentik/authentik/blob/main/authentik/providers/scim/clients/groups.py) | `SCIMGroupClient` for group CRUD operations |
| [`blueprints/system/providers-scim.yaml`](https://github.com/goauthentik/authentik/blob/main/blueprints/system/providers-scim.yaml) | Default user and group mappings |
| [`website/docs/add-secure-apps/providers/scim/create-scim-provider.md`](https://github.com/goauthentik/authentik/blob/main/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`](https://github.com/goauthentik/authentik/blob/main/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`](https://github.com/goauthentik/authentik/blob/main/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.