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 — using the same SSO / OIDC configuration you already set up for the developer portal and AI clients.

Prerequisites

• AIControls admin access (to reach Settings → SSO/OIDC)
• An OIDC application registered with your identity provider — typically the same application registration already used for developer portal and AI client SSO
• Permission to add a redirect URI to that application

Register the redirect URI

The admin console uses a dedicated callback path, separate from the developer portal's. In your identity provider, register this exact redirect URI in addition to the developer portal's /auth/callback value, on the same client:

https://YOUR_CONSOLE_URL/auth/oidc/callback

warning

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

Turn on console login access

1. Go to Settings → SSO / OIDC. If it isn't configured yet, set it up first — see Link Your Enterprise Identity or OIDC provider fields.
2. Scroll to Console login access and toggle Also use this provider for admin console sign-in.
3. Set Console Redirect URL to https://YOUR_CONSOLE_URL/auth/oidc/callback — the redirect URI you just registered.
4. Optionally set Allowed Emails — an allowlist of addresses permitted to sign in to the admin console. Leave it blank to allow any user your IdP authenticates. This restricts console sign-in only; it has no effect on developer portal or AI client sign-in through the same provider.
5. Click Save. Changes take effect immediately — no restart required.

One identity provider registration now covers the developer portal, AI clients, and the admin console.

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 console sign-in 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.

Sign out and RP-initiated logout

By default, Sign out only ends your AIControls session — your identity provider's own session stays active. If you then land back on the login page, SSO's automatic redirect can silently sign you back in without prompting for credentials.

To also end the IdP session on sign-out, enable End IdP Session on Sign-Out under Settings → SSO / OIDC → Console login access. When enabled, sign-out redirects your browser to your identity provider's logout endpoint before returning you to the password sign-in form. Not every IdP or tenant configuration permits this (some require additional app-registration settings, such as a front-channel logout URL) — test sign-out after enabling it to confirm your IdP accepts the redirect.

The redirect applies only to sessions that were established through SSO. An administrator who signed in with a password (the break-glass fallback) has no IdP session to end, so their sign-out clears the local session only and lands on the password form directly.

Disabling console SSO

Toggle Also use this provider for admin console sign-in off and click Save. The setting is authoritative and persists across restarts — the console returns to password sign-in immediately. Developer portal and AI client sign-in through the same provider are unaffected.

Using a different identity provider for the admin console

The steps above point the admin console at the same identity provider already configured for the developer portal and AI clients — the right choice for almost every deployment. If you genuinely need the admin console to authenticate against a different identity provider than the one used everywhere else (for example, a stricter corporate IdP for administrators versus a lighter-weight one for developers), that configuration still exists as a separate, advanced option. Contact your AIControls representative to have it enabled for your workspace.