luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/website/content/docs/auth/jwt_oidc_providers.mdx
Rosemary Wang a48db957ca
docs: Update Azure AD OIDC documentation (#10853) 
Addresses #8191 with clearer external groups configuration.
2021-02-12 17:28:00 -08:00

264 lines
12 KiB
Plaintext
Raw Blame History

---
layout: docs
page_title: OIDC Provider Setup - Auth Methods
description: OIDC provider configuration quick starts
---
# OIDC Provider Configuration
This page collects high-level setup steps on how to configure an OIDC
application for various providers. For more general usage and operation
information, see the [Vault JWT/OIDC method documentation](/docs/auth/jwt).
OIDC providers are often highly configurable and you should become familiar with
their recommended settings and best practices. The instructions below are
largely community-driven and intended to help you get started. Corrections
and additions may be submitted via the [Vault Github repository](https://github.com/hashicorp/vault).
## Azure Active Directory (AAD)
Reference: [Azure Active Directory v2.0 and the OpenID Connect protocol](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc)
1. Choose your Azure tenant.
1. Go to **Azure Active Directory** and
[register an application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
for Vault.
1. Add Redirect URIs with the "Web" type. You may include two redirect URIs,
one for CLI access another one for Vault UI access.
- `http://localhost:8250/oidc/callback`
- `https://hostname:port_number/ui/vault/auth/oidc/oidc/callback`
1. Record the "Application (client) ID" as you will need it as the `oidc_client_id`.
1. Under **API Permissions** grant the following permission:
- Microsoft Graph API permission [GroupMember.Read.All](https://docs.microsoft.com/en-us/graph/permissions-reference#application-permissions-23)
1. Under **Endpoints**, copy the OpenID Connect metadata document URL, omitting the `/well-known...` portion.
- The endpoint URL (`oidc_discovery_url`) will look like: https://login.microsoftonline.com/tenant-guid-dead-beef-aaaa-aaaa/v2.0
1. Under **Certificates & secrets**,
[add a client secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-a-client-secret)
Record the secret's value as you will need it as the `oidc_client_secret` for Vault.
### Connect AD group with Vault external group
Reference: [Azure Active Directory with OIDC Auth Method and External Groups](https://learn.hashicorp.com/tutorials/vault/oidc-auth-azure)
To connect the AD group with a [Vault external groups](/docs/secrets/identity#external-vs-internal-groups),
you will need
[Azure AD v2.0 endpoints](https://docs.microsoft.com/en-gb/azure/active-directory/develop/azure-ad-endpoint-comparison).
You should set up a [Vault policy](https://learn.hashicorp.com/tutorials/vault/policies) for the Azure AD group to use.
1. Go to **Azure Active Directory** and choose your Vault application.
1. Go to **Token configuration** and **Add groups claim**. Select "All" or "SecurityGroup" based on
[which groups for a user](https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims)
you want returned in the claim.
1. In Vault, enable the OIDC auth method.
1. Configure the OIDC auth method with the `oidc_client_id` (application ID), `oidc_client_secret`
(client secret), and `oidc_discovery_url` (endpoint URL) you recorded from Azure.
```shell
vault write auth/oidc/config \
oidc_client_id="your_client_id" \
oidc_client_secret="your_client_secret" \
default_role="your_default_role" \
oidc_discovery_url="https://login.microsoftonline.com/tenant_id/v2.0"
```
1. Configure the [OIDC Role](/api/auth/jwt#create-role) with the following:
- `user_claim` should be `"email"`.
- `allowed_redirect_uris` should be the two redirect URIs for Vault CLI and UI access.
- `groups_claim` should be set to `"groups"`.
- `oidc_scopes` should be set to `"https://graph.microsoft.com/.default"`.
```shell
vault write auth/oidc/role/your_default_role \
user_claim="email" \
allowed_redirect_uris="http://localhost:8250/oidc/callback,https://online_version_hostname:port_number/ui/vault/auth/oidc/oidc/callback" \
groups_claim="groups" \
oidc_scopes="https://graph.microsoft.com/.default" \
policies=default
```
1. In Vault, create the [external group](/api/secret/identity/group).
Record the group ID as you will need it for the group alias.
1. From Vault, retrieve the [OIDC accessor ID](/api/system/auth#list-auth-methods)
from the OIDC auth method as you will need it for the group alias's `mount_accessor`.
1. Go to the Azure AD Group you want to attach to Vault's external group. Record the `objectId`
as you will need it as the group alias name in Vault.
1. In Vault, create a [group alias](/api/secret/identity/group-alias)
for the external group and set the `objectId` as the group alias name.
```shell
vault write identity/group-alias \
name="your_ad_group_object_id" \
mount_accessor="vault_oidc_accessor_id" \
canonical_id="vault_external_group_id"
```
### Azure-specific handling configuration
If a user is a member of more than 200 groups (directly or indirectly), extra configuration
is required so that Vault can fetch the groups properly.
- In Azure, under the applications **API Permissions**, grant the following permissions:
- Microsoft Graph API permission [Directory.Read.All](https://docs.microsoft.com/en-us/graph/permissions-reference#application-permissions-19)
- In Vault, set `"provider_config"` to Azure.
```shell
vault write auth/oidc/config -<<"EOH"
{
"oidc_client_id": "your_client_id",
"oidc_client_secret": "your_client_secret",
"default_role": "your_default_role",
"oidc_discovery_url": "https://login.microsoftonline.com/tenant_id/v2.0",
"provider_config": {
"provider": "azure"
}
}
EOH
```
- In Vault, add `"profile"` to `oidc_scopes` so the user's id comes back on the JWT.
```shell
vault write auth/oidc/role/your_default_role \
user_claim="email" \
allowed_redirect_uris="http://localhost:8250/oidc/callback,https://online_version_hostname:port_number/ui/vault/auth/oidc/oidc/callback" \
groups_claim="groups" \
oidc_scopes="profile" \
policies="default"
```
## Auth0
1. Select Create Application (Regular Web App).
1. Configure Allowed Callback URLs.
1. Copy client ID and secret.
1. If you see Vault errors involving signature, check the application's Advanced > OAuth settings
and verify that signing algorithm is "RS256".
## Gitlab
1. Visit Settings > Applications.
1. Fill out Name and Redirect URIs.
1. Making sure to select the "openid" scope.
1. Copy client ID and secret.
## Google
Main reference: [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/OAuth2)
1. Visit the [Google API Console](https://console.developers.google.com).
1. Create or a select a project.
1. Create a new credential via Credentials > Create Credentials > OAuth Client ID.
1. Configure the OAuth Consent Screen. Application Name is required. Save.
1. Select application type: "Web Application".
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.
The Google service account key file obtained from the steps in the guide must be made available on the
host that Vault is running on.
#### 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. The path must refer to a file that's readable on the host that Vault is running on.
- `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.
1. Client Protocol: openid-connect
1. Access Type: confidential
1. Standard Flow Enabled: On
1. Configure Valid Redirect URIs.
1. Save.
1. Visit Credentials. Select Client ID and Secret and note the generated secret.
## Okta
1. Make sure an Authorization Server has been created. The "Issuer" field shown on the Setting page
will be used as the `oidc_discovery_url`.
1. Visit Applications > Add Application (Web).
1. Configure Login redirect URIs. Save.
1. Save client ID and secret.
Note your policy will need `oidc_scopes` to include `profile` to get a full profile ("[Fat Token](https://support.okta.com/help/s/article/Okta-Groups-or-Attribute-Missing-from-Id-Token)"). You will also need to configure bound audience along the lines of `"bound_audiences": ["api://default", "0a4........."]` if you are using the default authorization server.
Reference in a new issue View git blame Copy permalink