Skip to main content

Single Sign-On (SSO)

Connect EnClaw to your corporate identity provider so users sign in with the credentials they already have. Once configured, the workspace becomes "Sign in with [your IdP]" — no EnClaw-specific passwords to manage.

Best done before inviting users. New users invited after SSO is configured will go straight through SSO on their first click; new users invited before will create a local-password account and you'll have to migrate them later.

Supported providers​

ProviderProtocolStatusDetailed guide
Microsoft Entra ID / Azure ADOIDC✅ Productiondocs/integrations/sso/azure-ad-oidc.md (in the repository)
Microsoft Entra ID / Azure ADSAML 2.0🟡 Supported, no dedicated guide yetSee OIDC guide + adapt
OktaOIDC✅ Productionstub — coming
Google WorkspaceOIDC✅ Productionstub — coming
Ping IdentityOIDC✅ Productionstub — coming
Generic OIDC IdPOIDC⚠️ Manual configask EnClaw support

Most customers use Azure AD OIDC — it's the default in the dropdown, the docs are the most polished, and group-sync (mapping AD groups → EnClaw teams) is fully wired only for Azure AD today.

High-level flow​

  1. On the IdP side (Azure portal, Okta dashboard, etc.): register EnClaw as an application, grant it the permissions it needs, copy out a few credentials.
  2. On the EnClaw side (/integrations → SSO Configurations): paste those credentials into a new SSO config row, mark it active.
  3. Test by signing out and signing back in with an SSO-enabled email.

Each detailed guide (linked above) walks the IdP-side steps. The EnClaw-side step is the same regardless of provider — see EnClaw-side configuration below.

Callback URL — the one thing you MUST get right​

Every SSO setup needs EnClaw's callback URL registered as an allowed redirect URI on the IdP side. The format is:

https://<your-enclaw-api-host>/api/auth/sso/callback

The <your-enclaw-api-host> is the API hostname — typically the user-facing hostname with -api prefixed (e.g. web is app.enclaw.com, API is app-api.enclaw.com). Your operator can confirm.

If you're a platform operator running multiple SaaS environments against the same Azure AD app, register all callback URLs at once:

https://your-org-api.enclaw.com/api/auth/sso/callback       ← customer prod
https://app-api.enclaw.com/api/auth/sso/callback            ← saas-prod
https://stage-app-api.enclaw.com/api/auth/sso/callback      ← saas-stage
https://dev-app-api.enclaw.com/api/auth/sso/callback        ← saas-dev

A single Azure AD app can hold many redirect URIs and there's no security downside. The alternative (one app reg per env) means N sets of client secrets to manage in GitHub Actions — strictly worse.

The Microsoft error code if you miss this is AADSTS50011 ("redirect URI does not match"). Add the URI in Entra → App registrations → Authentication and the error clears.

EnClaw-side configuration​

Once your IdP registration is done and you have the four pieces of info you need (tenant ID, client ID, client secret, plus optionally an issuer URL):

  1. Sign in as super_admin / platform_admin.
  2. Go to /sso-providers (or /integrations → SSO Configurations — same page).
  3. Click + Add SSO configuration.
  4. Pick the provider, paste:
    • Tenant ID (Azure AD directory ID, Okta org URL, etc.)
    • Client ID (application ID)
    • Client secret (the Value you copied at create-time, not the Secret ID)
    • Display name — what users see on the "Sign in with X" button (e.g. "Your Org Microsoft")
  5. Leave OIDC URLs blank if your provider is Azure AD or a major OIDC IdP — EnClaw discovers them from the issuer.
  6. Tick Is active.
  7. Click Save.

Sign out, then visit /login, enter an email matching your IdP's domain — the "Sign in with [Display name]" button should appear.

Group-sync (Azure AD only)​

Once SSO works, you can auto-map AD security groups to EnClaw teams so a user added to AD group EnClaw-Engineering automatically lands in the Engineering team with the role you set on that team. This is configured under /sso-providers → Edit → Group mappings after SSO itself is verified working.

Full detail in docs/integrations/sso/azure-ad-oidc.md (in the repository) (section "Token configuration" → "Groups claim").

Next​