> This page is for Workforce. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Single sign-on > How to configure SSO for the Workforce dashboard with Okta, Azure AD, Google Workspace, and other OIDC providers. 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](/merge-workforce/provisioning/scim), 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](/merge-workforce/rollout/employee-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](https://wf-develop.merge.dev/groups/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](/merge-workforce/settings/team-and-roles), or provision them with [SCIM](/merge-workforce/provisioning/scim) first. ## Per-IdP setup #### Okta 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://.okta.com/.well-known/openid-configuration`. If you scoped the app to a custom authorization server, use `https://.okta.com/oauth2//.well-known/openid-configuration` instead. 6. Paste all three into the dialog. #### Azure AD / Entra ID 1. Azure portal → **Microsoft Entra ID → App registrations → New registration**. 2. Redirect URI (Web): `https://ah-api.merge.dev/sso/oidc/callback/`. 3. Under **Certificates & secrets**, create a new client secret. Copy it now. 4. Under **Token configuration**, add `email` and `profile` claims. 5. Discovery URL: `https://login.microsoftonline.com//v2.0/.well-known/openid-configuration`. 6. Copy the application (client) ID and the client secret into the dialog. #### Google Workspace 1. Google Cloud Console → **APIs & Services → Credentials → Create credentials → OAuth client ID → Web application**. 2. Authorized redirect URI: `https://ah-api.merge.dev/sso/oidc/callback/`. 3. Copy the client ID and client secret. 4. Discovery URL: `https://accounts.google.com/.well-known/openid-configuration`. 5. Control who can sign in from the Google side, by limiting which users the OAuth client is available to. There is no domain allowlist on the Merge side; only emails that already belong to a member of your organization are let through. #### Other OIDC providers Any OIDC-compliant IdP works. You need: * A discovery document at `/.well-known/openid-configuration`, exposing `authorization_endpoint`, `token_endpoint`, and `jwks_uri` * Client ID * Client secret * Ability to register `https://ah-api.merge.dev/sso/oidc/callback/` as a redirect URI Paste the full discovery URL, not the bare issuer. The value is validated to end in `.well-known/openid-configuration` and the endpoints are fetched from it at save time, so an unreachable document fails the save. ## 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](/merge-workforce/provisioning/scim).