Adds documentation for OIDC provider specific extension for G Suite (#9454)
* docs: adds documentation for JWT/OIDC google provider specific handling * use may instead of will for identity group alias association Co-authored-by: Jim Kalafut <jkalafut@hashicorp.com> * adds missed parentheses Co-authored-by: Jim Kalafut <jkalafut@hashicorp.com> * adds missed parentheses Co-authored-by: Jim Kalafut <jkalafut@hashicorp.com> * reword sentence referring to key file for Google service account Co-authored-by: Theron Voran <tvoran@users.noreply.github.com> * add styles to emphasize security step Co-authored-by: Jim Kalafut <jkalafut@hashicorp.com> Co-authored-by: Theron Voran <tvoran@users.noreply.github.com>
This commit is contained in:
Austin Gebauer
GitHub
parent
068e080c27
commit
56bc00bed8
|
|
@ -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": "admin@gsuitedomain.com",
|
||||
"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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue