Use ADFS for OIDC authentication

Configure your Vault instance to work with Active Directory Federation Services (ADFS) and use ADFS accounts with OIDC for Vault login.

Before you start

1. You must have Vault v1.15.0+.
2. You must be running ADFS on Windows Server.
3. You must have an OIDC client secret from your ADFS instance.
4. You must know your Vault admin token. If you do not have a valid admin token, you can generate a new token in the Vault UI or with the Vault CLI.

Step 1: Enable the OIDC authN method for Vault

Step 2: Create a new application group in ADFS

1. Open your Windows Server UI.
2. Go to the Server Manager screen and click Tools.
3. Select AD FS Management.
4. Right-click on Application Groups and select Add Application Group....
5. Follow the prompts to create a new application group with the following information:
   • Name: Vault
   • Description: a short description explaining the purpose of the application group. For example, "Enable access to Vault".
   • Application type: Server application
   • Redirect URI: add the callback URL of your OIDC plugin for web redirects and the local OIDC callback URL for Vault CLI redirects. For example, https://myvault.example.com:8200/ui/vault/auth/<YOUR_OIDC_MOUNT_PATH>/oidc/callback and http://localhost:8250/oidc/callback.
6. Check the Generate a shared secret box and save the secret string.
7. Confirm the application group details and correct information before closing.

Step 3: Configure the webhook in ADFS

1. Open the Vault application group in from the ADFS management screen.
2. Click Add application...
3. Select Web API.
4. Follow the prompts to configure a new webhook with the following information:
   • Identifier: the client ID of your application group
   • Access control policy: select an existing policy or Permit everyone
   • Enable allatclaims, email, openid, and profile
5. Select the new webhook (Vault - Web API) from the properties screen of the Vault application group.
6. Open the Issuance Transform Rules tab.
7. Click Add Rule... and follow the prompts to create a new authentication rule with the following information:
   • Select Send LDAP Attributes as Claims
   • Rule name: LDAP Group
   • Attribute store: Active Directory
   • LDAP attribute: Token-Groups - Unqualified Names
   • Outgoing claim type: Group

Step 4: Create a default ADFS role in Vault

Use the vault write CLI command to create a default role for users authenticating with ADFS where:

• ADFS_APPLICATION_GROUP_CLIENT_ID is the client ID provided by ADFS.
• YOUR_OIDC_MOUNT_PATH is the mount path for the OIDC plugin.. For example, adfs.
• ADFS_ROLE is the name of your role. For example, adfs-default.

$ vault write auth/<YOUR_OIDC_MOUNT_PATH>/role/<ADFS_ROLE> \
  bound_audiences="<ADFS_APPLICATION_GROUP_CLIENT_ID>" \
  allowed_redirect_uris="${VAULT_ADDR}/ui/vault/auth/<YOUR_OIDC_MOUNT_PATH>/oidc/callback" \
  allowed_redirect_uris="http://localhost:8250/oidc/callback" \
  user_claim="upn" groups_claim="group" token_policies="default"

Step 5: Configure the OIDC plugin

Use the client ID and shared secret for your ADFS application group to finish configuring the OIDC plugin.

$ vault write auth/<YOUR_OIDC_MOUNT_PATH>/config \
  oidc_discovery_url="<ADFS_URL>" \
  oidc_client_id="<ADFS_APPLICATION_GROUP_CLIENT_ID>" \
  oidc_client_secret="<ADFS_APPLICATION_GROUP_SECRET>" \
  default_role="<ADFS_ROLE>" 

OPTIONAL: Link Active Directory groups to Vault

1. Enable the KV secret engine in Vault for ADFS:

   $ vault secrets enable -path=<ADFS_KV_PLUGIN_PATH> kv-v2
   

   For example:

    $ vault secrets enable -path=adfs-kv kv-v2
   

2. Create a read-only policy against the KV plugin for ADFS:

   $ vault policy write <RO_ADFS_POLICY_NAME> - << EOF
   # Read and list policy for the ADFS KV mount
   path "<ADFS_KV_PLUGIN_PATH>/*" {
     capabilities = ["read", "list"]
   }
   EOF
   

   For example:

    $ vault policy write read-adfs-test - << EOF
    # Read and list policy for the ADFS KV mount
    path "adfs-kv/*" {
      capabilities = ["read", "list"]
    }
    EOF
   

3. Write a test value to the KV plugin:

   $ vault kv put <ADFS_KV_PLUGIN_PATH>/test test_key="test value"
   

   For example:

   $ vault kv put adfs-kv/test test_key="test value"
   

Now you can create a Vault group and link to an AD group: