Azure Active Directory with OIDC Auth Method and External Groups

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.

Auth Concept

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 the AD_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 and profile.
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.

Infrastructure

Security

Networking

Applications