Add an identity provider to Platform Base

This guide connects an existing OpenID Connect identity provider (IdP) to the platform realm of Keycloak, so that users can sign in to Argo CD and Grafana with their existing accounts. See Identity and access for how this fits together.

Store the client secret

Register Platform Base as an OpenID Connect client at your IdP and note the client ID and the client secret. Then create a Secret with the client secret in the iam namespace:

kubectl -n iam create secret generic corp-idp \
  --from-literal=clientSecret='<client secret>'

Keycloak reads the secret as a file through its file vault. It never appears in the Keycloak configuration.

Configure the provider

Add the provider to cluster/config.libsonnet, under the realm it belongs to (platform or master). The key (corp) names the provider in your configuration:

iam+: {
  realms+: {
    platform+: {
      identityProviders+: {
        corp: {
          id: 'corp',
          displayName: 'Corporate login',
          issuer: 'https://idp.example.com/realms/corp',
          authorizationURL: 'https://idp.example.com/realms/corp/protocol/openid-connect/auth',
          tokenURL: 'https://idp.example.com/realms/corp/protocol/openid-connect/token',
          userInfoURL: 'https://idp.example.com/realms/corp/protocol/openid-connect/userinfo',
          jwksURL: 'https://idp.example.com/realms/corp/protocol/openid-connect/certs',
          logoutURL: 'https://idp.example.com/realms/corp/protocol/openid-connect/logout',
          oidc+: {
            clientID: 'platform',
            clientSecret+: {
              secretRef: { name: 'corp-idp', key: 'clientSecret' },
            },
          },
        },
      },
    },
  },
},

Set id, displayName and all six URLs explicitly. id becomes the alias of the provider in Keycloak and cannot be changed later.

These options have defaults:

Option	Default	Meaning
mode	oidc	Keycloak provider type.
clientAuthMethod	client_secret_post	How Keycloak authenticates at the token endpoint.
defaultScope	['openid']	Scopes Keycloak requests.
useJwksURL	true	Fetch signing keys from jwksURL.
validateSignature	true	Validate the signature of tokens.
pkceEnabled	false	Use PKCE.
syncMode	FORCE	Keycloak's sync mode for imported user data.
allowAdminRoleMapping	false	Required for mappers that grant an admin role or group.
mappers	[]	Identity provider mappers.

To let Platform Base create the Secret instead, set clientSecret+: { value: '...' } and leave out secretRef. Pass the value through dynamicConfig when you render the bootstrap instead of committing it. It is stored in Argo CD Application objects either way, see Secret values.

Register the redirect URI

Register this redirect URI at your IdP, with your iam hostname, the realm and the id of the provider:

https://iam.<baseDomain>/realms/platform/broker/<id>/endpoint

Map groups for Argo CD and Grafana

Argo CD reads the groups claim, which Keycloak builds from the user attribute groups. To fill it from a claim of your IdP, add an attribute importer mapper to the provider:

mappers: [
  {
    name: 'groups',
    identityProviderMapper: 'oidc-user-attribute-idp-mapper',
    config: { claim: 'groups', 'user.attribute': 'groups' },
  },
],

Then bind a group to an Argo CD role in argocd.rbac, see Customize Argo CD. Grafana takes the role of a user from the roles claim, see Identity and access. If a mapper grants an admin role or an admin group, set allowAdminRoleMapping: true on the provider and keep it set while the mapper exists.