Skip to Content
CraftBot Docs v1 — internal preview
Admin & SettingsSingle Sign-On

Single Sign-On

The Single Sign-On page lets an administrator connect CraftBot to your organisation’s identity provider so users sign in with their existing corporate account instead of a CraftBot-specific password. It is restricted to Admin and Super Admin, and lives at Settings → Administration → Single Sign-On.

CraftBot supports OpenID Connect (OIDC) identity providers — Microsoft Entra ID, Okta, and Google Workspace are the common ones. SAML is not supported.

Before you start

You will need an OIDC application registered in your identity provider. During that registration the IdP asks for a redirect URI — the URL it sends users back to after they authenticate. CraftBot shows the exact value to use in a banner at the top of the Single Sign-On page:

{your-app-origin}/auth/sso/callback

Register that URL in your IdP application before adding the provider in CraftBot, otherwise sign-in will fail with a redirect-mismatch error.

Adding a provider

  1. Go to Settings → Single Sign-On and click Add provider. The form opens as a modal popup on top of the providers table.
  2. Display name — the label shown on the login-page SSO button (e.g. “Acme Entra ID”). Users see “Sign in with {display name}”.
  3. Issuer URL — the OIDC issuer for your provider. For Microsoft Entra ID this looks like https://login.microsoftonline.com/<tenant>/v2.0; Okta and Google Workspace have their own issuer URLs.
  4. Client ID — the application (client) ID from your IdP registration.
  5. Client secret — the client secret generated by your IdP. It is stored encrypted and is never displayed again after you save. To replace it later, tick Rotate client secret on the edit modal and enter a new value.
  6. Scopes — the OIDC scopes requested at sign-in. The default openid email profile is sufficient for most setups.
  7. Default role — the CraftBot role given to an auto-provisioned user when no role mapping matches (admin / supervisor / agent / readonly).
  8. Role claim — the name of the ID-token claim that carries the user’s IdP group names (commonly groups).
  9. Role mappings — map an IdP group name to a CraftBot role. A user whose token lists a mapped group is provisioned with that role; if several map, the strongest applies.
  10. Auto-provision — when on, an unknown user signing in via SSO for the first time gets a CraftBot account created automatically (JIT provisioning). When off, only users who already have a CraftBot account can sign in via this provider.
  11. Enforce SSO — a flag indicating this tenant intends SSO-only sign-in. Note: tenant-wide disabling of password login is not yet enforced — the flag is stored for a future release.
  12. Enabled — only enabled providers appear on the login page. You can enable several providers at once; each enabled provider gets its own Sign in with {display name} button on the login page, so users can choose which identity provider to authenticate with.
  13. Click Save. The provider appears in the table and, if enabled, on the login page immediately.

Editing a provider

Click Edit on a provider row to reopen the modal with the current values. The client secret is never shown — leave Rotate client secret unticked to keep the existing secret, or tick it to supply a replacement.

Deleting a provider

Click Delete to remove a provider. Its button disappears from the login page. Users previously provisioned via that provider keep their CraftBot accounts; they fall back to password sign-in (or another configured provider).

How sign-in works

  • On the login page, an enabled provider shows as a Sign in with {display name} button. Clicking it redirects the user to the identity provider to authenticate, then back to CraftBot through the /auth/sso/callback page (a brief “Completing sign-in…” screen) and on to their landing page.
  • First-time users are auto-provisioned when Auto-provision is on: a CraftBot account is created from the IdP identity, IdP groups are mapped to a role via your Role mappings, and if no mapping matches the Default role is used.
  • Existing password users whose email matches the SSO identity are automatically linked to SSO on their first SSO sign-in — no duplicate account is created, and they can continue to sign in either way.

Best practices

  • Register the redirect URI in your IdP exactly as shown in the page banner before adding the provider.
  • Prefer Role mappings over a permissive Default role — set the default to readonly or agent so an unmapped user never lands with elevated access.
  • Rotate the client secret on a schedule using the Rotate client secret checkbox; the old secret is replaced immediately on save.
  • Keep at least one Super Admin with a working password while SSO is being set up, so a misconfigured provider can’t lock you out.
Last updated on
Healthcare blocklistTenant