Skip to content

Latest commit

 

History

History
226 lines (149 loc) · 8.83 KB

keycloak.md

File metadata and controls

226 lines (149 loc) · 8.83 KB

Keycloak

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

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

Keycloak and ArgoCD with Client authentication

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

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

Creating a new client in Keycloak

First we need to 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.

Keycloak add client

Enable the Client authentication.

Keycloak add client Step 2

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).

Keycloak configure client

Make sure to click Save.

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

Keycloak client secret

Configuring ArgoCD OIDC

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

You can patch it with value copied previously:

kubectl -n argo-cd patch secret argocd-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 argocd-cm.

Your ConfigMap should look like this:

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

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 argocd-secret Secret
  • requestedScopes contains the groups claim if you didn't add it to the Default scopes

Keycloak and ArgoCD with PKCE

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

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

You will also be able to authenticate using argo-cd command line.

Creating a new client in Keycloak

First we need to 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.

Keycloak add client

Leave default values.

Keycloak add client Step 2

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:

Keycloak configure client

Make sure to click Save.

Now go to a tab called Advanced, look for parameter named Proof Key for Code Exchange Code Challenge Method and set it to S256

Keycloak configure client Step 2 Make sure to click Save.

Configuring ArgoCD OIDC

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

Your ConfigMap should look like this:

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

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 ArgoCD behaviour with PKCE
  • requestedScopes contains the groups claim if you didn't add it to the Default scopes

Configuring the groups claim

In order for ArgoCD 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.

Keycloak add scope

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".

Keycloak groups mapper

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 ArgoCD requests the scope in its OIDC configuration. Since we will always want group information, I recommend using the Default category.

Keycloak client scope

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

Keycloak user group

Configuring ArgoCD Policy

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
data:
  policy.csv: |
    g, ArgoCDAdmins, role:admin

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

Login

You can now login using our new Keycloak OIDC authentication:

Keycloak ArgoCD login

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

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

argocd 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

Authentication successful!

Troubleshoot

If ArgoCD auth returns 401 or when the login attempt leads to the loop, then restart the argocd-server pod.

kubectl rollout restart deployment argocd-server -n argocd

If you migrate from Client authentification 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.