Enterprise SSO

Admin-plane sign-in is SSO-first: humans authenticate at an identity provider, and Agent Access Manager only validates the resulting token — signature, issuer, expiry, audience — and maps roles. Passwords and MFA live at the IdP, never in the gateway. The local Basic admin login remains as a break-glass credential.

This page explains the model; for step-by-step IdP setup see Keycloak & OIDC providers.

The three ways in

Method	Who uses it	How
Browser session via SSO	Dashboard users	Authorization-code flow at Keycloak or your OIDC IdP; the dashboard holds a session, not a token
OIDC Bearer token	Scripts, CI, service automation	`Authorization: Bearer <access-token>` on `/admin/**`
HTTP Basic (break-glass)	The platform admin, bootstrap and emergencies	`curl -u admin:password` — on by default until SSO is configured

The data plane (/v1/**) is untouched by all of this: applications always authenticate with virtual keys.

Bundled Keycloak or bring your own

Every edition can bundle Keycloak (served behind the same host at /auth, in production mode, on the bundled PostgreSQL). The installer renders the realm for your URL and prints the one-time admin password; first sign-in forces a change.

Alternatively, use your existing Keycloak, Microsoft Entra ID, Okta, Google, or any OIDC provider:

install with --idp custom and set AIM_OIDC_ISSUER_URI, AIM_OIDC_CLIENT_ID, AIM_OIDC_CLIENT_SECRET in deploy/.env, or
keep the bundled Keycloak and federate your IdP inside it (Identity Providers, or User Federation for LDAP/AD) with no app configuration change.

What the gateway validates

When an OIDC issuer is configured (aim.admin.oidc.issuer-uri), every Bearer token on /admin/** is checked for:

Signature against the issuer's published keys,
Issuer and expiry,
Audience — the token's aud must contain a configured value (aim.admin.oidc.audiences, conventionally aim-admin-api). Your IdP must be configured to emit it; most do not by default, and without it every token is rejected with 401.

Realm roles map to authorities: the realm role admin maps to the platform-admin authority required on /admin/** for platform-level operations. A token without the role gets 403. Org-level roles (owner, admin, operator, user, guest) are Agent Access Manager memberships — see Roles & permissions.

OIDC is additive: the Basic bootstrap admin keeps working as the break-glass credential, so existing scripts are unaffected when you turn SSO on.

Deploy-time by design

There are deliberately no write controls for authentication in the dashboard. SSO issuer, audiences, and whether form login is enabled are set in deployment configuration and at your IdP — so a compromised dashboard session cannot weaken sign-in. The dashboard's Settings page shows a read-only posture card (which methods are live, from GET /admin/auth/methods).

Hardening recommendations

Configure at the IdP (they require nothing from the gateway, which holds no session):

Short access-token lifespan (a few minutes) and refresh-token rotation with reuse detection.
Idle and absolute session caps.
MFA as a realm policy for admin users.
Watch Govern ▸ Sign-in activity for failed or suspicious admin logins.

Keycloak & OIDC providers — client, audience, and role setup per IdP.
Installation — bring your own identity provider.