Keycloak

Prerequisites

Complete the preparation checklist.

Application setup

Select the intended realm in the Keycloak Admin Console. Create an OpenID Connect client with Client authentication on and Standard flow on. Set Valid redirect URIs to https://api.<platform-host>/identity/callback and Valid post logout redirect URIs to https://<platform-host> (plus any other approved frontend addresses). Require S256 PKCE where the client policy offers it. Save, then collect the client secret from Credentials.

Use your Istari domain for <platform-host>. For a custom API hostname or base URL, use the configured callback address.

Collected values

Collect the Client ID and secret. Open Realm settings > General > OpenID Endpoint Configuration and copy its issuer field, including /realms/<realm>. Do not use the admin-console address or the OpenID configuration URL itself.

Installation configuration

istari-values.yaml (excerpt)

identity:
  oidc:
    provider: keycloak
    issuer: "https://<keycloak-host>/realms/<realm>"
    clientId: "<client-id>"
    clientAuthMethod: client_secret_basic
    scopes: "openid profile email offline_access"
  idpMigration:
    enabled: false

Store ISTARI_DIGITAL_IDENTITY_SERVICE_OIDC_CLIENT_SECRET in the Identity Service Secret. Keep ISTARI_DIGITAL_IDENTITY_SERVICE_ENROLLMENT_POLICY=open for the email-based recipe below.

Account preparation

Pre-register new users with import-humans -provider keycloak. Their verified email claims the matching account. For existing users, follow Switch to Keycloak and preserve the provider-to-tenant mappings.

For email pre-registration under pre-registered-only, sign-in also needs a mapped upstream grouping. Keycloak's realm is not inferred from the issuer URL: supply an upstream_tenant_id claim, or set identity.oidc.defaultTenantId for a single grouping, and map that value with create-tenant -provider-name keycloak -provider-tenant-id <grouping-id>.

See account import commands and administrator setup.

Verification

Confirm verified email claims the prepared principal and tenant. Open enrollment can admit a separate account when email linking fails; stop the cutover if a migrated user reaches a different principal. Test refresh, upstream logout, existing ownership, and sharing.

Limitations

Private-key JWT and client-secret authentication are supported. Keycloak groups do not automatically become Istari roles. See Keycloak's OIDC endpoint reference.