> This page is for Agent Handler.

> 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 Agent Handler dashboard with Okta, Azure AD, Google Workspace, and other OIDC providers.

Single sign-on lets your team members log in to the Agent Handler dashboard through your identity provider - Okta, Azure AD, Google Workspace, or any OIDC-compliant IdP - instead of managing a separate Agent Handler password. It's the prerequisite for [SCIM provisioning](/merge-agent-handler/administer/scim) and is usually the first thing your security team will ask for.

SSO covers dashboard access only. It doesn't change how end users authenticate to Connectors (that's still [Link](/merge-agent-handler/build/authentication/link)) and doesn't change the MCP URL's auth model.

## Before you start

You need admin access to your IdP and a role with the **Manage users** permission in Agent Handler (both Admin and Security have it). Once you flip "require SSO" on, members who haven't completed first-time SSO will be locked out - fully 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 [Settings → Single sign-on](https://ah.merge.dev/settings/sso).
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 Agent Handler API host (`ah-api.merge.dev`), not the dashboard host (`ah.merge.dev`), 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. Agent Handler requests exactly those three.
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 Agent Handler reads the authorization, token, and JWKS endpoints from it.
5. Paste all three into the dialog and click **Save configuration**.
6. Turn on the **Enable SSO** toggle. A saved configuration is inactive until you do, and you cannot require SSO while it's off.

Test the flow before requiring it. Open an incognito window, go to [ah.merge.dev/login/sso](https://ah.merge.dev/login/sso), enter your work email. You should bounce through your IdP and back to the dashboard.

> **SSO logs in existing members, it doesn't create them**
>
> The email you enter has to already belong to an Agent Handler member. SSO authenticates people; it doesn't provision them. Invite them from Settings or provision them with [SCIM](/merge-agent-handler/administer/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://<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 Agent Handler.

#### 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/<TENANT_ID>/v2.0/.well-known/openid-configuration`.
6. Copy the application (client) ID and the client secret into Agent Handler.

#### 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. Agent Handler has no domain allowlist of its own; it only lets through emails that already belong to a member of your organization.

#### Other OIDC providers

Any OIDC-compliant IdP works. You need:

* A discovery document at `<ISSUER>/.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. Agent Handler validates that the value ends in `.well-known/openid-configuration` and fetches the endpoints from it at save time, so an unreachable document fails the save.

## Requiring SSO

Once SSO works for your account, you can require it across the org. Turn on **Require SSO** in [Settings → Single sign-on](https://ah.merge.dev/settings/sso). The toggle needs a saved configuration with **Enable SSO** already on, and while **Require SSO** is on you cannot delete the configuration. After it's on:

* Members can no longer log in with email and password. The password form returns the same "unable to log in" error it returns for a wrong password, so members won't be told why.
* Password reset stops working too. Requesting a reset email silently does nothing, and an already-issued reset link is rejected.
* Members not in the IdP Groups assigned to the Agent Handler app cannot log in at all.

Invitations don't change. An invited member still sets a password when accepting the invite, they just can't use it to log in while SSO is required.

Switch this on once your team is fully provisioned in the IdP. The admin who toggles it can lock themselves out if their IdP account isn't set up correctly - test in incognito first.

## How SSO interacts with email/password

If you don't require SSO, both auth methods work in parallel. Members can log in either way. This is useful during rollout - you can configure SSO without forcing migration.

After **Require SSO** is on, only the SSO path works. To hand password access back to a member, turn **Require SSO** off first.

## What SSO doesn't do

SSO authenticates the dashboard only. Provisioning users (and mapping IdP Groups to Agent Handler roles) is [SCIM](/merge-agent-handler/administer/scim). End-user auth to Connectors is still [Link](/merge-agent-handler/build/authentication/link) or [Magic Link](/merge-agent-handler/build/authentication/magic-link). MCP URL auth is an [Access Key](/merge-agent-handler/administer/access-keys) for [Building an agent](/merge-agent-handler/setup/building-an-agent), and OAuth-through-IdP for [Agent Handler for Employees](/merge-agent-handler/setup/agent-handler-for-employees).

## Next

Auto-provision and deprovision members from your IdP with [SCIM provisioning](/merge-agent-handler/administer/scim).