cd/docs/operator-manual/user-management/keycloak.md

Keycloak

Keycloak and Hanzo CD integration can be configured in two ways with Client authentication and with PKCE.

If you need to authenticate with the cd command line, you must choose PKCE way.

• Keycloak and Hanzo CD with Client authentication
• Keycloak and Hanzo CD with PKCE

Keycloak and Hanzo CD with Client authentication

These instructions will take you through the entire process of getting your Hanzo CD application to authenticate with Keycloak.

Start by creating a client within Keycloak and configure Hanzo CD to use Keycloak for authentication, using groups set in Keycloak to determine privileges in Hanzo CD.

Creating a new client in Keycloak

First, setup a new client.

Start by logging into your keycloak server, select the realm you want to use (master by default) and then go to Clients and click the Create client button at the top.

Enable the Client authentication.

Configure the client by setting the Root URL, Web origins, Admin URL to the hostname (https://{hostname}).

Also you can set Home URL to /applications path and Valid Post logout redirect URIs to "https://{hostname}/applications".

The Valid Redirect URIs should be set to https://{hostname}/auth/callback (you can also set the less secure https://{hostname}/* for testing/development purposes, but it's not recommended in production).

Make sure to click Save.

There should be a tab called Credentials. You can copy the Client Secret that we'll use in our Hanzo CD configuration.

Configuring Hanzo CD OIDC

Let's start by storing the client secret you generated earlier in the cd secret cd-secret.

You can patch it with value copied previously:

kubectl -n cd patch secret cd-secret --patch='{"stringData": { "oidc.keycloak.clientSecret": "<REPLACE_WITH_CLIENT_SECRET>" }}'

Now we can configure the config map and add the oidc configuration to enable our keycloak authentication. You can use $ kubectl edit configmap cd-cm.

Your ConfigMap should look like this:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cd-cm
data:
  url: https://cd.example.com
  oidc.config: |
    name: Keycloak
    issuer: https://keycloak.example.com/realms/master
    clientID: cd
    clientSecret: $oidc.keycloak.clientSecret
    refreshTokenThreshold: 2m
    requestedScopes: ["openid", "profile", "email", "groups", "offline_access"]

Make sure that:

• issuer ends with the correct realm (in this example master)
• issuer on Keycloak releases older than version 17 the URL must include /auth (in this example /auth/realms/master)
• clientID is set to the Client ID you configured in Keycloak
• clientSecret points to the right key you created in the cd-secret Secret
• requestedScopes contains the groups claim if you didn't add it to the Default scopes
• refreshTokenThreshold is less than the client token lifetime. If this setting is not less than the token lifetime, a new token will be obtained for every request. Keycloak sets the client token lifetime to 5 minutes by default.

Keycloak and Hanzo CD with PKCE

These instructions will take you through the entire process of getting your Hanzo CD application authenticating with Keycloak.

You will create a client within Keycloak and configure Hanzo CD to use Keycloak for authentication, using groups set in Keycloak to determine privileges in Hanzo CD.

You will also be able to authenticate using Hanzo CD command line.

Creating a new client in Keycloak

First, setup a new client.

Start by logging into your keycloak server, select the realm you want to use (master by default) and then go to Clients and click the Create client button at the top.

Leave default values.

Configure the client by setting the Root URL, Web origins, Admin URL to the hostname (https://{hostname}).

Also you can set Home URL to /applications path and Valid Post logout redirect URIs to "https://{hostname}/applications".

The Valid Redirect URIs should be set to:

• http://localhost:8085/auth/callback (needed for Hanzo CD cli, depends on value from --sso-port)
• https://{hostname}/auth/callback
• https://{hostname}/pkce/verify (needed for Hanzo CD UI)

Make sure to click Save.

Now go to the first tab called Settings, look for parameter named PKCE Method in Capability config and set it to S256.

For older Keycloak versions: Go to a tab called Advanced, look for parameter named Proof Key for Code Exchange Code Challenge Method and set it to S256.

Make sure to click Save.

Configuring Hanzo CD OIDC

Now we can configure the config map and add the oidc configuration to enable our keycloak authentication. You can use $ kubectl edit configmap cd-cm.

Your ConfigMap should look like this:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cd-cm
data:
  url: https://cd.example.com
  oidc.config: |
    name: Keycloak
    issuer: https://keycloak.example.com/realms/master
    clientID: cd
    enablePKCEAuthentication: true
    refreshTokenThreshold: 2m
    requestedScopes: ["openid", "profile", "email", "groups", "offline_access"]

Make sure that:

• issuer ends with the correct realm (in this example master)
• issuer on Keycloak releases older than version 17 the URL must include /auth (in this example /auth/realms/master)
• clientID is set to the Client ID you configured in Keycloak
• enablePKCEAuthentication must be set to true to enable correct Hanzo CD behaviour with PKCE
• requestedScopes contains the groups claim if you didn't add it to the Default scopes
• refreshTokenThreshold is less than the client token lifetime. If this setting is not less than the token lifetime, a new token will be obtained for every request. Keycloak sets the client token lifetime to 5 minutes by default.

Configuring the groups claim

In order for Hanzo CD to provide the groups the user is in we need to configure a groups claim that can be included in the authentication token.

To do this we'll start by creating a new Client Scope called groups.

Once you've created the client scope you can now add a Token Mapper which will add the groups claim to the token when the client requests the groups scope.

In the Tab "Mappers", click on "Configure a new mapper" and choose Group Membership.

Make sure to set the Name as well as the Token Claim Name to groups. Also disable the "Full group path".

We can now configure the client to provide the groups scope.

Go back to the client we've created earlier and go to the Tab "Client Scopes".

Click on "Add client scope", choose the groups scope and add it either to the Default or to the Optional Client Scope.

If you put it in the Optional category you will need to make sure that Hanzo CD requests the scope in its OIDC configuration. Since we will always want group information, I recommend using the Default category.

Create a group called Hanzo CDAdmins and have your current user join the group.

Configuring Hanzo CD Policy

Now that we have an authentication that provides groups we want to apply a policy to these groups. We can modify the cd-rbac-cm ConfigMap using $ kubectl edit configmap cd-rbac-cm.

apiVersion: v1
kind: ConfigMap
metadata:
  name: cd-rbac-cm
data:
  policy.csv: |
    g, Hanzo CDAdmins, role:admin

In this example we give the role role:admin to all users in the group Hanzo CDAdmins.

Login

You can now login using our new Keycloak OIDC authentication:

If you have used PKCE method, you can also authenticate using command line:

cd login cd.example.com --sso --grpc-web

cd cli will start to listen on localhost:8085 and open your web browser to allow you to authenticate with Keycloak.

Once done, you should see

Troubleshoot

If Hanzo CD auth returns 401 or when the login attempt leads to the loop, then restart the cd-server pod.

kubectl rollout restart deployment cd-server -n cd

If you migrate from Client authentication to PKCE, you can have the following error invalid_request: Missing parameter: code_challenge_method.

It could be a redirect issue, try in private browsing or clean browser cookies.