Docs/scc edits - adfs docs (#24633)

* add adfs link

* add adfs and update index

add the adfs link in the index.mdx
add the file adfs.mdx

* Update docs-nav-data.json

Add the link to ADFS documentation

* add adfs-oidc-ldapgroupoption.png

image for the documentation adfs.mdx

* Update docs-nav-data.json

Updated from the last version of the file and adding adfs link

* suggested edits

* Update the file adfs.mdx

* Update adfs.mdx

Change auth/adfs/config to auth/<YOUR_OIDC_MOUNT_PATH>/config

* Update website/content/docs/auth/jwt/oidc-providers/adfs.mdx

* Corrected typo adfs.mdx

We had 2x step3 so I changed to have step 3 and step 4

---------

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

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
+
+<Tabs>
+
+<Tab heading="Vault CLI">
+
+1. Save your Vault instance URL to the `VAULT_ADDR` environment variable:
+   ```shell-session
+   $ export VAULT_ADDR="<URL_FOR_YOUR_VAULT_INSTALLATION>"
+   ```
+   For example:
+
+   <CodeBlockConfig hideClipboard>
+
+   ```shell-session
+   $ export VAULT_ADDR="https://myvault.example.com:8200"
+   ```
+
+   </CodeBlockConfig>
+
+1. Save your Vault instance URL to the `VAULT_TOKEN` environment variable:
+   ```shell-session
+   $ export VAULT_TOKEN="<YOUR_VAULT_ACCESS_TOKEN>"
+   ```
+   For example:
+
+   <CodeBlockConfig hideClipboard>
+
+   ```shell-session
+   $ export VAULT_TOKEN="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
+   ```
+
+   </CodeBlockConfig>
+ 
+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="<OIDC_NAMESPACE>"
+   ```
+   For example:
+
+   <CodeBlockConfig hideClipboard>
+
+   ```shell-session
+   $ export VAULT_NAMESPACE="oidc-ns"
+   ```
+
+   </CodeBlockConfig>
+
+1. Enable the OIDC authentication plugin:
+  ```shell-session
+  $ vault auth enable -path=<YOUR_OIDC_MOUNT_PATH> oidc
+  ```
+  For example:
+
+  <CodeBlockConfig hideClipboard>
+
+  ```shell-session
+  $ vault auth enable -path=/adfs oidc
+  ```
+
+  </CodeBlockConfig>
+
+</Tab>
+
+<Tab heading="Vault UI">
+
+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.
+
+</Tab>
+
+</Tabs>
+
+## Step 2: Create a new application group in ADFS
+
+<Note title="Save the client ID">
+
+  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.
+
+</Note>
+
+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/<YOUR_OIDC_MOUNT_PATH>/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/<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"
+```
+
+<Tip>
+
+Using `upn` value for `user_claim` tells Vault to consider the user email
+associated with the ADFS authentication token as an entity alias.
+
+</Tip>
+
+## Step 5: Configure the OIDC plugin
+
+Use the client ID and shared secret for your ADFS application group to finish
+configuring the OIDC plugin. 
+
+<Tabs>
+
+<Tab heading="Vault CLI">
+
+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/<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>" 
+```
+
+</Tab>
+
+<Tab heading="Vault UI">
+
+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.
+
+</Tab>
+
+</Tabs>
+
+
+## OPTIONAL: Link Active Directory groups to Vault
+
+1. Enable the KV secret engine in Vault for ADFS:
+   ```shell-session
+   $ vault secrets enable -path=<ADFS_KV_PLUGIN_PATH> kv-v2
+   ```
+   For example:
+
+  <CodeBlockConfig hideClipboard>
+
+  ```shell-session
+   $ vault secrets enable -path=adfs-kv kv-v2
+  ```
+
+  </CodeBlockConfig>
+
+1. Create a read-only policy against the KV plugin for ADFS:
+   ```shell-session
+   $ 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:
+
+  <CodeBlockConfig hideClipboard>
+
+  ```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
+  ```
+
+  </CodeBlockConfig>
+
+1. Write a test value to the KV plugin:
+  ```shell-session
+  $ vault kv put <ADFS_KV_PLUGIN_PATH>/test test_key="test value"
+   ```
+   For example:
+
+  <CodeBlockConfig hideClipboard>
+
+  ```shell-session
+  $ vault kv put adfs-kv/test test_key="test value"
+  ```
+
+  </CodeBlockConfig>
+
+Now you can create a Vault group and link to an AD group:
+
+<Tabs>
+
+<Tab heading="Vault CLI">
+
+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="<YOUR_NEW_VAULT_GROUP_NAME>" \
+    policies="<RO_ADFS_POLICY_NAME>" \
+    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 '.["<YOUR_OIDC_MOUNT_PATH>/"].accessor' > \
+     accessor_adfs.txt
+   ```
+1. Create a group alias:
+   ```shell-session
+   $ vault write identity/group-alias \
+     name="<YOUR_EXISTING_AD_GROUP>"  \
+     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 <ADFS_KV_PLUGIN_PATH>/test
+  ```
+
+</Tab>
+
+<Tab heading="Vault UI">
+
+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: `<YOUR_OIDC_MOUNT_PATH>/ (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.
+
+</Tab>
+
+</Tabs>
+

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)

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"