SCIM Provisioning

Learn about SCIM provisioning with Topaz labs

Overview

Topaz Labs supports SCIM 2.0 user provisioning for enterprise customers.

You can use SCIM to:

- create users
- update users
- deprovision users
- assign Topaz managed-seat role and seat count

Requirements

Before setting up provisioning in your identity provider, request these values from Topaz:

- Provisioning URL
- Bearer token
- tenantKey
- controllerKey

Example values:

- Provisioning URL: https://topazlabs.com/topaz-scim/
- Bearer token: <tenant-token>
- tenantKey: tk_sample-tenant
- controllerKey: ck_photo-team

Topaz Extension URN

Use this SCIM extension URN when mapping Topaz-specific attributes:

urn:ietf:params:scim:schemas:extension:topaz:2.0:User

Configure the SCIM Connection

Use this SCIM base URL

Enter the base URL only. Do not append /Users when configuring the application.

Use bearer token authentication.

Authorization: Bearer <tenant-token>
Content-Type: application/scim+json

In your identity provider:

1. Create or open the Topaz SCIM application.
2. Enter the SCIM base URL provided by Topaz.
3. Enter the bearer token provided by Topaz.
4. Save the connection settings.
5. Test the connection if your identity provider supports it.

Configure Attribute Mappings

Topaz recommends sending these standard SCIM fields:

- userName
- emails
- name.givenName
- name.familyName
- displayName
- active

Topaz also supports these Topaz-specific extension fields:

- tenantKey
- controllerKey
- managedSeatEnabled
- managedSeatRole
- managedSeatCount
- productScope
- ssoRuleAction

Azure Entra Notes

Azure Entra works well for a user-based SCIM setup.

For Azure Entra, Topaz recommends:

- tenantKey -> constant
- controllerKey -> constant
- productScope -> constant

In the simplest Azure Entra setup, these may also be constants:

- managedSeatEnabled
- managedSeatRole
- managedSeatCount
- ssoRuleAction

This gives you a working baseline, but it means those values are shared across users in that provisioning app.

If you need true per-user control from Azure, those values must come from user-specific Azure attributes rather than constants.

Azure Provision on demand is best for testing one user at a time.

For a standard managed-seat setup, use these values:

- tenantKey -> the tenantKey provided by Topaz
- controllerKey -> the controllerKey provided by Topaz
- managedSeatEnabled -> true
- managedSeatRole -> sub_user
- managedSeatCount -> 1

controllerKey is required for provisioning writes.

If you send tenantKey, it must match the tenant assigned to your bearer token.

> If you use Azure Entra, assign the user to the enterprise application before testing provisioning. Unassigned users are skipped before Topaz receives the request.

Example User Payload

{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:topaz:2.0:User"
],
"userName": "user@example.com",
"active": true,
"displayName": "Sample User",
"name": {
"givenName": "Sample",
"familyName": "User"
},
"emails": [
{
"primary": true,
"value": "user@example.com"
}
],
"urn:ietf:params:scim:schemas:extension:topaz:2.0:User": {
"tenantKey": "tk_sample-tenant",
"controllerKey": "ck_photo-team",
"managedSeatEnabled": true,
"managedSeatRole": "sub_user",
"managedSeatCount": 1,
"productScope": "enterprise_default"
}
}

Test Provisioning

After saving your connection and mappings:

1. Assign a single test user.
2. Confirm the user provisions successfully.
3. Confirm the user is routed to the correct Topaz tenant and controller.
4. Confirm the expected role and seat count are applied.

Azure Entra notes:

- Use one provisioning URL only.
- Provision on demand tests one user at a time.
- Azure group object provisioning is not supported in the current Topaz SCIM rollout.
- Background provisioning runs on Azure's own schedule.

- Azure Entra may apply custom Topaz attributes in subsequent PATCH operations rather than the initial create.
- Topaz SCIM reconciles toward final desired state across create/update lifecycle events.

Topaz currently supports these user operations:

- POST /Users
- GET /Users
- GET /Users/{id}
- PUT /Users/{id}
- PATCH /Users/{id}
- DELETE /Users/{id}

Topaz currently supports exact-match SCIM filters using eq for:

- userName
- emails.value
- externalId
- id

Examples:

filter=userName eq "user@example.com"
filter=emails.value eq "user@example.com"
filter=externalId eq "entra-object-id"
filter=id eq "123"

Go Live

Before enabling provisioning for your organization, confirm that:

- the SCIM base URL is correct
- the bearer token is correct
- the tenantKey is correct
- the controllerKey is correct
- your default role and seat count mappings are correct
- you have successfully provisioned a test user

Notes

• Sending active=false is treated as a deprovision action.
• DELETE /Users/{id} is also treated as a deprovision action.
• When a user is deprovisioned, Topaz removes SCIM-managed assignments and marks the user inactive in tenant state. The underlying account is not hard-deleted.
• If you use Azure Entra and want account disable to deprovision the user in Topaz, make sure your active mapping reflects the lifecycle signal you intend to use. A mapping based only on soft-delete state may not react to a simple account disable.

Topaz does not currently support:

- SCIM Groups (coming soon)
- SCIM bulk operations

Support

If you need help with setup, contact your Topaz representative.

Topaz SCIM Attribute Reference