Skip to main content

Admin Console SSO

Tasks

Let administrators sign in to the AIControls web console with your identity provider (Google Workspace, Azure AD / Microsoft Entra ID, Okta, or any OpenID Connect provider) instead of the local password.

Prerequisites​

  • AIControls admin access (to reach Settings → SSO/OIDC)
  • An OIDC application registered with your identity provider
  • Permission to add a redirect URI to that application

Register the redirect URI​

The admin console uses a dedicated callback path. In your identity provider, register this exact redirect URI:

https://YOUR_CONSOLE_URL/auth/oidc/callback
warning

The admin console callback is /auth/oidc/callback. This is different from the developer-portal (User Auth) callback, which is /auth/callback. Registering the wrong path routes the admin sign-in to the wrong handler and login fails.

Configure Admin SSO​

  1. Go to Settings → SSO/OIDC → Admin SSO.
  2. Choose your provider (Google Workspace, Azure AD, Okta, or Custom OIDC). For Azure AD, enter the Tenant ID — the issuer URL is derived automatically.
  3. Enter the Client ID and Client Secret from your registered application.
  4. Set the Redirect URL to https://YOUR_CONSOLE_URL/auth/oidc/callback.
  5. Optionally set Allowed Emails — an allowlist of addresses permitted to sign in. Leave it blank to allow any user your IdP authenticates.
  6. Toggle Enabled and click Save Admin SSO. Changes take effect immediately — no restart required.

Azure AD / Microsoft Entra ID​

Azure AD v2 ID tokens do not include an email claim by default — identity is carried in upn or preferred_username. AIControls resolves the signed-in identity in the order email → upn → preferred_username, so Azure AD works without any extra claim configuration, including when an Allowed Emails allowlist is set (the allowlist is matched against the resolved identity).

tip

If you prefer an explicit email claim, add it in the Azure app registration under Token configuration → Add optional claim → ID → email. It is optional — the upn / preferred_username fallback handles sign-in either way.

An admin who signs in via SSO is matched to their existing console account by the resolved identity, so their existing role (e.g. Admin) is preserved. Allowed Emails only gates whether sign-in is permitted; it does not grant a role.

Password sign-in fallback​

When Admin SSO is enabled, the login page redirects to your identity provider automatically. A Sign in with password instead link is always shown on the login page so you can fall back to the local admin password — for example if the IdP is misconfigured or unreachable. You can also reach the password form directly at:

https://YOUR_CONSOLE_URL/ui/login?password=1

If a sign-in is rejected (for example, the account is not in the Allowed Emails list), the login page shows the reason so you can correct the configuration.

Disabling SSO​

Toggle Enabled off and click Save Admin SSO. The setting is authoritative and persists across restarts — the console returns to password sign-in immediately.

Last updated on