Agent Console SCIM Provisioning

The agent admin console accepts SCIM 2.0 pushes from your identity provider (IdP), so users are created, updated, and offboarded in the console as they change in your directory. This page covers one setting that matters more than the rest: what your IdP sends as the SCIM externalId.

Connect your IdP

In the console's Directory settings, go to Directory sync via SCIM v2. The console shows your SCIM endpoint URL and lets you generate a bearer token. Point your IdP at the endpoint and use the token for authentication:

Authorization: Bearer <your-scim-token>

The token is scoped to your organization. The users endpoint is /api/scim/v2/Users on your console host.

How users are matched

When your IdP creates or re-syncs a user, the console looks for an existing user in your organization in this order:

1. externalId, exact match.
2. Email, case-insensitive.

The first match wins. A match on externalId is the same person, so an email change in your IdP updates the existing user and keeps their enrollments.

An email match is weaker evidence. It cannot tell apart two cases that look identical:

• the same person, whose user ID was re-keyed in the IdP;
• a different person who now holds the same email address (a rehire, or a recycled address).

The console therefore handles the two directions differently:

A deactivation for the new holder of a reused address can therefore offboard the previous holder. Correct externalId mapping, below, prevents that.

Map externalId to a stable, immutable ID

Send the IdP's permanent user ID as externalId. Do not send an email address or sign-in name, because those can change and can be reassigned to someone else.

Microsoft Entra ID

In Enterprise apps, open your provisioning app, then Provisioning > Attribute Mapping, and edit the externalId mapping under Users:

• Set the Source attribute to objectId, the user's Object ID (the id property in Microsoft Graph, which Microsoft describes as the user's unique, read-only identifier).
• Do not map externalId to userPrincipalName or mail. Microsoft describes the user principal name as a sign-in name that by convention matches the user's email name.
• Check what the mapping sends today. Microsoft's SCIM documentation uses mailNickname as its example source for a user's externalId, and a mail alias is not a permanent ID.

Okta

Map externalId to the Okta user ID, which Okta documents as the unique, read-only key for a user. In the app's attribute mappings, use the Okta Expression Language expression user.getInternalProperty("id") as the source for the externalId attribute.

Operating rules

• Pick the externalId source before the first sync, and do not change it afterwards. An update your IdP sends to an existing user (by the user's console ID) rewrites the stored externalId to the new value. But any user your IdP instead creates again (a POST) is matched by email to a record holding the old value, and is refused with 409 uniqueness until that is resolved. Deactivations still go through.
• Offboard before you reuse an email address, and expect the create to be refused until the old record is cleared. When a new hire will get an address that belonged to someone else, deprovision the previous holder first. This protects the previous holder's offboarding: once they are offboarded, a later deactivation for the new holder cannot offboard the wrong person. It does not release the address. Offboarding suspends the previous holder but keeps their record, including their email and externalId, so the new hire's create is still answered with 409 uniqueness until that record no longer holds the address. Contact Hawcx support to clear it, then have your IdP retry.

Reference

• Microsoft: Customize attribute mappings, Develop a SCIM endpoint, user resource type
• Okta: Okta Expression Language, Map Okta attributes to app attributes