Can Paradigm automatically provision users?

This article explains how Paradigm implements the SCIM (System for Cross-domain Identity Management) protocol to enable transparent provisioning and management of users between systems.

What is SCIM?

SCIM (System for Cross-domain Identity Management) is an open standard that simplifies user management in multi-domain scenarios. It provides a standardized schema and API for creating, reading, updating, and deleting identity data between identity providers and service providers.

SCIM Implementation Details

Supported SCIM Version

Paradigm supports SCIM 2.0 (RFC 7642, RFC 7643 and RFC 7644).

Tested Identity Providers

Our SCIM implementation has been tested with:

• Microsoft Entra ID

Base URL

All SCIM endpoints are accessible via:

https://[paradigm-domain]/scim/v2/

With [paradigm-domain] being the domain name under which is hosted Paradigm. For the Saas platform of LightOn, its value would be https://paradigm.lighton.ai/scim/v2/.

Authentication

To secure the SCIM API, we implemented a token-based authentication using our API key authentication backend.

Each request must include an authorization header:

Authorization: Bearer {your-paradigm-api-key}

You can generate and manage API keys in the Admin Panel under API Settings.

Supported Endpoints

Here are the SCIM endpoints supported by Paradigm together with their HTTP methods:

Endpoint	HTTP Method	Description
/Users	GET	List/search users
/Users	POST	Create a user
/Users/{id}	GET	Get a specific user
/Users/{id}	PUT	Replace a user's attributes
/Users/{id}	PATCH	Update a user's attributes
/Users/{id}	DELETE	Delete a user (Anonymization for Paradigm)
/Groups	GET	List/search groups

Supported user SCIM attributes

The SCIM implementation of Paradigm supports the following user attributes:

Core Attributes

Attribute	Description	Required
userName	Unique identifier for the user	Yes
name.givenName	First name	No
name.familyName	Last name	No
title	The user’s title, such as “Vice President”	No
preferredLanguage	Indicates the User's preferred written or spoken language	No
active	Boolean indicating if user is active	No
emails	Email addresses, Paradigm only supports one email address per user	Yes
password	The User's cleartext password. This attribute is intended to be used as a means to specify an initial password when creating a new User or to reset an existing User's password.	No

Group Schema

The SCIM implementation of Paradigm supports the following group attributes:

Attribute	Description	Required
displayName	Name of the group	Yes
members	List of member references	No

Error Handling

The Paradigm SCIM API endpoints return standard HTTP codes following the SCIM error format:

Status Code	Description
200	Successful operation
201	Resource created successfully
400	Bad request (validation error)
401	Unauthorized (authentication error)
403	Forbidden (authorization error)
404	Resource not found
409	Conflict with existing resource
500	Internal server error

Here is an example of error response:

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 
    "status": "400", 
    "detail": "Attribute 'userName' is required" 
}

Provisioning Workflow

User Provisioning

1. The Identity Provider (IdP) initiates a SCIM request to create a user on the /Users endpoint
2. Paradigm validates the request and user data
3. A new user account is created with default permissions
4. A success response is returned to the IdP

User Deprovisioning

1. The Identity Provider (IdP) sends a request to deactivate or delete a user
2. Paradigm validates the request
3. For deactivation: User's active status is set to false
4. For deletion: User account is anonymized (Any user data is removed but the behavioral data)
5. A success response is returned to the IdP

Any further SCIM request on the anonymized user will return a 404 Not Found HTTP response.

API request/response examples

User Creation

Request data example:

POST /api/scim/v2/Users
Authorization: Bearer {your-paradigm-api-key}
Content-Type: application/json

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "john.doe@example.com",
  "externalId": "ccb1c352-d321-4027-9d17-de03d8d28b2f",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "john.doe@example.com",
      "primary": true
    }
  ],
  "password": "fake-password-value",
  "title": "Software Engineer",
  "preferredLanguage": "fr-Latn-CA"
}

Related response:

{
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User'],
    'id': '4', 
    'externalId': 'ccb1c352-d321-4027-9d17-de03d8d28b2f',
    'userName': 'john.doe@example.com', 
    'name': {
        'givenName': 'John', 
        'familyName': 'Doe', 
        'formatted': 'John Doe'
    }, 
    'displayName': 'John Doe', 
    'emails': [
        {
            'value': 'john.doe@example.com', 
            'primary': True
        }
    ], 
    'active': True, 
    'title': 'Software Engineer', 
    'preferredLanguage': 'fr',
    'groups': [],
    'meta': {
        'resourceType': 'User', 
        'created': '2025-04-18T08:43:17.679804+00:00', 
        'lastModified': '2025-04-18T08:43:17.679804+00:00', 
        'location': 'http://testserver/scim/v2/Users/4'
    }
}

Update a User

Request data example:

PATCH /api/scim/v2/Users/a1b2c3d4
Authorization: Bearer {your-paradigm-api-key}
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "name.givenName",
      "value": "Jonathan"
    },
    {
      "op": "replace",
      "path": "title",
      "value": "Senior Software Engineer"
    }
  ]
}

Troubleshooting

Authentication Failures

• Verify your API key is valid and not expired
• Verify the owner of the API key has permissions to manage users.
• Ensure the Authorization header is formatted correctly

Good Practices

1. Implement Incremental Updates: Use PATCH operations instead of PUT when possible
2. Handle API Failures Gracefully: Implement retry logic with exponential backoff
3. Maintain IdP Synchronization: Schedule regular full syncs to ensure consistency
4. Secure Your API keys: Rotate tokens regularly and store them securely