diff --git a/website/content/docs/auth/jwt/oidc-providers/adfs.mdx b/website/content/docs/auth/jwt/oidc-providers/adfs.mdx new file mode 100644 index 0000000000..9578e99ab2 --- /dev/null +++ b/website/content/docs/auth/jwt/oidc-providers/adfs.mdx @@ -0,0 +1,341 @@ +--- +layout: docs +page_title: Configure Vault with ADFS for OIDC +description: >- + Configure Vault to use Active Directory Federation Services (ADFS) + as an OIDC provider. +--- + +# Configure Vault with ADFS for OIDC + +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+**. +1. **You must be running ADFS on Windows Server**. +1. **You must have an OIDC client secret from your ADFS instance**. +1. **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](/vault/docs/commands/token/create). + +## Step 1: Enable the OIDC authN method for Vault + + + + + +1. Save your Vault instance URL to the `VAULT_ADDR` environment variable: + ```shell-session + $ export VAULT_ADDR="" + ``` + For example: + + + + ```shell-session + $ export VAULT_ADDR="https://myvault.example.com:8200" + ``` + + + +1. Save your Vault instance URL to the `VAULT_TOKEN` environment variable: + ```shell-session + $ export VAULT_TOKEN="" + ``` + For example: + + + + ```shell-session + $ export VAULT_TOKEN="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" + ``` + + + +1. **If you use Vault Enterprise or Vault HCP**, set the namespace where you + have the OIDC plugin mounted to the `VAULT_NAMESPACE` environment variable: + ```shell-session + $ export VAULT_NAMESPACE="" + ``` + For example: + + + + ```shell-session + $ export VAULT_NAMESPACE="oidc-ns" + ``` + + + +1. Enable the OIDC authentication plugin: + ```shell-session + $ vault auth enable -path= oidc + ``` + For example: + + + + ```shell-session + $ vault auth enable -path=/adfs oidc + ``` + + + + + + + +1. Open the web UI for your Vault instance. +1. Select **Access** from the left-hand menu. +1. Right click **Enable new method** on the Access page. +1. Select **OIDC**. +1. Click **Next**. +1. Set the mount path for the OIDC plugin. For example, `adfs`. +1. Click **Enable Method**. +1. Click **Save** to enable the plugin. + + + + + +## Step 2: Create a new application group in ADFS + + + + Make note of the 32-character **client identifier** provided by ADFS for your + new application group (for example, `d879d6fb-d2de-4596-b39c-191b2f83c03f`). + You will need the client ID to configure your OIDC plugin for Vault. + + + +1. Open your Windows Server UI. +1. Go to the Server Manager screen and click **Tools**. +1. Select **AD FS Management**. +1. Right-click on **Application Groups** and select **Add Application Group...**. +1. 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//oidc/callback` + and `http://localhost:8250/oidc/callback`. +1. Check the **Generate a shared secret** box and save the secret string. +1. 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. +1. Click **Add application...** +1. Select **Web API**. +1. 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` +1. Select the new webhook (Vault - Web API) from the properties screen of the + Vault application group. +1. Open the **Issuance Transform Rules** tab. +1. 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` + +[![Screenshot of the Transform Claim Rule Configuration](/img/adfs-oidc-ldapgroupoption.png)](/img/adfs-oidc-ldapgroupoption.png) + +## 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`. + +```shell-session +$ vault write auth//role/ \ + bound_audiences="" \ + allowed_redirect_uris="${VAULT_ADDR}/ui/vault/auth//oidc/callback" \ + allowed_redirect_uris="http://localhost:8250/oidc/callback" \ + user_claim="upn" groups_claim="group" token_policies="default" +``` + + + +Using `upn` value for `user_claim` tells Vault to consider the user email +associated with the ADFS authentication token as an entity alias. + + + +## Step 5: Configure the OIDC plugin + +Use the client ID and shared secret for your ADFS application group to finish +configuring the OIDC plugin. + + + + + +Use the `vault write` CLI command to save the configuration details for the OIDC +plugin where: + +- `ADFS_URL` is the discovery URL for your ADFS instance. For example, + `https://adfs.example.com/adfs` +- `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_APPLICATION_GROUP_SECRET` is the shared secret for your ADFS application + group. +- `ADFS_ROLE` is the name of your role. For example, `adfs-default`. + + +```shell-session +$ vault write auth//config \ + oidc_discovery_url="" \ + oidc_client_id="" \ + oidc_client_secret="" \ + default_role="" +``` + + + + + +1. Open the Vault UI. +1. Select the OIDC plugin from the **Access** screen. +1. Click **Enable Method** and follow the prompts to configure the OIDC plugin + with the following information: + - OIDC discovery URL: the discovery URL for your ADFS instance. For example, + `https://adfs.example.com/adfs`. + - Default role: the name of your new ADFS role. For example, `adfs-default`. +1. Click **OIDC Options** and set your OIDC information: + - OIDC client ID: the application group client ID provided by ADFS. + - OIDC client secret: the shared secret for your ADFS application group. +1. Save your changes. + + + + + + +## OPTIONAL: Link Active Directory groups to Vault + +1. Enable the KV secret engine in Vault for ADFS: + ```shell-session + $ vault secrets enable -path= kv-v2 + ``` + For example: + + + + ```shell-session + $ vault secrets enable -path=adfs-kv kv-v2 + ``` + + + +1. Create a read-only policy against the KV plugin for ADFS: + ```shell-session + $ vault policy write - << EOF + # Read and list policy for the ADFS KV mount + path "/*" { + capabilities = ["read", "list"] + } + EOF + ``` + For example: + + + + ```shell-session + $ vault policy write read-adfs-test - << EOF + # Read and list policy for the ADFS KV mount + path "adfs-kv/*" { + capabilities = ["read", "list"] + } + EOF + ``` + + + +1. Write a test value to the KV plugin: + ```shell-session + $ vault kv put /test test_key="test value" + ``` + For example: + + + + ```shell-session + $ vault kv put adfs-kv/test test_key="test value" + ``` + + + +Now you can create a Vault group and link to an AD group: + + + + + +1. Create an external group in Vault and save the group ID to a file named + `group_id.txt`: + ```shell-session + $ vault write \ + -format=json \ + identity/group name="" \ + policies="" \ + type="external" | jq -r ".data.id" > group_id.txt + ``` +1. Retrieve the mount accessor for the ADFS authentication method and save it to + a file named `accessor_adfs.txt`: + ```shell-session + $ vault auth list -format=json | \ + jq -r '.["/"].accessor' > \ + accessor_adfs.txt + ``` +1. Create a group alias: + ```shell-session + $ vault write identity/group-alias \ + name="" \ + mount_accessor=$(cat accessor_adfs.txt) \ + canonical_id="$(cat group_id.txt)" + ``` +1. Login to Vault as an AD user who is a member of YOUR_EXISTING_AD_GROUP. +1. Read your test value from the KV plugin: + ```shell-session + $ vault kv list -mount=secret /test + ``` + + + + + +1. Open the Vault UI. +1. Select **Access**. +1. Select **Groups**. +1. Click **Create group**. +1. Follow the prompts to create an external group with the following + information: + - Name: your new Vault group name + - Type: `external` + - Policies: the read-only ADFS policy you created. For example, + `read-adfs-test`. +1. Click on **Add alias** and follow the prompts to map the Vault group name + to an existing group on your AD: + - Name: the name of an existing AD group (**must match exactly**). + - Auth Backend: `/ (oidc)` +1. Login to Vault as an AD user who is a member of the aliased AD group. +1. Read your test value from the KV plugin. + + + + + diff --git a/website/content/docs/auth/jwt/oidc-providers/index.mdx b/website/content/docs/auth/jwt/oidc-providers/index.mdx index 6527bbb25f..3c2822047a 100644 --- a/website/content/docs/auth/jwt/oidc-providers/index.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/index.mdx @@ -15,6 +15,7 @@ their recommended settings and best practices. The guides listed 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). +- [ADFS](/vault/docs/auth/jwt/oidc-providers/adfs) - [Auth0](/vault/docs/auth/jwt/oidc-providers/auth0) - [Azure AD](/vault/docs/auth/jwt/oidc-providers/azuread) - [ForgeRock](/vault/docs/auth/jwt/oidc-providers/forgerock) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index bc3f9d33a7..17f20402ac 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1631,6 +1631,10 @@ "title": "Overview", "path": "auth/jwt/oidc-providers" }, + { + "title": "ADFS", + "path": "auth/jwt/oidc-providers/adfs" + }, { "title": "Auth0", "path": "auth/jwt/oidc-providers/auth0" diff --git a/website/public/img/adfs-oidc-ldapgroupoption.png b/website/public/img/adfs-oidc-ldapgroupoption.png new file mode 100644 index 0000000000..7f7cea7388 Binary files /dev/null and b/website/public/img/adfs-oidc-ldapgroupoption.png differ