github.com/argoproj/argo-cd/v3@v3.2.1/docs/operator-manual/user-management/keycloak.md (about) 1 # Keycloak 2 Keycloak and ArgoCD integration can be configured in two ways with Client authentication and with PKCE. 3 4 If you need to authenticate with __argo-cd command line__, you must choose PKCE way. 5 6 * [Keycloak and ArgoCD with Client authentication](#keycloak-and-argocd-with-client-authentication) 7 * [Keycloak and ArgoCD with PKCE](#keycloak-and-argocd-with-pkce) 8 9 ## Keycloak and ArgoCD with Client authentication 10 11 These instructions will take you through the entire process of getting your ArgoCD application authenticating with Keycloak. 12 13 You will create a client within Keycloak and configure ArgoCD to use Keycloak for authentication, using groups set in Keycloak 14 to determine privileges in Argo. 15 16 ### Creating a new client in Keycloak 17 18 First we need to setup a new client. 19 20 Start by logging into your keycloak server, select the realm you want to use (`master` by default) 21 and then go to __Clients__ and click the __Create client__ button at the top. 22 23  24 25 Enable the __Client authentication__. 26 27  28 29 Configure the client by setting the __Root URL__, __Web origins__, __Admin URL__ to the hostname (https://{hostname}). 30 31 Also you can set __Home URL__ to _/applications_ path and __Valid Post logout redirect URIs__ to "https://{hostname}/applications". 32 33 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, 34 but it's not recommended in production). 35 36  37 38 Make sure to click __Save__. 39 40 There should be a tab called __Credentials__. You can copy the Client Secret that we'll use in our ArgoCD configuration. 41 42  43 44 ### Configuring ArgoCD OIDC 45 46 Let's start by storing the client secret you generated earlier in the argocd secret _argocd-secret_. 47 48 You can patch it with value copied previously: 49 ```bash 50 kubectl -n argo-cd patch secret argocd-secret --patch='{"stringData": { "oidc.keycloak.clientSecret": "<REPLACE_WITH_CLIENT_SECRET>" }}' 51 ``` 52 53 Now we can configure the config map and add the oidc configuration to enable our keycloak authentication. 54 You can use `$ kubectl edit configmap argocd-cm`. 55 56 Your ConfigMap should look like this: 57 58 ```yaml 59 apiVersion: v1 60 kind: ConfigMap 61 metadata: 62 name: argocd-cm 63 data: 64 url: https://argocd.example.com 65 oidc.config: | 66 name: Keycloak 67 issuer: https://keycloak.example.com/realms/master 68 clientID: argocd 69 clientSecret: $oidc.keycloak.clientSecret 70 requestedScopes: ["openid", "profile", "email", "groups"] 71 ``` 72 73 Make sure that: 74 75 - __issuer__ ends with the correct realm (in this example _master_) 76 - __issuer__ on Keycloak releases older than version 17 the URL must include /auth (in this example /auth/realms/master) 77 - __clientID__ is set to the Client ID you configured in Keycloak 78 - __clientSecret__ points to the right key you created in the _argocd-secret_ Secret 79 - __requestedScopes__ contains the _groups_ claim if you didn't add it to the Default scopes 80 81 ## Keycloak and ArgoCD with PKCE 82 83 These instructions will take you through the entire process of getting your ArgoCD application authenticating with Keycloak. 84 85 You will create a client within Keycloak and configure ArgoCD to use Keycloak for authentication, using groups set in Keycloak 86 to determine privileges in Argo. 87 88 You will also be able to authenticate using argo-cd command line. 89 90 ### Creating a new client in Keycloak 91 92 First we need to setup a new client. 93 94 Start by logging into your keycloak server, select the realm you want to use (`master` by default) 95 and then go to __Clients__ and click the __Create client__ button at the top. 96 97  98 99 Leave default values. 100 101  102 103 Configure the client by setting the __Root URL__, __Web origins__, __Admin URL__ to the hostname (https://{hostname}). 104 105 Also you can set __Home URL__ to _/applications_ path and __Valid Post logout redirect URIs__ to "https://{hostname}/applications". 106 107 The Valid Redirect URIs should be set to: 108 - http://localhost:8085/auth/callback (needed for argo-cd cli, depends on value from [--sso-port](../../user-guide/commands/argocd_login.md)) 109 - https://{hostname}/auth/callback 110 111  112 113 Make sure to click __Save__. 114 115 Now go to a tab called __Advanced__, look for parameter named __Proof Key for Code Exchange Code Challenge Method__ and set it to __S256__ 116 117  118 Make sure to click __Save__. 119 120 ### Configuring ArgoCD OIDC 121 Now we can configure the config map and add the oidc configuration to enable our keycloak authentication. 122 You can use `$ kubectl edit configmap argocd-cm`. 123 124 Your ConfigMap should look like this: 125 126 ```yaml 127 apiVersion: v1 128 kind: ConfigMap 129 metadata: 130 name: argocd-cm 131 data: 132 url: https://argocd.example.com 133 oidc.config: | 134 name: Keycloak 135 issuer: https://keycloak.example.com/realms/master 136 clientID: argocd 137 enablePKCEAuthentication: true 138 requestedScopes: ["openid", "profile", "email", "groups"] 139 ``` 140 141 Make sure that: 142 143 - __issuer__ ends with the correct realm (in this example _master_) 144 - __issuer__ on Keycloak releases older than version 17 the URL must include /auth (in this example /auth/realms/master) 145 - __clientID__ is set to the Client ID you configured in Keycloak 146 - __enablePKCEAuthentication__ must be set to true to enable correct ArgoCD behaviour with PKCE 147 - __requestedScopes__ contains the _groups_ claim if you didn't add it to the Default scopes 148 149 ## Configuring the groups claim 150 151 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. 152 153 To do this we'll start by creating a new __Client Scope__ called _groups_. 154 155  156 157 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 158 the groups scope. 159 160 In the Tab "Mappers", click on "Configure a new mapper" and choose __Group Membership__. 161 162 Make sure to set the __Name__ as well as the __Token Claim Name__ to _groups_. Also disable the "Full group path". 163 164  165 166 We can now configure the client to provide the _groups_ scope. 167 168 Go back to the client we've created earlier and go to the Tab "Client Scopes". 169 170 Click on "Add client scope", choose the _groups_ scope and add it either to the __Default__ or to the __Optional__ Client Scope. 171 172 If you put it in the Optional 173 category you will need to make sure that ArgoCD requests the scope in its OIDC configuration. 174 Since we will always want group information, I recommend 175 using the Default category. 176 177  178 179 Create a group called _ArgoCDAdmins_ and have your current user join the group. 180 181  182 183 ## Configuring ArgoCD Policy 184 185 Now that we have an authentication that provides groups we want to apply a policy to these groups. 186 We can modify the _argocd-rbac-cm_ ConfigMap using `$ kubectl edit configmap argocd-rbac-cm`. 187 188 ```yaml 189 apiVersion: v1 190 kind: ConfigMap 191 metadata: 192 name: argocd-rbac-cm 193 data: 194 policy.csv: | 195 g, ArgoCDAdmins, role:admin 196 ``` 197 198 In this example we give the role _role:admin_ to all users in the group _ArgoCDAdmins_. 199 200 ## Login 201 202 You can now login using our new Keycloak OIDC authentication: 203 204  205 206 If you have used PKCE method, you can also authenticate using command line: 207 ```bash 208 argocd login argocd.example.com --sso --grpc-web 209 ``` 210 211 argocd cli will start to listen on localhost:8085 and open your web browser to allow you to authenticate with Keycloak. 212 213 Once done, you should see 214 215  216 217 ## Troubleshoot 218 If ArgoCD auth returns 401 or when the login attempt leads to the loop, then restart the argocd-server pod. 219 ``` 220 kubectl rollout restart deployment argocd-server -n argocd 221 ``` 222 223 If you migrate from Client authentication to PKCE, you can have the following error `invalid_request: Missing parameter: code_challenge_method`. 224 225 It could be a redirect issue, try in private browsing or clean browser cookies.