Microsoft Entra

Connect Microsoft Entra to emisar: an app registration signs people in with the oid claim, and a separate enterprise application provisions the directory.

Before you start, you need:

An Entra administrator.
An emisar owner or admin.

The sections below build two objects in order: sign-in first, then the directory.

Single sign-on#

Connecting an identity provider is a paid feature. Only available on Team & Enterprise.

1

In emisar

Start the connection.

Open Team → Single sign-on → Add connection and choose Microsoft Entra ID. Leave the page open: the callback URL on it is what Entra asks for next, and Entra's values come back here at the end.

emisar · Add connection

Picking the provider here tailors the rest of the form to it.
2

In Entra

Register the application.

In the Microsoft Entra admin center go to App registrations → New registration. Under Redirect URI choose the Web platform and enter emisar's callback:

Redirect URI

https://emisar.dev/sign_in/sso/callback

Microsoft Entra admin center · Register an application

The platform must be set to Web. Until it is, the URI beside it is ignored, and the form refuses to register without it.
3

In Entra

Create a client secret.

Open Certificates & secrets → New client secret. Copy the Value column, not Secret ID. The value is shown once and cannot be recovered later.

Microsoft Entra · Certificates & secrets

Press New client secret, then copy Value while it is shown. Secret ID is not the credential.
4

In Entra

Copy the client and tenant IDs.

The registration Overview page contains two values. Use Application (client) ID as the client ID. Use Directory (tenant) ID in the issuer URL.

Microsoft Entra · App registration overview

Application (client) ID is emisar's Client ID. Directory (tenant) ID below it goes into the issuer.
5

In Entra

Add the sign-in time claim.

Under Manage → Token configuration, select Add optional claim, choose the ID token type, select auth_time, and select Add. Entra leaves this claim out by default. emisar checks it whenever it asks Entra for a fresh sign-in: verifying the connection, accepting an invitation in a workspace that requires SSO, and setting up or resetting multi-factor authentication. Without the claim, those steps fail.
6

In emisar

Paste them into the connection.

Return to the connection from step 1. Use Application (client) ID as the client ID. Use the secret from step 3. Build the issuer from your tenant ID.

Issuer URL

https://login.microsoftonline.com/YOUR-TENANT-ID/v2.0

The trailing /v2.0 selects Entra's v2.0 endpoint. Without it, Entra returns v1.0 tokens. The identifier claim is already oid. Entra assigns a different sub to each application. The oid claim also matches the value directory sync sends.

Select Add connection, then Verify sign-in. Complete the identity checks and sign in with your Entra user. This links your Entra identity to your current emisar member; directory sync is not required for this verification. Select Enable for members and confirm.

emisar · Add connection

The issuer carries your tenant ID and ends in /v2.0. The identifier claim is already oid.

Directory sync#

Directory sync makes Entra responsible for the member lifecycle: it provisions (adds) people and removes their access after offboarding. It also supplies the active identity record that links Entra's oid claim to sign-in. Only available on Enterprise.

Provision members before their first sign-in.

With directory sync enabled, provision members before they sign in. When Entra's ID token omits email_verified, emisar matches its oid to an active member provisioned by this Entra connection, not by email. Map SCIM externalId to Entra's objectId so both flows use the same identifier.

You need the connection's SCIM base URL and bearer token. See enabling directory sync for where both come from.

1

In Entra

Create the enterprise application.

Provisioning needs a separate object from the sign-in app registration. Go to Enterprise applications → New application → Create your own application. Name it emisar. Choose Integrate any other application you do not find in the gallery.

Microsoft Entra · Browse App Gallery

The gallery is for apps Microsoft already ships an integration for. emisar is not one, so you create it by hand.
2

In Entra

Point it at emisar.

On the new application's Provisioning page, set Provisioning Mode to Automatic. Enter the SCIM base URL as Tenant URL. Enter the bearer as Secret Token.

Tenant URL

https://emisar.dev/scim/v2

Microsoft Entra · Enterprise application provisioning

After the live test, the Provisioning overview reported a completed incremental cycle with one group and two users.

Press Test Connection. Entra queries a random GUID that cannot exist. It expects an empty result, not an error. emisar returns that result. A failure means the URL or token is wrong, not the schema. Save.

Microsoft Entra · Connectivity

Leave authentication on Bearer. Tenant URL and the masked bearer sit together above Test connection.
3

In Entra

Remap externalId to objectId.

Open Manage → Attribute mapping and change the source attribute feeding externalId from mailNickname to objectId. On a tenant still using Entra's older provisioning screens, the same setting lives under Mappings → Provision Microsoft Entra ID Users.

Microsoft Entra · Attribute mapping

The saved result: objectId now feeds externalId. Open this row to verify the complete mapping.

Microsoft Entra · Edit Attribute Mapping

Change the source, not the target: externalId must stay aligned with the OIDC oid claim.

Entra defaults to mailNickname. This value can be missing, duplicated, or changed. It also differs from the identifier used by the sign-in connection. If SSO uses oid while SCIM uses mailNickname, sign-in cannot match the synced member and waits for administrator approval. objectId is the same permanent value as oid, so both flows identify one person.
4

In Entra

Assign the people to sync.

Under Users and groups, assign each person who needs an emisar account, or a group that contains them directly. Entra provisions only the direct members of an assigned group, never the members of a group nested inside it. Then, on Provisioning → Settings, set Scope to Sync only assigned users and groups and turn Provisioning Status on. Scope is separate from assignment and defaults to everyone. Change it, or Entra sends the entire directory no matter what you assigned. Entra syncs roughly every 40 minutes. New members appear under Members after the next cycle. Their Entra groups then appear under Groups & access. An offboarding also waits for the next cycle. For an urgent one, also choose Suspend access on emisar's Team page; directory sync never lifts that hold.

Entra · Users and groups

The certification group is assigned here and was provisioned to emisar.
5

In Entra

Guard against a mistaken unassignment.

On the same Provisioning → Settings page, check Prevent accidental deletions, set a threshold above your usual offboardings per cycle, and fill in Notification Email. When one cycle would disable or delete more users than that, Entra pauses provisioning and emails you to allow or reject the batch. Without that guard, unassigning the wrong group suspends everyone in it in emisar and revokes their agent keys and standing approvals. Assigning the group again restores their access, but not those credentials.

Next: configure Role mapping so directory groups grant the right Emisar role.

← Previous

Okta

JumpCloud