You operate Keycloak yourself. Phonemos needs a realm and OpenID Connect clients. Use Keycloak 26 or newer. High availability and sizing are described on Infrastructure Dependencies.

URL and realm

Set keycloak.url to the Keycloak base URL, including the /auth path if your distribution uses it, for example https://id.example.com/auth. Set keycloak.realm to the realm name. The issuer that Hasura validates is that URL plus /realms/ plus the realm name.

Both browsers and cluster pods must be able to reach Keycloak. If Keycloak uses a private certificate authority, mount the CA with global.ssl.caCertificates.

Clients

Create the following clients in the realm. The client IDs must match the Helm values.

Backend (confidential): keycloak.backend.clientId, for example phonemos-backend. Copy the client secret to keycloak.backend.clientSecret. The Phonemos backend uses this client for service calls to Keycloak.

Frontend / Hasura: keycloak.frontend.clientId, for example phonemos-hasura. Add a redirect URI of https://your-site/* for every host in sites. If the console is enabled, also add https://console-host/oauth2/callback. Allow the same hosts as web origins. Request the openid, email, and profile scopes. The Traefik console path also requests a hasura scope.

Public frontend: only if you use publicSites. Set the client ID and secret under keycloak.frontendPublic, and add redirect URIs for each public host.

Hasura JWT

Set hasura.jwtSecret to a JSON string. Use type RS256, a jwk_url that points at the realm certs endpoint, and an issuer that matches the realm URL. Set claims_format to stringified_json and claims_namespace_path to the document root. Map x-hasura-user-id to $.hasura.user, x-hasura-user-email to $.hasura.email, x-hasura-allowed-roles to $.hasura.roles, and x-hasura-default-role to $.hasura.roles[0].

The access token must contain a hasura object with user, email, and roles. Add this with a Keycloak protocol mapper on the frontend client. Write to support@linkyard.ch if you need the mapper definition for your Keycloak version.

Instance managers and the console

Create a Keycloak group whose name matches keycloak.instanceManagerGroup (the default is instance-managers) and add the users who may administer the instance.

When hasura.enableConsole is true, the chart exposes a console host. On a generic Ingress, /console goes directly to Hasura, so restrict that host. With Traefik IngressRoutes, oauth2-proxy sits in front of the console and requires oauth2Proxy.cookieSecret.