Adds documentation for OIDC provider specific extension for G Suite (#…

…9454) (#9760)

website/pages/docs/auth/jwt_oidc_providers.mdx

@@ -128,6 +128,79 @@ Main reference: [Using OAuth 2.0 to Access Google APIs](https://developers.googl
 1. Configure Authorized Redirect URIs.
 1. Save client ID and secret.
 
+### Google-specific handling configuration
+
+Provider specific configuration is available when using Google as an identity provider from the
+Vault JWT/OIDC auth method. The configuration allows Vault to obtain G Suite group membership and
+user information during the JWT/OIDC authentication flow. The group membership obtained from G Suite
+may be used for Identity group alias association. The user information obtained from G Suite can be
+used to copy claims data into resulting auth token and alias metadata via [claim_mappings](/api/auth/jwt#claim_mappings).
+
+#### Setup
+
+To set up the Google-specific handling, you'll need:
+- A G Suite account with the [super admin role](https://support.google.com/a/answer/2405986?hl=en)
+for granting domain-wide delegation API client access.
+- The ability to create a service account in [Google Cloud Platform](https://console.developers.google.com/iam-admin/serviceaccounts).
+
+The Google-specific handling that's used to fetch G Suite groups and user information in Vault uses
+[G Suite Domain-Wide Delegation of Authority](https://developers.google.com/admin-sdk/directory/v1/guides/delegation)
+for authentication and authorization. You need to follow **all steps** in the [guide](https://developers.google.com/admin-sdk/directory/v1/guides/delegation)
+to obtain the key file for a Google service account capable of making requests to the G Suite
+[User Accounts](https://developers.google.com/admin-sdk/directory/v1/guides/manage-users) and
+[Groups](https://developers.google.com/admin-sdk/directory/v1/guides/manage-groups) APIs.
+
+In **step 5** within the section titled
+[Delegate domain-wide authority to your service account](https://developers.google.com/admin-sdk/directory/v1/guides/delegation#delegate_domain-wide_authority_to_your_service_account),
+the only OAuth scopes that should be granted are:
+- `https://www.googleapis.com/auth/admin.directory.group.readonly`
+- `https://www.googleapis.com/auth/admin.directory.user.readonly`
+
+~> This is an **important security step** in order to give the service account the least set of privileges
+that enable the feature.
+
+#### Configuration
+
+- `provider` `(string: <required>)` - Name of the provider. Must be set to "gsuite".
+- `gsuite_service_account` `(string: <required>)` - Path to the Google service account key file obtained from setup.
+- `gsuite_admin_impersonate` `(string: <required>)` - Email address of a G Suite admin to impersonate.
+- `fetch_groups` `(bool: false)` - If set to true, groups will be fetched from G Suite.
+- `fetch_user_info` `(bool: false)` - If set to true, user info will be fetched from G Suite using the configured [user_custom_schemas](#user_custom_schemas).
+- `groups_recurse_max_depth` `(int: <optional>)` - Group membership recursion max depth. Defaults to 0, which means don't recurse.
+- `user_custom_schemas` `(string: <optional>)` - Comma-separated list of G Suite [custom schemas](https://developers.google.com/admin-sdk/directory/v1/guides/manage-schemas).
+Values set for G Suite users using custom schema fields will be fetched and made available as claims that can be used with [claim_mappings](/api/auth/jwt#claim_mappings). Required if [fetch_user_info](#fetch_user_info) is set to true.
+
+Example configuration:
+```
+vault write auth/oidc/config -<<EOF
+{
+    "oidc_discovery_url": "https://accounts.google.com",
+    "oidc_client_id": "your_client_id",
+    "oidc_client_secret": "your_client_secret",
+    "default_role": "your_default_role",
+    "provider_config": {
+        "provider": "gsuite",
+        "gsuite_service_account": "/path/to/service-account.json",
+        "gsuite_admin_impersonate": "[email protected]",
+        "fetch_groups": true,
+        "fetch_user_info": true,
+        "groups_recurse_max_depth": 5,
+        "user_custom_schemas": "Education,Preferences"
+    }
+}
+EOF
+```
+
+Example role:
+```
+vault write auth/oidc/role/your_default_role \
+    allowed_redirect_uris="http://localhost:8200/ui/vault/auth/oidc/oidc/callback,http://localhost:8250/oidc/callback" \
+    user_claim="sub" \
+    groups_claim="groups" \
+    claim_mappings="/Education/graduation_date"="graduation_date" \
+    claim_mappings="/Preferences/shirt_size"="shirt_size"
+```
+
 ## Keycloak
 
 1. Select/create a Realm and Client. Select a Client and visit Settings.