Directory sync (SCIM)

Directory sync uses SCIM 2.0 to let your identity provider manage members in emisar: it provisions people, and when they leave it suspends the member, ends their sessions, and revokes their API keys.

Enabling directory sync#

Open the configured connection from Team → Single sign-on and enable directory sync — the panel lives on the connection's page, under its settings. Only available on Enterprise.

emisar console · User provisioning & directory sync

Expand

1. 1

   From Team → Single sign-on, open the connection and click Enable under User provisioning & directory sync.

   emisar shows you two things to wire into your provider's SCIM connector:

   • — the SCIM base URL — /scim/v2 on your emisar host (copy button beside it)
   • — the bearer token — shown once when you enable or rotate, so copy it immediately; if you missed it, Rotate token mints a new one and the old one stops working.
2. 2

   Point your IdP's SCIM connector at that base URL and bearer.

   Set the SCIM endpoint to the base URL, paste the token as the API token (emisar reads it from the Authorization header), and enable Create, Update, and Deactivate. Okta and Entra need a separate provisioning application — their OIDC login applications cannot provision through SCIM — while JumpCloud carries sign-in and provisioning in one. The Setup instructions guide lists the provider-specific settings.

3. 3

   Match the SCIM externalId to the OIDC subject.

   Configure externalId to carry the same stable value as the connection's identifier claim, so the SSO login and the synced record resolve to one emisar identity. Matching never uses email, so identifiers that differ cannot be reconciled.

   • — Okta usually needs no changes: it puts the Okta user ID in externalId, and its organization authorization server sends the same value as sub — though Okta shows that in examples rather than guaranteeing it, and a custom authorization server can rewrite the subject claim.
   • — Entra needs changes on both sides: map externalId from mailNickname to objectId, and set the connection's identifier claim to oid. Entra sends a different sub per application, so without both changes the login and provisioning applications identify different people.

   Whatever the provider, check both values against one real user before you roll out.

• — Provisioning creates the user and membership at the connection's default role before their first login, with runner access combined from Default access and mapped directory groups.
• — When the directory deactivates or removes a user, deprovisioning suspends the member — sessions end and their API keys are revoked immediately, so directory offboarding revokes emisar access on its own. The person and audit history remain. Deactivation can be reversed with active:true; after DELETE, the directory must POST the same externalId to restore the resource. emisar refuses to deprovision the last active owner and returns an error to the directory — promote another owner first.

Rotate or disable directory sync#

Rotate token mints a new bearer and the old one stops working immediately — paste the new value into your IdP connector. Disable also stops the bearer, but members are kept: the directory just stops managing their role and runner access, and owners and admins control those again. If you re-enable sync later, group-based access returns only after the directory pushes its groups again.

Because there is no overlap, the connector is unauthenticated between the rotate and the paste — you should plan for that gap. The rotation sequence, and how a SCIM bearer compares with every other credential emisar issues, is in rotate and revoke credentials. If you believe the bearer has leaked, see security incidents.

emisar console · Members

Expand

The connection's Members list includes identities added through sign-in and directory sync. Last seen records the identity's latest activity, including sign-in; it is not a directory-sync success receipt. Suspending access in emisar creates a manual hold that later directory sync does not remove. Restore access does not restore revoked agent credentials or standing approvals. Directory-deactivated members must first be reactivated in the identity provider.

SCIM protocol reference#

Every endpoint is under the connection's /scim/v2 base URL and requires its bearer token. The token selects the account and provider. Resources cannot be read or changed across connections.

Users#

• — POST requires externalId or userName. active defaults to true. emisar accepts a JSON boolean or the case-insensitive strings "True"/"False" that Entra sends. Repeating a create with the same externalId reconciles the existing identity and returns the same server id.
• — Collection filters support userName eq "..." and externalId eq "...". Unsupported filters return invalidFilter. Collections use one-based startIndex/count pagination, return at most 100 resources per page, and report the full matching count in totalResults.
• — PATCH accepts add or replace for active, displayName, name.givenName, and name.familyName, including the pathless attribute map Entra sends. PUT requires active in one of those boolean forms and can update the name. Email and externalId stay fixed after provisioning.
• — PATCH active:false suspends the membership while keeping the User resource addressable, and active:true restores that suspension. DELETE also retires the User resource: later reads and mutations return 404 until the directory POSTs the same externalId. A manual administrator suspension is not reversed by the directory.

Groups#

• — POST and PUT reconcile the full membership. PATCH supports member add, remove, and whole-set replace, plus displayName replacement. Each members[].value is the returned id of a User resource.
• — A Group POST with externalId reconciles that directory resource. A probe without externalId gets a new server id. Use that id for later reads and writes. displayName is a label and filter, never the group's identity.
• — Collection filtering supports displayName eq "..." and uses the same startIndex/count pagination as Users. Deleting a group removes everyone from it, recomputes their mapped authorization, then retires the SCIM group resource.
• — One request accepts at most 100 PATCH operations. A group write accepts at most 5,000 member IDs. Bulk, sorting, ETags, and password changes are not supported.

Provider guides#

The IdP-side walkthrough lives on each provider's guide, beside its sign-in setup:

• Okta — SCIM rides its own Okta app, separate from the sign-in integration.
• Microsoft Entra — a separate enterprise application, with externalId remapped to objectId.
• JumpCloud — the same custom application that signs people in.
• Keycloak has no outbound SCIM. The guide explains the remaining manual work.
• Google Workspace has no outbound SCIM. Route it through an IdP to close the offboarding gap.

Role mapping#

In Groups & access, use a group's role dropdown to assign an emisar role — viewer, operator, billing manager, or admin. A member in several mapped groups gets the highest role mapped to any of them. If none of their groups has a role mapping, the connection's default role applies. That default is a fallback, not a minimum. Renaming a group does not break its mapping. Owner is never assignable through sync — it stays a deliberate human assignment.

Directory sync cannot grant or remove Owner privileges or narrow an Owner's runner and pack access. It can still suspend an Owner, subject to the last-owner safeguard. To hand an Owner's role and access back to the directory, another Owner chooses Use directory role from their role menu on Team. While sync is pending, that member has Viewer privileges and no runner or pack access.

emisar console · Groups & access

Expand

Mapping directory groups to runner access#

In Groups & access, each row shows the connection defaults plus that group's runner and pack grants. Choose Edit access on the group to add access to all runners, selected runner groups, or individual runners and packs. Connection defaults stay selected and locked in the editor; you can keep that access or add more. Choose Reset to defaults in the editor to remove only that group's access grant; its role mapping stays unchanged. The grant applies to current group members immediately and follows later SCIM membership changes.

Group runner access is additive: emisar combines Default runner access with every mapped group the member belongs to, a mapping cannot remove access granted elsewhere, and any All runners grant wins. For example, a no-runners default plus database-team → group:database-prod gives those members exactly the database runner group — and if another mapped group grants all runners, members in both get all runners.

Troubleshooting#

Use these checks for directory-side symptoms. If you are not sure the problem is provisioning, start from Troubleshooting. It routes each symptom to the page that owns it.

Security notes#

• — The SCIM bearer token is an admin-grade credential — it can provision and deprovision across the account, so treat it like a password and rotate it from Team → Single sign-on whenever it is exposed; your IdP loses access until you paste the new token.
• — Each directory-sync action records its authentication method in the audit log . This shows whether the directory, rather than a person, suspended an offboarded member.