SCIM 2.0 Provisioning API

Overview

The SCIM (System for Cross-domain Identity Management) 2.0 API provides standardized endpoints for automated user and group provisioning. SCIM enables identity providers and HR systems to synchronize user accounts, manage lifecycle events, and maintain group memberships automatically.

v2.8.0 implements SCIM 2.0 protocol (RFC 7643, RFC 7644) with Keycloak backend integration.

Use Cases

Identity Provider (IdP) Provisioning: Okta, Azure AD, OneLogin
HR System Integration: Workday, BambooHR, SAP SuccessFactors
User Lifecycle Automation: Onboarding, offboarding, role changes
Group Management: Automatic team/department synchronization
Directory Synchronization: Keep user data in sync across systems

SCIM 2.0 Standards Compliance

Supported Features
Backend Integration

✅ Core User Schema (RFC 7643 §4.1)
- userName, name, emails, active, password
✅ Core Group Schema (RFC 7643 §4.2)
- displayName, members
✅ CRUD Operations (RFC 7644)
- Create (POST), Read (GET), Update (PUT/PATCH), Delete
✅ Filtering & Pagination
- Basic filters (userName eq, email eq)
- Pagination (startIndex, count)
✅ PATCH Operations (RFC 7644 §3.5.2)
- replace, add (partial support)

Base URL

https://api.yourdomain.com/scim/v2

Authentication

All SCIM endpoints require authentication:

Authorization: Bearer {token} (service account or admin user)
Requires SCIM provisioning permissions

SCIM endpoints should be called by identity providers or automation systems, not end users. Configure appropriate access controls.

User Endpoints

POST /Users

Create a new user (SCIM 2.0). Provisions user in Keycloak and syncs roles to OpenFGA. Request Body:

array

required

SCIM schema URIs (always ["urn:ietf:params:scim:schemas:core:2.0:User"])

string

required

Unique username or email address

object

User’s name:

givenName: First name
familyName: Last name
formatted: Full name

array

Email addresses (array of {value, primary} objects)

boolean

default:true

Whether user account is active

string

User’s initial password (optional, can be set later)

Request Example:

curl -X POST https://api.yourdomain.com/scim/v2/Users \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "alice@example.com",
    "name": {
      "givenName": "Alice",
      "familyName": "Smith",
      "formatted": "Alice Smith"
    },
    "emails": [{
      "value": "alice@example.com",
      "primary": true
    }],
    "active": true,
    "password": "SecurePassword123!"
  }'
```python
```python Python
import httpx

response = httpx.post(
    "https://api.yourdomain.com/scim/v2/Users",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/scim+json"
    },
    json={
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "userName": "alice@example.com",
        "name": {
            "givenName": "Alice",
            "familyName": "Smith",
            "formatted": "Alice Smith"
        },
        "emails": [{"value": "alice@example.com", "primary": True}],
        "active": True,
        "password": "SecurePassword123!"
    }
)

user = response.json()
print(f"Created user: {user['id']}")

const response = await fetch('https://api.yourdomain.com/scim/v2/Users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/scim+json'
  },
  body: JSON.stringify({
    schemas: ['urn:ietf:params:scim:schemas:core:2.0:User'],
    userName: 'alice@example.com',
    name: {
      givenName: 'Alice',
      familyName: 'Smith',
      formatted: 'Alice Smith'
    },
    emails: [{value: 'alice@example.com', primary: true}],
    active: true,
    password: 'SecurePassword123!'
  })
});

const user = await response.json();
console.log('Created user:', user.id);

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "userName": "alice@example.com",
  "name": {
    "givenName": "Alice",
    "familyName": "Smith",
    "formatted": "Alice Smith"
  },
  "emails": [
    {
      "value": "alice@example.com",
      "primary": true
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2025-10-29T10:00:00Z",
    "lastModified": "2025-10-29T10:00:00Z"
  }
}

Status Codes:

Created

User created successfully

Bad Request

Invalid SCIM schema or missing required fields

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 400,
  "detail": "Invalid SCIM user schema",
  "scimType": "invalidValue"
}

Conflict

User already exists

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 409,
  "detail": "User with userName 'alice@example.com' already exists",
  "scimType": "uniqueness"
}

GET /Users/

Get user by ID (SCIM 2.0). Returns user in SCIM format. Path Parameters:

string

required

Keycloak user ID (UUID)

Request Example:

curl https://api.yourdomain.com/scim/v2/Users/f81d4fae-7dec-11d0-a765-00a0c91e6bf6 \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

Response: Same as POST /Users response Status Codes:

Success

User retrieved successfully

Not Found

User not found

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 404,
  "detail": "User f81d4fae-7dec-11d0-a765-00a0c91e6bf6 not found",
  "scimType": "notFound"
}

PUT /Users/

Replace user (SCIM 2.0 PUT). Replaces entire user resource. All fields must be provided. Path Parameters:

string

required

Keycloak user ID (UUID)

Request Body: Same as POST /Users Request Example:

curl -X PUT https://api.yourdomain.com/scim/v2/Users/f81d4fae-7dec-11d0-a765-00a0c91e6bf6 \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "alice@example.com",
    "name": {
      "givenName": "Alice",
      "familyName": "Smith-Johnson",
      "formatted": "Alice Smith-Johnson"
    },
    "emails": [{
      "value": "alice.johnson@example.com",
      "primary": true
    }],
    "active": true
  }'

Response: Same as POST /Users response Status Codes:

Success

User updated successfully

Bad Request

Invalid SCIM schema

Not Found

User not found

PATCH /Users/

Update user with PATCH operations (SCIM 2.0). Supports partial updates using SCIM PATCH operations. Path Parameters:

string

required

Keycloak user ID (UUID)

Request Body:

array

required

["urn:ietf:params:scim:api:messages:2.0:PatchOp"]

array

required

Array of PATCH operations:

op: Operation type (replace, add, remove)
path: Attribute path (e.g., active, emails)
value: New value

Request Example:

curl -X PATCH https://api.yourdomain.com/scim/v2/Users/f81d4fae-7dec-11d0-a765-00a0c91e6bf6 \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      }
    ]
  }'

curl -X PATCH https://api.yourdomain.com/scim/v2/Users/f81d4fae-7dec-11d0-a765-00a0c91e6bf6 \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "emails",
        "value": [{"value": "newemail@example.com", "primary": true}]
      }
    ]
  }'

import httpx

# Deactivate user
response = httpx.patch(
    f"https://api.yourdomain.com/scim/v2/Users/{user_id}",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/scim+json"
    },
    json={
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {"op": "replace", "path": "active", "value": False}
        ]
    }
)

Response: Same as POST /Users response Status Codes:

Success

User patched successfully

Bad Request

Invalid PATCH operation

Not Found

User not found

DELETE /Users/

Delete (deactivate) user (SCIM 2.0). Deactivates user in Keycloak (sets enabled=false) and removes OpenFGA authorization tuples. User data is preserved for compliance. Path Parameters:

string

required

Keycloak user ID (UUID)

Request Example:

curl -X DELETE https://api.yourdomain.com/scim/v2/Users/f81d4fae-7dec-11d0-a765-00a0c91e6bf6 \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

Response: No content (HTTP 204)

Soft Delete: Users are deactivated (not permanently deleted) to comply with audit and compliance requirements. Hard deletion requires direct Keycloak admin access.

Status Codes:

No Content

User deleted successfully

Not Found

User not found

GET /Users

List/search users (SCIM 2.0). Supports basic filtering and pagination. Query Parameters:

string

SCIM filter expression (e.g., userName eq "alice@example.com")Supported filters:

userName eq "value"
email eq "value"

integer

default:1

1-based start index for pagination (minimum: 1)

integer

default:100

Number of results to return (1-1000)

Request Example:

curl 'https://api.yourdomain.com/scim/v2/Users?startIndex=1&count=100' \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
```bash
```bash Filter by UserName
curl 'https://api.yourdomain.com/scim/v2/Users?filter=userName%20eq%20%22alice@example.com%22' \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

import httpx

# List users with pagination
response = httpx.get(
    "https://api.yourdomain.com/scim/v2/Users",
    headers={"Authorization": f"Bearer {token}"},
    params={"startIndex": 1, "count": 50}
)

users = response.json()
print(f"Total users: {users['totalResults']}")

Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "startIndex": 1,
  "itemsPerPage": 2,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "userName": "alice@example.com",
      "name": {
        "givenName": "Alice",
        "familyName": "Smith"
      },
      "emails": [{"value": "alice@example.com", "primary": true}],
      "active": true
    },
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "9d3e2a1b-8c7f-4e6d-a5b4-3c2d1e0f9a8b",
      "userName": "bob@example.com",
      "name": {
        "givenName": "Bob",
        "familyName": "Johnson"
      },
      "emails": [{"value": "bob@example.com", "primary": true}],
      "active": true
    }
  ]
}

Status Codes:

Success

Users retrieved successfully

Bad Request

Invalid filter or pagination parameters

Group Endpoints

POST /Groups

Create a new group (SCIM 2.0). Request Body:

array

required

["urn:ietf:params:scim:schemas:core:2.0:Group"]

string

required

Group name (e.g., “Engineering”, “Marketing”)

array

Array of group members:

value: User ID (UUID)
display: Display name (optional)

Request Example:

curl -X POST https://api.yourdomain.com/scim/v2/Groups \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "Engineering",
    "members": [
      {
        "value": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
        "display": "Alice Smith"
      },
      {
        "value": "9d3e2a1b-8c7f-4e6d-a5b4-3c2d1e0f9a8b",
        "display": "Bob Johnson"
      }
    ]
  }'

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "displayName": "Engineering",
  "members": [
    {
      "value": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "display": "Alice Smith"
    },
    {
      "value": "9d3e2a1b-8c7f-4e6d-a5b4-3c2d1e0f9a8b",
      "display": "Bob Johnson"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "created": "2025-10-29T10:00:00Z"
  }
}

Status Codes:

Created

Group created successfully

Bad Request

Invalid SCIM schema

Conflict

Group already exists

GET /Groups/

Get group by ID (SCIM 2.0). Path Parameters:

string

required

Keycloak group ID (UUID)

Request Example:

curl https://api.yourdomain.com/scim/v2/Groups/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

Response: Same as POST /Groups response Status Codes:

Success

Group retrieved successfully

Not Found

Group not found

Identity Provider Integration Examples

Okta SCIM Integration

# Okta Application Settings
SCIM Base URL: https://api.yourdomain.com/scim/v2
Authentication: OAuth 2.0 Bearer Token
Supported Features:
  - Push New Users
  - Push Profile Updates
  - Push Groups
  - Import New Users and Profile Updates

Attribute Mappings:
  userName: user.email
  name.givenName: user.firstName
  name.familyName: user.lastName
  emails[0].value: user.email
  active: user.status == "ACTIVE"

Azure AD SCIM Integration

# Azure AD Enterprise Application
$AppId = "<your-app-id>"
$TenantDomain = "https://api.yourdomain.com/scim/v2"

Set-AzureADApplication -ObjectId $AppId `
  -IdentifierUris $TenantDomain `
  -ReplyUrls "$TenantDomain/Users","$TenantDomain/Groups"

# Configure attribute mappings in Azure Portal
# Provisioning > Mappings > User Mappings

OneLogin SCIM Integration

{
  "scim_base_url": "https://api.yourdomain.com/scim/v2",
  "authentication": "Bearer Token",
  "scim_version": "2.0",
  "user_provisioning": true,
  "group_provisioning": true,
  "attribute_mappings": {
    "userName": "email",
    "givenName": "firstname",
    "familyName": "lastname"
  }
}

SCIM Testing & Validation

Test User Provisioning Flow

# 1. Create user
USER_ID=$(curl -X POST https://api.yourdomain.com/scim/v2/Users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "testuser@example.com",
    "name": {"givenName": "Test", "familyName": "User"},
    "emails": [{"value": "testuser@example.com", "primary": true}],
    "active": true
  }' | jq -r '.id')

# 2. Get user
curl https://api.yourdomain.com/scim/v2/Users/$USER_ID \
  -H "Authorization: Bearer $TOKEN"

# 3. Update user (deactivate)
curl -X PATCH https://api.yourdomain.com/scim/v2/Users/$USER_ID \
  -H "Authorization: Bearer $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}]
  }'

# 4. Delete user
curl -X DELETE https://api.yourdomain.com/scim/v2/Users/$USER_ID \
  -H "Authorization: Bearer $TOKEN"

SCIM Provisioning Guide

Complete SCIM setup and integration guide

Keycloak Integration

Keycloak deployment and configuration

OpenFGA Authorization

Authorization model and permissions

SCIM Implementation ADR

SCIM design decisions

Standards Compliant: Full SCIM 2.0 protocol implementation with Keycloak and OpenFGA integration!

API Documentation

Developer Tools

MCP Protocol

Overview

Use Cases

SCIM 2.0 Standards Compliance

Base URL

Authentication

User Endpoints

POST /Users

GET /Users/

PUT /Users/

PATCH /Users/

DELETE /Users/

GET /Users

Group Endpoints

POST /Groups

GET /Groups/

Identity Provider Integration Examples

Okta SCIM Integration

Azure AD SCIM Integration

OneLogin SCIM Integration

SCIM Testing & Validation

Test User Provisioning Flow

SCIM Provisioning Guide

Keycloak Integration

OpenFGA Authorization

SCIM Implementation ADR

​Overview

​Use Cases

​SCIM 2.0 Standards Compliance

​Base URL

​Authentication

​User Endpoints

​POST /Users

​GET /Users/

​PUT /Users/

​PATCH /Users/

​DELETE /Users/

​GET /Users

​Group Endpoints

​POST /Groups

​GET /Groups/

​Identity Provider Integration Examples

​Okta SCIM Integration

​Azure AD SCIM Integration

​OneLogin SCIM Integration

​SCIM Testing & Validation

​Test User Provisioning Flow

​Related Documentation

SCIM Provisioning Guide

Keycloak Integration

OpenFGA Authorization

SCIM Implementation ADR

Overview

Use Cases

SCIM 2.0 Standards Compliance

Base URL

Authentication

User Endpoints

POST /Users

GET /Users/

PUT /Users/

PATCH /Users/

DELETE /Users/

GET /Users

Group Endpoints

POST /Groups

GET /Groups/

Identity Provider Integration Examples

Okta SCIM Integration

Azure AD SCIM Integration

OneLogin SCIM Integration

SCIM Testing & Validation

Test User Provisioning Flow

Related Documentation