github.com/argoproj/argo-cd/v3@v3.2.1/docs/operator-manual/user-management/google.md (about) 1 # Google 2 3 There are three different ways to integrate Argo CD login with your Google Workspace users. Generally the OpenID Connect (_oidc_) method would be the recommended way of doing this integration (and easier, as well...), but depending on your needs, you may choose a different option. 4 5 - [OpenID Connect using Dex](#openid-connect-using-dex) 6 This is the recommended login method if you don't need information about the groups the user's belongs to. Google doesn't expose the `groups` claim via _oidc_, so you won't be able to use Google Groups membership information for RBAC. 7 - [SAML App Auth using Dex](#saml-app-auth-using-dex) 8 Dex [recommends avoiding this method](https://dexidp.io/docs/connectors/saml/#warning). Also, you won't get Google Groups membership information through this method. 9 - [OpenID Connect plus Google Groups using Dex](#openid-connect-plus-google-groups-using-dex) 10 This is the recommended method if you need to use Google Groups membership in your RBAC configuration. 11 12 Once you've set up one of the above integrations, be sure to edit `argo-rbac-cm` to configure permissions (as in the example below). See [RBAC Configurations](../rbac.md) for more detailed scenarios. 13 14 ```yaml 15 apiVersion: v1 16 kind: ConfigMap 17 metadata: 18 name: argocd-rbac-cm 19 namespace: argocd 20 data: 21 policy.default: role:readonly 22 ``` 23 24 ## OpenID Connect using Dex 25 26 ### Configure your OAuth consent screen 27 28 If you've never configured this, you'll be redirected straight to this if you try to create an OAuth Client ID 29 30 1. Go to your [OAuth Consent](https://console.cloud.google.com/apis/credentials/consent) configuration. If you still haven't created one, select `Internal` or `External` and click `Create` 31 2. Go and [edit your OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent/edit) Verify you're in the correct project! 32 3. Configure a name for your login app and a user support email address 33 4. The app logo and filling the information links is not mandatory, but it's a nice touch for the login page 34 5. In "Authorized domains" add the domains who are allowed to log in to ArgoCD (e.g. if you add `example.com`, all Google Workspace users with an `@example.com` address will be able to log in) 35 6. Save to continue to the "Scopes" section 36 7. Click on "Add or remove scopes" and add the `.../auth/userinfo.profile` and the `openid` scopes 37 8. Save, review the summary of your changes and finish 38 39 ### Configure a new OAuth Client ID 40 41 1. Go to your [Google API Credentials](https://console.cloud.google.com/apis/credentials) console, and make sure you're in the correct project. 42 2. Click on "+Create Credentials"/"OAuth Client ID" 43 3. Select "Web Application" in the Application Type drop down menu, and enter an identifying name for your app (e.g. `Argo CD`) 44 4. Fill "Authorized JavaScript origins" with your Argo CD URL, e.g. `https://argocd.example.com` 45 5. Fill "Authorized redirect URIs" with your Argo CD URL plus `/api/dex/callback`, e.g. `https://argocd.example.com/api/dex/callback` 46 47  48 49 6. Click "Create" and save your "Client ID" and your "Client Secret" for later 50 51 ### Configure Argo to use OpenID Connect 52 53 Edit `argocd-cm` and add the following `dex.config` to the data section, replacing `clientID` and `clientSecret` with the values you saved before: 54 55 ```yaml 56 data: 57 url: https://argocd.example.com 58 dex.config: | 59 connectors: 60 - config: 61 issuer: https://accounts.google.com 62 clientID: XXXXXXXXXXXXX.apps.googleusercontent.com 63 clientSecret: XXXXXXXXXXXXX 64 type: oidc 65 id: google 66 name: Google 67 ``` 68 69 ### References 70 71 - [Dex oidc connector docs](https://dexidp.io/docs/connectors/oidc/) 72 73 ## SAML App Auth using Dex 74 75 ### Configure a new SAML App 76 77 --- 78 79 !!! warning "Deprecation Warning" 80 81 Note that, according to [Dex documentation](https://dexidp.io/docs/connectors/saml/#warning), SAML is considered unsafe and they are planning to deprecate that module. 82 83 --- 84 85 1. In the [Google admin console](https://admin.google.com), open the left-side menu and select `Apps` > `SAML Apps` 86 87  88 89 2. Under `Add App` select `Add custom SAML app` 90 91  92 93 3. Enter a `Name` for the application (e.g. `Argo CD`), then choose `Continue` 94 95  96 97 4. Download the metadata or copy the `SSO URL`, `Certificate`, and optionally `Entity ID` from the identity provider details for use in the next section. Choose `continue`. 98 99 - Base64 encode the contents of the certificate file, for example: 100 - `$ cat ArgoCD.cer | base64` 101 - _Keep a copy of the encoded output to be used in the next section._ 102 - _Ensure that the certificate is in PEM format before base64 encoding_ 103 104  105 106 5. For both the `ACS URL` and `Entity ID`, use your Argo Dex Callback URL, for example: `https://argocd.example.com/api/dex/callback` 107 108  109 110 6. Add SAML Attribute Mapping, Map `Primary email` to `name` and `Primary Email` to `email`. and click `ADD MAPPING` button. 111 112  113 114 7. Finish creating the application. 115 116 ### Configure Argo to use the new Google SAML App 117 118 Edit `argocd-cm` and add the following `dex.config` to the data section, replacing the `caData`, `argocd.example.com`, `sso-url`, and optionally `google-entity-id` with your values from the Google SAML App: 119 120 ```yaml 121 data: 122 url: https://argocd.example.com 123 dex.config: | 124 connectors: 125 - type: saml 126 id: saml 127 name: saml 128 config: 129 ssoURL: https://sso-url (e.g. https://accounts.google.com/o/saml2/idp?idpid=Abcde0) 130 entityIssuer: https://argocd.example.com/api/dex/callback 131 caData: | 132 BASE64-ENCODED-CERTIFICATE-DATA 133 redirectURI: https://argocd.example.com/api/dex/callback 134 usernameAttr: name 135 emailAttr: email 136 # optional 137 ssoIssuer: https://google-entity-id (e.g. https://accounts.google.com/o/saml2?idpid=Abcde0) 138 ``` 139 140 ### References 141 142 - [Dex SAML connector docs](https://dexidp.io/docs/connectors/saml/) 143 - [Google's SAML error messages](https://support.google.com/a/answer/6301076?hl=en) 144 145 ## OpenID Connect plus Google Groups using Dex 146 147 We're going to use Dex's `google` connector to get additional Google Groups information from your users, allowing you to use group membership on your RBAC, i.e., giving `admin` role to the whole `sysadmins@yourcompany.com` group. 148 149 This connector uses two different credentials: 150 151 - An oidc client ID and secret 152 Same as when you're configuring an [OpenID connection](#openid-connect-using-dex), this authenticates your users 153 - A Google service account 154 This is used to connect to the Google Directory API and pull information about your user's group membership 155 156 Also, you'll need the email address for an admin user on this domain. Dex will impersonate that user identity to fetch user information from the API. 157 158 ### Configure OpenID Connect 159 160 Go through the same steps as in [OpenID Connect using Dex](#openid-connect-using-dex), except for configuring `argocd-cm`. We'll do that later. 161 162 ### Set up Directory API access 163 164 1. Follow [Google instructions to create a service account with Domain-Wide Delegation](https://developers.google.com/admin-sdk/directory/v1/guides/delegation) 165 - When assigning API scopes to the service account, the scope must **strictly include** `https://www.googleapis.com/auth/admin.directory.group.readonly`. If you assign only the [broader scope] (https://www.googleapis.com/auth/admin.directory.group), you will not be able to retrieve data from the API 166 - Create the credentials in JSON format and store them in a safe place, we'll need them later 167 2. Enable the [Admin SDK](https://console.developers.google.com/apis/library/admin.googleapis.com/) 168 169 ### Configure Dex 170 171 1. **Configure authentication credentials** 172 173 **Option 1: Using Service Account File (traditional method)** 174 175 Create a secret with the contents of the previous json file encoded in base64, like this: 176 177 ```yaml 178 apiVersion: v1 179 kind: Secret 180 metadata: 181 name: argocd-google-groups-json 182 namespace: argocd 183 data: 184 googleAuth.json: JSON_FILE_BASE64_ENCODED 185 ``` 186 187 Then edit your `argocd-dex-server` deployment to mount that secret as a file: 188 189 - Add a volume mount in `/spec/template/spec/containers/0/volumeMounts/` like this. Be aware of editing the running container and not the init container! 190 191 ```yaml 192 volumeMounts: 193 - mountPath: /shared 194 name: static-files 195 - mountPath: /tmp 196 name: dexconfig 197 - mountPath: /tmp/oidc 198 name: google-json 199 readOnly: true 200 ``` 201 202 - Add a volume in `/spec/template/spec/volumes/` like this: 203 204 ```yaml 205 volumes: 206 - emptyDir: {} 207 name: static-files 208 - emptyDir: {} 209 name: dexconfig 210 - name: google-json 211 secret: 212 defaultMode: 420 213 secretName: argocd-google-groups-json 214 ``` 215 216 **Option 2: Using Workload Identity (Dex > v2.34.0)** 217 218 Configure Workload Identity for your `argocd-dex-server` service account. No secret file is needed when using Workload Identity. 219 220 2. Edit `argocd-cm` and add the following `url` and `dex.config` to the data section, replacing `clientID` and `clientSecret` with the values you saved before, `adminEmail` with the address for the admin user you're going to impersonate, and editing `redirectURI` with your Argo CD domain (note that the `type` is now `google` instead of `oidc`): 221 222 **Option 1: Using Service Account File** 223 224 ```yaml 225 data: 226 url: https://argocd.example.com 227 dex.config: | 228 connectors: 229 - config: 230 redirectURI: https://argocd.example.com/api/dex/callback 231 clientID: XXXXXXXXXXXXX.apps.googleusercontent.com 232 clientSecret: XXXXXXXXXXXXX 233 serviceAccountFilePath: /tmp/oidc/googleAuth.json 234 adminEmail: admin-email@example.com 235 # Optional: Enable transitive group membership (Dex > v2.31.0) 236 # fetchTransitiveGroupMembership: True 237 type: google 238 id: google 239 name: Google 240 ``` 241 242 **Option 2: Using Workload Identity (Dex > v2.34.0)** 243 244 ```yaml 245 data: 246 url: https://argocd.example.com 247 dex.config: | 248 connectors: 249 - config: 250 redirectURI: https://argocd.example.com/api/dex/callback 251 clientID: XXXXXXXXXXXXX.apps.googleusercontent.com 252 clientSecret: XXXXXXXXXXXXX 253 adminEmail: admin-email@example.com 254 fetchTransitiveGroupMembership: True 255 type: google 256 id: google 257 name: Google 258 ``` 259 260 3. Restart your `argocd-dex-server` deployment to be sure it's using the latest configuration 261 4. Login to Argo CD and go to the "User info" section, were you should see the groups you're member 262  263 5. Now you can use groups email addresses to give RBAC permissions 264 265 ### References 266 267 - [Dex Google connector docs](https://dexidp.io/docs/connectors/google/)