SCIM 2.0 Provisioning Guide

Automate user provisioning and deprovisioning from external identity management systems using SCIM 2.0.

Automate user provisioning and deprovisioning from external identity management systems using SCIM 2.0.

See ADR-0038 for implementation details.

Overview

SCIM (System for Cross-domain Identity Management) enables:

• Automated User Provisioning: Create users from Azure AD, Okta, Google Workspace
• Attribute Synchronization: Keep user profiles in sync
• Deprovisioning: Automatically disable users when removed from source
• Group Management: Sync group memberships
• Bulk Operations: Provision hundreds of users at once

SCIM Provisioning Lifecycle Flow

Supported Endpoints

Users

• POST /scim/v2/Users - Create user
• GET /scim/v2/Users/{id} - Get user
• PUT /scim/v2/Users/{id} - Replace user
• PATCH /scim/v2/Users/{id} - Update user (partial)
• DELETE /scim/v2/Users/{id} - Deactivate user
• GET /scim/v2/Users?filter=... - Search users

Groups

• POST /scim/v2/Groups - Create group
• GET /scim/v2/Groups/{id} - Get group
• PATCH /scim/v2/Groups/{id} - Update group membership

Quick Start

1. Enable SCIM

## .env
SCIM_ENABLED=true
SCIM_BASE_URL=https://api.example.com/scim/v2
SCIM_AUTHENTICATION=jwt

2. Create Service Principal for SCIM

curl -X POST https://api.example.com/api/v1/service-principals \
  -H "Authorization: Bearer ADMIN_JWT" \
  -d '{
    "name": "SCIM Provisioning Client",
    "description": "Azure AD SCIM provisioning",
    "authentication_mode": "client_credentials"
  }'

## Save the client_secret returned

3. Configure External System

Configure your identity provider to use SCIM:

Azure AD:

1. Enterprise Applications → Your App → Provisioning
2. Set Tenant URL: https://api.example.com/scim/v2
3. Set Secret Token: Bearer <JWT_TOKEN>
4. Test connection
5. Enable provisioning

Okta:

1. Applications → Your App → Provisioning → Integration
2. Set SCIM Base URL: https://api.example.com/scim/v2
3. Set Authentication: OAuth2 Client Credentials
4. Set Client ID/Secret from service principal

SCIM Examples

Create User

curl -X POST https://api.example.com/scim/v2/Users \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[e-mail]",
    "name": {
      "givenName": "Alice",
      "familyName": "Smith"
    },
    "emails": [{
      "value": "[e-mail]",
      "primary": true
    }],
    "active": true
  }'

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "user-uuid-123",
  "userName": "[e-mail]",
  "name": {
    "givenName": "Alice",
    "familyName": "Smith"
  },
  "emails": [{
    "value": "[e-mail]",
    "primary": true
  }],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2025-01-28T00:00:00Z",
    "lastModified": "2025-01-28T00:00:00Z"
  }
}

Update User (PATCH)

curl -X PATCH https://api.example.com/scim/v2/Users/user-uuid-123 \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      }
    ]
  }'

Deactivate User (DELETE)

curl -X DELETE https://api.example.com/scim/v2/Users/user-uuid-123 \
  -H "Authorization: Bearer JWT_TOKEN"

Search Users

curl -X GET 'https://api.example.com/scim/v2/Users?filter=userName eq "[e-mail]"' \
  -H "Authorization: Bearer JWT_TOKEN"

Create Group

curl -X POST https://api.example.com/scim/v2/Groups \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "Engineering",
    "members": [
      {"value": "user-uuid-123", "display": "Alice Smith"}
    ]
  }'

Enterprise User Extension

SCIM supports enterprise-specific attributes:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "[e-mail]",
  "name": {"givenName": "Alice", "familyName": "Smith"},
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "12345",
    "department": "Engineering",
    "organization": "Acme Corp",
    "division": "Product",
    "costCenter": "CC-100",
    "manager": {
      "value": "user-uuid-456",
      "displayName": "Bob Manager"
    }
  }
}

These map to Keycloak user attributes:

• employeeNumber → employeeNumber
• department → department
• organization → organization

OpenFGA Synchronization

When users are provisioned via SCIM, roles are automatically synced to OpenFGA:

SCIM Create User → Keycloak User Created → Event Listener
  → sync_user_to_openfga() → OpenFGA Tuples

Default roles assigned: ["user"]

Configure in .env:

SCIM_AUTO_SYNC_TO_OPENFGA=true
SCIM_DEFAULT_ROLES=user,premium  # Comma-separated

Monitoring

Prometheus Metrics

## SCIM operations rate
rate(scim_operations_total{operation="create"}[5m])

## SCIM errors
rate(scim_operations_errors_total[5m])

## Provisioning latency
histogram_quantile(0.95, scim_operation_duration_seconds_bucket)

Audit Logs

All SCIM operations are logged:

{
  "timestamp": "2025-01-28T12:00:00Z",
  "operation": "scim.create_user",
  "scim_client": "service:azure-ad-scim",
  "user_id": "user-uuid-123",
  "username": "[e-mail]",
  "result": "success"
}

Troubleshooting

401 Unauthorized

Issue: SCIM client cannot authenticate

Solutions:

• Verify JWT token is valid
• Check service principal credentials
• Ensure token not expired (refresh if needed)

409 Conflict (User Exists)

Issue: User already exists in Keycloak

Solutions:

• Use PATCH to update instead of POST
• Check userName field (must be unique)
• Query before creating: GET /scim/v2/Users?filter=userName eq "[e-mail]"

Attribute Not Mapped

Issue: Enterprise attributes not appearing in Keycloak

Solutions:

• Check schema includes enterprise extension
• Verify attribute mapping in user_to_keycloak()
• Check Keycloak user attributes in Admin Console

References

Architecture & API Docs

• ADR: ADR-0038: SCIM Implementation
• API Reference: SCIM 2.0 API
• RFC 7643: SCIM Core Schema
• RFC 7644: SCIM Protocol

Related Guides

• Service Principals - Provision service principals via SCIM
• API Key Management - Create API keys for provisioned users
• OpenFGA Setup - Automatic permission sync with SCIM
• Permission Model - Understanding role-based access control