Administer

Single sign-on

Authenticate dashboard members through your identity provider.

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 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) and doesn’t change the MCP URL’s auth model.

Before you start

You need admin access to your IdP and the Admin role in Agent Handler. 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.
  2. Click Configure OIDC.
  3. From your IdP, register a new OIDC application. Use these fields:
    • Redirect URI: https://ah.merge.dev/sso/callback
    • Sign-out URL: https://ah.merge.dev/sso/logout
    • Scopes: openid, email, profile
  4. Copy the Issuer URL, Client ID, and Client Secret from your IdP.
  5. Paste them into Agent Handler’s OIDC configuration form.
  6. Save.

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

Per-IdP setup

  1. Okta Admin Console → Applications → Create App Integration → OIDC - OpenID Connect → Web Application.
  2. Sign-in redirect URI: https://ah.merge.dev/sso/callback.
  3. Sign-out redirect URI: https://ah.merge.dev/sso/logout.
  4. Assign the application to the Groups that should have dashboard access.
  5. From the application’s Sign On tab, copy the Issuer, Client ID, and Client Secret.
  6. Paste into Agent Handler.

Requiring SSO

Once SSO works for your account, you can require it across the org. After enabling Require SSO in Settings → Single sign-on:

  • Members can no longer log in with email and password.
  • New invitations skip the password setup step - invited members go straight to your IdP on first login.
  • Members not in the IdP Groups assigned to the Agent Handler app cannot log in at all.

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. Members with existing passwords can still reset them, but the password login form rejects them.

What SSO doesn’t do

SSO authenticates the dashboard only. Provisioning users (and mapping IdP Groups to Agent Handler roles) is SCIM. End-user auth to Connectors is still Link or Magic Link. MCP URL auth is an Access Key for Building an agent, and OAuth-through-IdP for Context layer for employees.

Next

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