docs: configuring Google OIDC and Google groups for RBAC (argoproj#7308)

Signed-off-by: alvarogonzalez-packlink <[email protected]>

docs/operator-manual/user-management/google.md

@@ -1,6 +1,13 @@
 # Google
 
-* [G Suite SAML App Auth using Dex](#g-suite-saml-app-auth-using-dex)
+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.
+
+* [OpenID Connect using Dex](#openid-connect-using-dex) 
+ 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. 
+* [SAML App Auth using Dex](#saml-app-auth-using-dex) 
+ Dex [recommends avoiding this method](https://dexidp.io/docs/connectors/saml/#warning). Also, you won't get Google Groups membership information through this method.
+* [OpenID Connect plus Google Groups using Dex](#openid-connect-plus-google-groups-using-dex) 
+ This is the recommended method if you need to user Google Groups membership in your RBAC configuration.
 
 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.
 
@@ -14,10 +21,66 @@ data:
  policy.default: role:readonly
 ```
 
-## G Suite SAML App Auth using Dex
+## OpenID Connect using Dex
+
+### Configure your OAuth consent screen
+
+If you've never configured this, you'll be redirected straight to this if you try to create an OAuth Client ID
+
+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` 
+2. Go and [edit your OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent/edit) Verify you're in the correct project!
+3. Configure a name for your login app and a user support email address
+4. The app logo and filling the information links is not mandatory, but it's a nice touch for the login page
+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)
+6. Save to continue to the "Scopes" section
+7. Click on "Add or remove scopes" and add the `.../auth/userinfo.profile` and the `openid` scopes
+8. Save, review the summary of your changes and finish
+
+### Configure a new OAuth Client ID
+
+1. Go to your [Google API Credentials](https://console.cloud.google.com/apis/credentials) console, and make sure you're in the correct project.
+2. Click on "+Create Credentials"/"OAuth Client ID"
+3. Select "Web Application" in the Application Type drop down menu, and enter an identifying name for your app (e.g. `Argo CD`)
+4. Fill "Authorized JavaScript origins" with your Argo CD URL, e.g. `https://argocd.example.com`
+5. Fill "Authorized redirect URIs" with your Argo CD URL plus `/api/dex/callback`, e.g. `https://argocd.example.com/api/dex/callback`
+
+ ![](../../assets/google-admin-oidc-uris.png)
+
+6. Click "Create" and save your "Client ID" and your "Client Secret" for later
+
+### Configure Argo to use OpenID Connect
+
+Edit `argo-cm` and add the following dex.config to the data section, replacing `clientID` and `clientSecret` with the values you saved before:
+
+```yaml
+data:
+ url: https://argocd.example.com
+ dex.config: |
+ connectors:
+ - config:
+ issuer: https://accounts.google.com
+ clientID: XXXXXXXXXXXXX.apps.googleusercontent.com
+ clientSecret: XXXXXXXXXXXXX
+ type: oidc
+ id: google
+ name: Google
+```
+
+### References
+
+- [Dex oidc connector docs](https://dexidp.io/docs/connectors/oidc/)
+
+## SAML App Auth using Dex
 
 ### Configure a new SAML App
 
+---
+!!! warning "Deprecation Warning"
+
+ 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.
+
+---
+
 1. In the [Google admin console](https://admin.google.com), open the left-side menu and select `Apps` > `SAML Apps`
 
  ![Google Admin Apps Menu](../../assets/google-admin-saml-apps-menu.png "Google Admin menu with the Apps / SAML Apps path selected")
@@ -76,3 +139,90 @@ data:
 
 - [Dex SAML connector docs](https://dexidp.io/docs/connectors/saml/)
 - [Google's SAML error messages](https://support.google.com/a/answer/6301076?hl=en)
+
+## OpenID Connect plus Google Groups using Dex
+
+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 `[email protected]` group.
+
+This connector uses two different credentials:
+- An oidc client ID and secret 
+ Same as when you're configuring an [OpenID connection](#openid-connect-using-dex), this authenticates your users
+- A Google service account 
+ This is used to connect to the Google Directory API and pull information about your user's group membership
+
+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.
+
+### Configure OpenID Connect
+
+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.
+
+### Set up Directory API access 
+
+1. Follow [Google instructions to create a service account with Domain-Wide Delegation](https://developers.google.com/admin-sdk/directory/v1/guides/delegation) 
+ - When assigning API scopes to the service account assign **only** the `https://www.googleapis.com/auth/admin.directory.group.readonly` scope and nothing else. If you assign any other scopes, you won't be able to fetch information from the API
+ - Create the credentials in JSON format and store them in a safe place, we'll need them later
+2. Enable the [Admin SDK](https://console.developers.google.com/apis/library/admin.googleapis.com/)
+
+### Configure Dex
+
+1. Create a secret with the contents of the previous json file encoded in base64, like this
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+ name: argocd-google-groups-json
+ namespace: argocd
+data:
+ googleAuth.json: JSON_FILE_BASE64_ENCODED
+```
+
+2. Edit your `argocd-dex-server` deployment to mount that secret as a file 
+ - Add a volume mount in `/spec/template/spec/containers/0/volumeMounts/` like this: 
+ ```yaml
+ volumeMounts:
+ - mountPath: /shared
+ name: static-files
+ - mountPath: /tmp
+ name: dexconfig
+ - mountPath: /tmp/oidc
+ name: google-json
+ readOnly: true
+ ```
+ Be aware of editing the running container and not the init container!
+ - Add a volume in `/spec/template/spec/volumes/` like this: 
+ ```yaml
+ volumes:
+ - emptyDir: {}
+ name: static-files
+ - emptyDir: {}
+ name: dexconfig
+ - name: google-json
+ secret:
+ defaultMode: 420
+ secretName: argocd-google-groups-json
+ ```
+
+3. Edit `argo-cm` and add the following 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: 
+ ```yaml
+ dex.config: |
+ connectors:
+ - config:
+ redirectURI: https://argocd.example.com/api/dex/callback
+ clientID: XXXXXXXXXXXXX.apps.googleusercontent.com
+ clientSecret: XXXXXXXXXXXXX
+ serviceAccountFilePath: /tmp/oidc/googleAuth.json
+ adminEmail: [email protected]
+ type: google
+ id: google
+ name: Google
+ ```
+
+4. Restart your `argocd-dex-server` deployment to be sure it's using the latest configuration
+5. Login to Argo CD and go to the "User info" section, were you should see the groups you're member 
+ ![User info](../../assets/google-groups-membership.png)
+6. Now you can use groups email addresses to give RBAC permissions
+
+### References
+
+- [Dex Google connector docs](https://dexidp.io/docs/connectors/google/)