Before a client can interact with Vault, it must authenticate against an auth method to acquire a token. This token has policies attached so that the behavior of the client can be governed.
NOTE: To learn the basics of Vault tokens, go through the Tokens tutorial.
Auth methods perform authentication to verify the user or machine-supplied information. Some of the supported auth methods are targeted towards users while others are targeted toward machines or apps.
»Challenge
Vault supports a number of auth methods for users or system to prove their identity so that a token with appropriate policies can be obtained. Delegated authorization methods based on OAuth 2.0 are convenient for users and have become increasingly common.
»Solution
If you use Azure Active Directory (AD), you can use Microsoft's identity platform and its implementation of OpenID Connect to verify the identity of a Vault user. By registering a Vault application in Azure, configuring Vault's OIDC auth method, and connecting the AD group with an external group in Vault, your Vault users can log into Vault by web browser. They will be redirected to Azure to complete login and then be routed back to Vault with a newly-created token.
NOTE: To learn how to configure authentication for system-assigned or user-assigned managed identities in Azure, go through documentation on the Azure Auth Method.
This tutorial uses the user's email to authenticate to Azure AD. You can optionally edit some of the claims and Vault configuration to use Azure AD UserPrincipalName (UPN).
»Prerequisites
To perform the tasks described in this tutorial, you need to have a Vault 1.6 or later. Refer to the Getting Started tutorial to install Vault. Make sure that your Vault server has been initialized and unsealed.
In this tutorial, make sure that Azure can access your Vault server to successfully redirect the authentication request.
»Azure Active Directory
This tutorial uses Azure Active Directory. Make sure you have:
Configured an Azure AD tenant.
Sufficient permissions to configure application registrations and read group information.
Signed into Azure from the CLI with the correct tenant ID.
An Azure AD group you can use to connect to a Vault external group.
»Policy requirements
NOTE: For the purpose of this tutorial, you can use the root
token to work
with Vault. However, it is recommended that root tokens are only used for just
enough initial setup or in emergencies. As a best practice, use tokens with
an appropriate set of policies based on your role in the organization.
To perform all tasks demonstrated in this tutorial, your policy must include the following permissions:
# Mount the OIDC auth method
path "sys/auth/oidc" {
capabilities = [ "create", "read", "update", "delete", "sudo" ]
}
# Configure the OIDC auth method
path "auth/oidc/*" {
capabilities = [ "create", "read", "update", "delete", "list" ]
}
# Write ACL policies
path "sys/policies/acl/*" {
capabilities = [ "create", "read", "update", "delete", "list" ]
}
# List available secrets engines to retrieve accessor ID
path "sys/mounts" {
capabilities = [ "read" ]
}
# Manage secrets engines
path "sys/mounts/*"
{
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
# List, create, update, and delete key/value secrets
path "secret/*"
{
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
If you are not familiar with policies, complete the policies tutorial.
»Register Vault as a web app
An app registration allows Azure AD to identify Vault and the user.
Set the
VAULT_ADDR
environment variable to the address of your Vault server.$ export VAULT_ADDR=<your Vault server address>
Set the
AD_AZURE_DISPLAY_NAME
environment variable to a unique display name for Vault's app registration.$ export AD_AZURE_DISPLAY_NAME=vault-<unique identifier>
NOTE: Choose a unique name for the app registration of Vault. Otherwise, an existing app registration will be overwritten by new parameters.
Register a web app for Vault with two redirect URIs (also called
reply-urls
). One URI is for Vault CLI access and the second is for UI access. Save the application ID to theAD_VAULT_APP_ID
environment variable.$ export AD_VAULT_APP_ID=$(az ad app create \ --display-name ${AD_AZURE_DISPLAY_NAME} \ --reply-urls "http://localhost:8250/oidc/callback" \ "${VAULT_ADDR}/ui/vault/auth/oidc/oidc/callback" | \ jq -r '.appId')
Retrieve the application ID of the Microsoft Graph API, which allows you to access Azure service resources. This ID will be used to attach API permissions to the app registration.
$ export AD_MICROSOFT_GRAPH_API_ID=$(az ad sp list \ --filter "displayName eq 'Microsoft Graph'" \ --query '[].appId' -o tsv)
Using the Microsoft Graph API ID, retrieve the ID of the permission for
GroupMember.Read.All
.$ export AD_PERMISSION_GROUP_MEMBER_READ_ALL_ID=$(az ad sp show \ --id ${AD_MICROSOFT_GRAPH_API_ID} \ --query "oauth2Permissions[?value=='GroupMember.Read.All'].id" -o tsv)
Add the
GroupMember.Read.All
permission to the application. This allows the application to read an Active Directory group and its users.$ az ad app permission add \ --id ${AD_VAULT_APP_ID} \ --api ${AD_MICROSOFT_GRAPH_API_ID} \ --api-permissions ${AD_PERMISSION_GROUP_MEMBER_READ_ALL_ID}=Scope
NOTE: If you would want to use UPN instead of email, you may need to add additional permissions such as
User.Read
andprofile
.Create a service principal to attach to the application. The service principal allows you to grant administrative consent from the Azure CLI.
$ az ad sp create --id ${AD_VAULT_APP_ID}
Grant administrative consent for the application to access the Microsoft Graph API.
$ az ad app permission grant --id ${AD_VAULT_APP_ID} \ --api ${AD_MICROSOFT_GRAPH_API_ID}
Retrieve the Azure tenant ID for the application and set it to the
AD_TENANT_ID
environment variable.$ export AD_TENANT_ID=$(az ad sp show --id ${AD_VAULT_APP_ID} \ --query 'appOwnerTenantId' -o tsv)
Reset the client secret for the application and set the password to the
AD_CLIENT_SECRET
environment variable. You will need the secret to configure the OIDC auth method in Vault.$ export AD_CLIENT_SECRET=$(az ad app credential reset \ --id ${AD_VAULT_APP_ID} | jq -r '.password')
»Update application group claims and ID tokens
In order to use AD groups to authenticate to Vault, you need to update the Vault application in Azure with a claim for group membership information.
Create a file named manifest.json
with the specification for an ID token
for an AD group.
$ cat > manifest.json << EOF
{
"idToken": [
{
"name": "groups",
"additionalProperties": []
}
]
}
EOF
Update the application with the claims manifest in manifest.json
and set groupMembershipClaims
to SecurityGroup
. You can expand the
group type
to additional groups.
$ az ad app update --id ${AD_VAULT_APP_ID} \
--set groupMembershipClaims=SecurityGroup \
--optional-claims @manifest.json
»Create Vault policies for an example group
Every client token has policies attached to it to control its secret access. You must create the policies before defining them in the OIDC configuration.
Set the VAULT_TOKEN
environment variable to a Vault token with sufficient
permissions to configure auth methods.
$ export VAULT_TOKEN=<your Vault token>
Create an example Vault policy that allows an application development team to
access and modify secrets mounted at secrets/
.
$ cat > kv-reader-policy.hcl << EOF
path "secret/*" {
capabilities = ["read", "list"]
}
EOF
Write the policy named kv-reader
to Vault.
$ vault policy write kv-reader kv-reader-policy.hcl
As part of this example, you can enable the key-value secrets engine at
secret/
.
$ vault secrets enable -path=secret -version=2 kv
»Configure Vault with the OIDC auth method
OIDC must be enabled and configured before it can be used. In this tutorial, you
will configure OIDC for a role named app-dev
, which application development
teams can use to log in and access secrets.
Set the VAULT_LOGIN_ROLE
environment variable to app-dev
. In your own
configuration, you can change this role name.
$ export VAULT_LOGIN_ROLE=app-dev
Enable the OIDC auth method on the Vault server.
$ vault auth enable oidc
Configure the OIDC auth method with the application ID, client secret, and tenant ID of your Vault application in Azure AD.
$ vault write auth/oidc/config \
oidc_client_id="${AD_VAULT_APP_ID}" \
oidc_client_secret="${AD_CLIENT_SECRET}" \
default_role="${VAULT_LOGIN_ROLE}" \
oidc_discovery_url="https://login.microsoftonline.com/${AD_TENANT_ID}/v2.0"
Add a role to Vault called app-dev
that uses the Vault policy to read secrets
(kv-reader
). It authenticates to Azure by a user's email. In addition, it
passes the group_claim
of groups
you previously configured as part of the
claims manifest. The oidc_scopes
should be set to the
https://graph.microsoft.com/.default
, which is the Microsoft Graph API.
$ vault write auth/oidc/role/${VAULT_LOGIN_ROLE} \
user_claim="email" \
allowed_redirect_uris="http://localhost:8250/oidc/callback" \
allowed_redirect_uris="https://${VAULT_ADDR}/ui/vault/auth/oidc/oidc/callback" \
groups_claim="groups" \
policies="kv-reader" \
oidc_scopes="https://graph.microsoft.com/.default"
NOTE: If you want to use UPN instead of user email, change the
user_claim
field to upn
.
»Set up a Vault external group for the AD group
You have an existing Active Directory group with a set of application development team users. Connect this Azure AD group to a Vault policy, which will allow any users in the Azure AD group to log into Vault by email and access secrets.
Get the ID of the Azure AD group you want to connect to a Vault policy.
$ export AD_GROUP_ID=$(az ad group show \
--group <Azure AD group display name> \
--query objectId -o tsv)
Create an external group named app-dev
in the Vault identity secrets engine
that references the app-dev
policy and set the group ID in the
VAULT_GROUP_ID
environment variable.
$ export VAULT_GROUP_ID=$(vault write \
-field=id -format=table \
identity/group \
name="${VAULT_LOGIN_ROLE}" \
type="external" \
policies="kv-reader")
Retrieve Vault's OIDC accessor ID and set it to the VAULT_OIDC_ACCESSOR_ID
environment variable.
$ export VAULT_OIDC_ACCESSOR_ID=$(vault auth list -format=json | \
jq -r '."oidc/".accessor')
Map the Vault group to the Azure AD group ID and set the alias ID as the
VAULT_GROUP_ALIAS_ID
environment variable.
$ export VAULT_GROUP_ALIAS_ID=$(vault write \
-field=id -format=table \
identity/group-alias \
name="${AD_GROUP_ID}" \
mount_accessor="${VAULT_OIDC_ACCESSOR_ID}" \
canonical_id="${VAULT_GROUP_ID}")
Open a new terminal. Set the VAULT_ADDR
environment variable to your Vault
server.
$ export VAULT_ADDR=<your Vault server address>
Try to log into the server with the OIDC auth method as a member of the AD group you configured with Vault. If it is successful, the command launches a browser to Azure for you to log in and return a Vault token.
$ vault login -method=oidc role="app-dev"
Complete the login via your OIDC provider. Launching browser to:
https://login.microsoftonline.com/...
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token s.REDACTED
token_accessor u58XsOYz2I5T1GmqwsaaOpsP.WEwzy
token_duration 1h
token_renewable true
token_policies ["default" "kv-reader"]
identity_policies []
policies ["default" "kv-reader"]
token_meta_role app-dev
As part of the app-dev
role that is connected to the AD group, you should be
able to access secret/
.
$ vault kv list secret
No value found at secret/metadata
»Summary
In this tutorial, you configured Vault's OIDC auth method to authenticate a user by using a group in Azure Active Directory. This allowed the user to read and list secrets from Vault.