Single sign-on (SSO)

SSO allows you to sign in to emisar through your own identity provider — Google Workspace, Okta, Microsoft Entra, JumpCloud, Keycloak, or any compliant OIDC provider.

Provisioning and removal from your directory is a separate layer on top of sign-in: directory sync (SCIM). Both are managed from Team → Single sign-on.

Setting up SSO login#

You need an emisar owner or admin, and enough access at your provider to create an application. Only available on Team & Enterprise.

1. Open Team → Single sign-on → Add provider and choose your provider type. Leave the page open — it shows the redirect URI your provider asks for next.
2. At the provider, create a confidential web application — one with a client secret. Paste emisar's redirect URI into it unchanged; it ends in /sign_in/sso/callback.
3. Back in emisar, enter the issuer URL, client ID, and client secret. Press Test connection, then tick Enabled and save — otherwise sign-ins will not work.

The provider guides below walk each of these screens with screenshots.

Connection settings#

The provider type selects a preset that chooses the identity claim and provider-specific behavior — pick your actual provider rather than Generic OIDC. The display name is shown on the sign-in page.

emisar fetches the issuer URL's OIDC discovery document and derives every other endpoint from it. Only enter the issuer. Do not enter authorization, token, or JWKS URLs. It must use HTTPS and be reachable from emisar.

The client ID and client secret come from the application. The secret is write-only: emisar stores it server-side and never shows it again — it must replay the secret on every sign-in, so it cannot store only a hash. Leave the field blank when editing later to keep the current secret.

The identifier claim is the field emisar stores as a person's permanent id: sub for most providers, oid for Microsoft Entra. Leave it unchanged — emisar recognises a returning member by this value, so it locks permanently at the first sign-in. Your directory must send the same value as SCIM externalId so sign-in and directory sync identify one person.

emisar console · Add connection

Expand

Who gets in, and what they get#

New-user provisioning controls a first sign-in when no emisar member exists: Auto-provision creates the member immediately, and Manual holds the first sign-in for administrator approval. Auto-provision is the usual setup when the provider application is assigned only to approved users; use Manual when you cannot control assignments that tightly.

Turning on directory sync overrides this setting: the directory decides who exists, and a sign-in from an unprovisioned account waits for approval either way.

Default role for new users is configurable. Provisioning never grants owner — that stays a deliberate human grant, so no provider misconfiguration can grant this role. If you map directory groups to roles, the mapping wins and this is only the fallback for someone in no mapped group. See roles for the list of roles and their permissions.

Default runner access controls which hosts a new member can see and use. No runners is the safe default — the member reads the console and reaches nothing until you grant access. All runners covers current and future runners, and Selected runners limits access to named groups or hosts. Roles and runner access are independent: an operator with no runners cannot dispatch anything.

Allowed email domain is optional. Set it to allow sign-ins from one domain only. For Google Workspace, emisar checks the hd claim to confirm the Workspace tenant. For other providers, the ID token must include an email address from that domain and mark it with email_verified: true. The hd claim does not confirm the email address, so emisar cannot use it to store an address or recognise a member. Leave this field blank to accept every identity returned by the provider.

emisar console · Add connection

Expand

Satisfying the 2FA requirement#

Enable this setting if your provider satisfies the account's 2FA requirement. It saves members from setting up a second 2FA token for emisar. Only turn it on if the provider really enforces MFA — otherwise it becomes a way around the account's requirement, which is described in Enforce account sign-in.

emisar console · Add connection

Expand

How members sign in#

On the sign-in page, members select “Continue with single sign-on” (/sign_in/sso), enter the team's address, choose the provider, authenticate there, and return signed in.

When the email already belongs to someone#

emisar recognises a returning member by the identifier claim, not by their email address. People change addresses, and an address can be reassigned; a subject cannot. Matching on email would let whoever controls an address inherit the emisar account behind it, so a first SSO sign-in never silently merges into an existing one. What happens instead depends on who owns the address:

• Already a member of this account. The sign-in is held, and an owner or admin approves it under Team → Pending access requests. Approving binds that existing member to the SSO identity — it does not create a second person, and their role and runner access are left as they are.
• Someone outside this account. The sign-in is refused. There is nobody here to link them to, and emisar will not claim another account's user by matching an address.

Managing a connection#

Require SSO for the account#

First complete a real sign-in through the connection in another browser. Test connection checks discovery and reachability only — not user assignment, callback acceptance, or claims — so it can pass on a connection nobody can actually sign in through. Keep an owner session open while you test. Then open Team → Security and turn on Require single sign-on.

Once required, magic-link sign-in stops working, and existing sessions are redirected to one of this account's enabled providers on their next navigation. This option cannot be enabled with no active SSO connection, and emisar refuses to disable or delete the last active connection while the requirement remains on. Turn off Require SSO before retiring that last connection.

Require SSO gates browser access and new OAuth consent for every member, including owners. What it covers — and the bearer credentials it leaves untouched — is in what Require SSO covers.

Rotate a client secret#

The client secret is a credential like any other — the rotation steps, including the write-only field and the sign-in check before you delete the old secret, are in Rotate and revoke credentials. If you suspect a leak, follow Security incidents instead.

Move to another issuer or client#

After an SSO connection's first sign-in, its issuer, client ID, and identifier claim cannot be updated any more. To move tenants, issuers, or clients, add a new connection and migrate assignments to it. You can still change the client secret to rotate it.

Disable or delete a connection#

Disabling a connection stops new sign-ins but keeps the configuration, so you can enable it again later. Deleting retires it and dismisses any manual-approval requests still waiting on it. Either way, the sessions that connection signed in are revoked, and users and audit history are kept.

An account can have several provider types, but only one enabled connection of each type. Only one enabled emisar connection can use a given email domain. Remove or disable the existing domain before assigning it elsewhere.

Provider guides#

Each guide walks one provider end to end — sign-in first, then directory sync — with screenshots of the console screens along the way.

• Okta — an OIDC web app for sign-in and a separate SCIM app for the directory. Verified against a live Okta Integrator org on August 18, 2026.
• Microsoft Entra — an app registration with the oid claim, and an enterprise application for provisioning.
• JumpCloud — one custom application carries sign-in and provisioning together. Verified against a live JumpCloud tenant on August 18, 2026.
• Keycloak uses a confidential client with PKCE and has no outbound SCIM.
• Google Workspace uses an Internal OAuth client with a locked, prefilled issuer and no outbound SCIM.

Any other OIDC provider#

The preset providers are built on top of one standard flow — they are not separate integrations. A provider that meets the contract below works through Generic OpenID Connect — including Auth0, Ping, OneLogin, Authentik, or an in-house IdP. This connection uses only the OIDC authorization code flow. SAML is not supported.

The setup steps above are the same here. Two extra requirements apply to a provider with no preset: its issuer must serve /.well-known/openid-configuration, and it must advertise client_secret_post or client_secret_basic for client authentication. The contract below is the full list emisar checks.

OIDC contract#

Troubleshooting#

Use these checks for common sign-in symptoms. If the symptom is somewhere else in the product, start from troubleshooting, which routes each one to its owner page.

Security notes#

Every SSO sign-in lands in the audit log with its authentication method.