AethosHub
PricingRequest Demo

DocumentationAgent Access Manager

Keycloak & OIDC providers

Keycloak & OIDC providers

Admin sign-in is SSO-first (the model is explained in Enterprise SSO). This page is the setup reference: the bundled Keycloak, your own Keycloak or IdP as the issuer, and federation — plus the three configuration details that cause most integration failures.

Option 1 — the bundled Keycloak (default)

Every standalone install bundles Keycloak behind the same host at /auth, in production mode, on the bundled PostgreSQL. The installer renders the realm for your public URL, and prints a one-time admin password; first sign-in forces a change. Nothing to configure.

Administer it at https://<host>/auth/admin — this is also where you set MFA policies, token lifespans, and session caps.

Option 2 — your own IdP (Keycloak, Entra ID, Okta, Google)

  1. Register a confidential OIDC client (authorization-code flow) with redirect URI:

    TEXT
    https://<your-host>/login/oauth2/code/aim-dashboard

  2. Add the audience. Tokens must carry aim-admin-api in aud. In Keycloak that is an Audience protocol mapper on the client or a client scope; in Entra/Okta, an equivalent audience/claim configuration. IdPs do not emit custom audiences by default — without this, every token is rejected with 401.

  3. Map the admin role. Map your admin group to a realm role named admin; it becomes the platform-admin authority (ROLE_ADMIN) on /admin/**. A token without it gets 403.

  4. Configure the gateway in deploy/.env and install with --idp custom (omits the bundled Keycloak):

    Command
    AIM_OIDC_ISSUER_URI=https://keycloak.example.com/realms/aimanager
AIM_OIDC_CLIENT_ID=aim-dashboard
AIM_OIDC_CLIENT_SECRET=...

    Setting the issuer is what turns OIDC on; the audience list is required alongside it. OIDC is additive — the break-glass Basic admin keeps working.

Option 3 — federate inside the bundled Keycloak

Keep the bundled Keycloak as the issuer and connect your corporate identity behind it: Identity Providers (another OIDC/SAML IdP) or User Federation (LDAP / Active Directory) in the Keycloak console. No gateway configuration changes at all — useful when you want AD sign-in without touching your central IdP's app catalogue.

Verifying a token by hand

Command
# Obtain a token from the IdP (direct-access grant, for testing only)
TOKEN=$(curl -s -X POST "$ISSUER/protocol/openid-connect/token" \
  -d grant_type=password -d client_id=$CLIENT -d username=$USER -d password=$PASS \
  | jq -r .access_token)

# Call the Admin API with it
curl -s -i -H "Authorization: Bearer $TOKEN" https://aam.example.com/admin/me

401 means the token failed validation — most often the missing audience. 403 means it validated but lacks the admin realm role.

Hardening checklist

All at the IdP, which requires nothing from the gateway:

  • Short access-token lifespan (a few minutes); the gateway holds no session and validates every request.
  • Refresh-token rotation with reuse detection; idle and absolute session caps.
  • MFA as a realm policy for admin users.
  • Once SSO is verified, treat the Basic admin strictly as break-glass and monitor Govern ▸ Sign-in activity.