Provisioning

Single sign-on

Authenticate dashboard admins through your identity provider

Single sign-on lets your admins sign in to the Workforce dashboard through your identity provider (Okta, Azure AD, Google Workspace, or any OIDC-compliant IdP) instead of a separate Merge password. It is the prerequisite for SCIM provisioning, and usually the first thing your security team asks for.

SSO covers dashboard sign-in. Employee AI clients authenticate over OAuth through the same identity provider, which is a separate flow: see Connect employee AI clients.

Before you start

You need admin access to your IdP and a role carrying the Manage users permission. Once you turn on Require SSO, anyone who has not completed a first SSO sign-in is locked out, so provision your team in the IdP first.

Setting up OIDC

The flow is the same for every OIDC-compliant IdP. The specific clicks differ.

  1. Open Provisioning → Sync.

  2. Click Configure SSO. The dialog shows the callback URL to register with your IdP:

    https://ah-api.merge.dev/sso/oidc/callback/

    Copy it from the dialog rather than typing it. It points at the Merge API host, not the dashboard host, and the trailing slash is part of the URL. Most IdPs require an exact match, so a missing slash or the wrong host fails the exchange.

  3. From your IdP, register a new OIDC web application. Set the callback URL above as the allowed redirect URI, and grant the openid, email, and profile scopes. Those three are all that is requested.

  4. Copy the Discovery URL, Client ID, and Client secret from your IdP. The discovery URL is the full .well-known/openid-configuration document, not the bare issuer, because the authorization, token, and JWKS endpoints are read from it.

  5. Paste all three into the dialog and click Save configuration.

  6. Saving turns Enable SSO on for you, so there is no second toggle to flip. The toggle under SSO settings is how you turn SSO back off, and Require SSO stays unavailable while it is off.

Test the flow before requiring it. Open an incognito window, sign in with your work email, and you should bounce through your IdP and back to the dashboard.

SSO signs in existing members, it does not create them

The email you enter has to already belong to a member of your organization. SSO authenticates people; it does not provision them. Invite them from Team and roles, or provision them with SCIM first.

Per-IdP setup

  1. Okta Admin Console → Applications → Create App Integration → OIDC - OpenID Connect → Web Application.
  2. Sign-in redirect URI: https://ah-api.merge.dev/sso/oidc/callback/.
  3. Assign the application to the Groups that should have dashboard access.
  4. From the application’s General tab, copy the Client ID and Client secret.
  5. Discovery URL: https://<your-org>.okta.com/.well-known/openid-configuration. If you scoped the app to a custom authorization server, use https://<your-org>.okta.com/oauth2/<AUTH_SERVER_ID>/.well-known/openid-configuration instead.
  6. Paste all three into the dialog.

Requiring SSO

Once SSO works for your own account, you can require it across the organization. Turn on Require SSO under SSO settings on the same Sync tab, and confirm the dialog that warns you about lockout. The toggle needs a saved configuration with Enable SSO already on, and while Require SSO is on you cannot disconnect the configuration. After it is on:

  • Password sign-in stops working. The form returns the same “Unable to log in with provided credentials” error it returns for a wrong password, so members are not told why
  • Password reset stops working too. Requesting a reset email silently does nothing, and an already-issued reset link is rejected
  • Anyone outside the IdP Groups assigned to the application cannot sign in at all

Invitations do not change. An invited member still sets a password when accepting the invite, but cannot use it to sign in while SSO is required. Turning Enable SSO back off turns Require SSO off with it.

Leave Require SSO off during rollout and both methods work in parallel, so you can configure and test SSO without forcing a migration. Switch it on once your team is fully provisioned in the IdP. The admin who toggles it can lock themselves out if their own IdP account is not set up correctly, so test in incognito first.

Next

Auto-provision and deprovision employees and Groups from your IdP with SCIM provisioning.