Skip to content

Admin console login (helix-console client)

The Helix admin console signs in through a standard OpenID Connect client — helix-console — using the authorization code flow with PKCE, exactly like any other application you register. This means an admin's console login is a real single sign-on session: it appears on the Sessions screen and can be ended with Single Logout, the same as Keycloak's security-admin-console.

How it works

  1. Opening the console with no session redirects the browser to /realms/{realm}/oauth2/authorize?client_id=helix-console&… (authorization code + PKCE).
  2. You sign in on the normal login page (the same page as before — it is shown inside the authorize redirect, so you still enter your password once).
  3. The console completes the token exchange at /realms/{realm}/oauth2/token. That exchange is what registers the SSO session (the OIDC sid), so the login now shows on the Sessions screen.
  4. Admin API calls (/admin/**) continue to use the session cookie established during login — the token exchange only registers the session; it does not change how the admin API is authorized.

Sign-out performs RP-initiated logout (/realms/{realm}/connect/logout) so both the cookie session and the SSO session end together.

Seeding & configuration

helix-console is seeded automatically in every realm at startup and whenever a realm is created — no manual registration. It is a public client (no secret, PKCE required) with scopes openid profile.

Its redirect URI, web origin, and post-logout URI are derived from a single setting:

Setting Env var Default
Console base URL HELIX_CONSOLE_BASE_URL http://localhost:8180

Point this at the console's external base URL (scheme + host + port). On every startup the client's redirect_uri ({base}/console/callback), web origin ({base}), and post-logout URI ({base}/) are reconciled from it, so changing the deployment URL and restarting is all that's needed — no manual client edit.

Recovery (break-glass)

The console client is protected: it self-heals (recreated on the next restart if deleted) and the admin API refuses to delete it. If the client is ever misconfigured (for example a wrong HELIX_CONSOLE_BASE_URL), an admin can still sign in directly at the IdP login page — /realms/{realm}/login — to get a session and fix the configuration. This break-glass path is always available.

In the console

Because helix-console is a real OIDC client, it appears wherever clients do:

  • Under Manage → Applications & clients → OIDC/SAML clients it shows as Helix Admin Console, a public client (PKCE) with scopes openid profile. You can inspect it, but the admin API and self-heal keep it from being deleted or renamed away.
  • Under Manage → Users & access → Sessions, an admin's console login shows as an active SSO session that can be ended with Single Logout — see Sessions.

Over the API

helix-console is listed and read like any other client under /admin/realms/{realm}/clients. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

# It surfaces in the normal clients list
curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/clients"

[
  { "clientId": "helix-console", "name": "Helix Admin Console", "publicClient": true, "grantTypes": ["authorization_code","refresh_token"] }
]

Protected client

A DELETE against the helix-console client is refused, and if it is ever removed out-of-band it is recreated on the next restart. Do not manage its redirect_uri / web origin by hand — they are reconciled from HELIX_CONSOLE_BASE_URL on every startup.

See also