Keycloak

Suggested reading

Read the Identity overview first to understand the IdentityProvider resource, userInfoPrefix, and claim mappings.

Configure a Keycloak realm as a Hub identity provider. Keycloak is standards-compliant out of the box: it emits a groups claim once you enable the group mapper, so you don't need claim-mapping overrides.

Prerequisites

• A Keycloak realm.
• Admin access to the realm to add a client and configure protocol mappers.

Provider-side setup

1. Client. In the Keycloak admin console, create a new confidential client for Hub. Set:
   • Client authentication: on.
   • Standard flow (authorization code): enabled.
   • Valid redirect URIs: https://<hub-url>/oidc/callback.
   • Record the client ID and client secret (Credentials tab).
2. Groups mapper. Under the client's Client scopes → dedicated scope → Add mapper > By configured type > Group Membership:
   • Token Claim Name: groups.
   • Full group path: off (unless you want paths like /eng/backend).
   • Add to ID token: on.
   • Add to access token: on.
   • Add to userinfo: on.

IdentityProvider resource

apiVersion: iam.hub.upbound.io/v1beta1
kind: IdentityProvider
metadata:
  name: keycloak
spec:
  redirect:
    browserLogin: true
    clientSecret: "<client-secret>"
    scopes:
      - openid
      - email
      - profile
  validation:
    issuer:
      # Take from the realm's .well-known/openid-configuration issuer field.
      url: https://sso.example.com/realms/<realm-name>
      audiences:
        - <client-id>
    claimMappings:
      username:
        claim: email
      groups:
        claim: groups
    claimValidationRules:
      - expression: "claims.email_verified == true"
        message: "email must be verified"

Role bindings then reference groups as keycloak:<group-name> and users as keycloak:<email>.

Notes

• Take the issuer.url value from the realm's discovery document at https://sso.example.com/realms/<realm-name>/.well-known/openid-configuration. It must match the issuer field there.
• If your Keycloak deployment uses a self-signed or private CA, add the CA certificate under spec.validation.issuer.certificateAuthority (PEM).

Configure the directory

To let Hub search the realm for groups and users (see Directory sync), give Hub a client that can query the Admin REST API. Create a confidential client with Service accounts roles enabled, and assign its service account the query-groups and view-users roles from the realm-management client. Then add a directory block alongside the login configuration:

spec:
  # ...redirect and validation as above
  directory:
    # The groups mapper above emits group names, not IDs.
    groupClaimType: DisplayName
    # Matches the email username mapping above.
    userClaimType: Email
    config:
      apiVersion: directory.hub.upbound.io/v1alpha1
      kind: KeycloakConfiguration
      baseURL: https://sso.example.com
      realm: <realm-name>
      clientID: "<directory-client-id>"
      clientSecret: "<directory-client-secret>"

Field	Required	Description
baseURL	yes	Base URL of the Keycloak instance, without /realms/.... Must use https://.
realm	yes	The realm to query for groups and users.
clientID	yes	Client ID of the client whose service account holds the realm-management roles.
clientSecret	yes	That client's secret. Read back as ***.

Group search matches any part of the group name. If you left the username on sub, use userClaimType: DirectoryID instead: Keycloak's sub is the user's ID.

Next step

With the provider registered, decide what its identities may do: Access management covers binding the prefixed usernames and groups above to Hub roles.