save edits

website/content/docs/auth/saml/link-vault-group-to-ad.mdx

@@ -0,0 +1,196 @@
+---
+layout: docs
+page_title: Link your SAML Active Directory groups to Vault
+description: >-
+  Configure Vault to connect Vault policies to Active Directory groups with
+  Active Directory Federation Services (AD FS) as a SAML provider.
+---
+
+# Link Active Directory SAML groups to Vault
+
+@include 'alerts/enterprise-and-hcp.mdx'
+
+Configure your Vault instance to link your Active Directory groups to Vault
+policies with SAML.
+
+
+
+## Before you start
+
+- **You must have Vault Enterprise or HCP Vault v1.15.5+**.
+- **You must be running AD FS on Windows Server**.
+- **You must have a [SAML plugin configured for AD FS](/vault/docs/auth/saml/adfs)**.
+- **You must have a Vault admin token**. If you do not have a valid admin
+   token, you can generate a new token in the Vault GUI or using
+   [`vault token create`](/vault/docs/commands/token/create) with the Vault CLI.
+
+
+
+## Step 1: Enable a `kv` plugin instance for AD clients
+
+<Tabs>
+
+<Tab heading="Vault CLI" group="cli">
+
+Enable an instance of the KV secret engine for AD FS under a custom path:
+
+```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>
+
+</Tab>
+
+<Tab heading="Vault GUI" group="gui">
+
+@include 'gui-page-instructions/enable-secrets-plugin.mdx'
+
+- Enable the KV plugin:
+
+    1. Select the **KV** token.
+    1. Set a mount path that reflects the plugin purpose. For example: `dfs-kv`.
+    1. Click **Enable engine**.
+
+</Tab>
+
+</Tabs>
+
+
+## Step 2: Create a read-only policy for the `kv` plugin
+
+<Tabs>
+
+<Tab heading="Vault CLI" group="cli">
+
+Use `vault write` to create a read-only policy for AD FS clients that use the
+new KV plugin:
+
+```shell-session
+$ vault policy write <RO_ADFS_POLICY_NAME> - << EOF
+# Read and list policy for the AD FS KV mount
+path "<ADFS_KV_PLUGIN_PATH>/*" {
+  capabilities = ["read", "list"]
+}
+EOF
+```
+
+For example:
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ vault policy write ro-saml-adfs - << EOF
+# Read and list policy for the AD FS KV mount
+path "adfs-kv/*" {
+  capabilities = ["read", "list"]
+}
+EOF
+```
+
+</CodeBlockConfig>
+
+</Tab>
+
+<Tab heading="Vault GUI" group="gui">
+
+@include 'gui-page-instructions/create-acl-policy.mdx'
+
+- Set the policy details and click **Create policy**:
+
+    - **Name**: "ro-saml-adfs"
+    - **Policy**:
+    ```hcl
+    # Read and list policy for the AD FS KV mount
+    path "<ADFS_KV_PLUGIN_PATH>/*" {
+      capabilities = ["read", "list"]
+    }
+    ```
+
+</Tab>
+
+</Tabs>
+
+
+
+## Step 3: Create and link a Vault group to AD
+
+<Tabs>
+
+<Tab heading="Vault CLI" group="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="SamlVaultReader"  \
+     policies="ro-adfs-test"                \
+     type="external" | jq -r ".data.id" > group_id.txt
+   ```
+
+1. Retrieve the mount accessor for the AD FS authentication method and save it
+   to a file named `accessor_adfs.txt`:
+
+   ```shell-session
+   $ vault auth list -format=json |               \
+     jq -r '.["<SAML_PLUGIN_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)"
+   ```
+
+
+</Tab>
+
+<Tab heading="Vault GUI" group="gui">
+
+@include 'gui-page-instructions/create-group.mdx'
+
+- Follow the prompts to create an external group with the following
+  information:
+     - Name: your new Vault group name
+     - Type: `external`
+     - Policies: the read-only AD FS policy you created. For example,
+       `ro-adfs-test`.
+
+- Click **Add alias** and follow the prompts to map the Vault group name to an
+  existing group in Active Directory:
+   - Name: the name of an existing AD group (**must match exactly**).
+   - Auth Backend: `<SAML_PLUGIN_PATH>/ (saml)`
+
+</Tab>
+
+</Tabs>
+
+
+## Step 4: Verify the link to Active Directory
+
+1. Use the Vault CLI to login as an Active Directory user who is a member of
+   the linked Active Directory group:
+
+   ```shell-session
+   $ vault login -method saml -path <SAML_PLUGIN_PATH>
+   ```
+
+1. Read your test value from the KV plugin:
+
+   ```shell-session
+   $ vault kv get adfs-kv/test
+   ```

website/content/docs/auth/saml/troubleshoot-adfs/adfs-event-320.mdx

@@ -0,0 +1,81 @@
+---
+layout: docs
+page_title: "Troubleshoot ADFS and SAML: AD FS event 320"
+description: >-
+  Fix connection problems in Vault due AD FS event 320 when using Active
+  Directory Federation Services (ADFS) as an SAML provider.
+---
+
+# AD FS event 320
+
+Troubleshoot problems where your AD FS event logs show error 320.
+
+
+
+## Example debugging data
+
+AD FS event log shows the following error:
+
+<CodeBlockConfig hideClipboard highlight="1,4">
+
+```shell-session
+The verification of the SAML message signature failed.
+Message issuer: MyVaultIdentifier
+Exception details:
+MSIS7086: The relying party trust 'MyVaultIdentifier' indicates that authentication requests sent by this relying party will be signed but no signature is present.
+```
+
+</CodeBlockConfig>
+
+
+
+## Analysis
+
+Verify that `SignedSamlRequestsRequired` is `false` for your AD FS Relying Party
+Trust for Vault:
+
+```powershell
+Get-AdfsRelyingPartyTrust -Name "<ADFS_VAULT_POLICY_NAME>"
+```
+
+For example:
+
+<CodeBlockConfig hideClipboard>
+
+```powershell
+Get-AdfsRelyingPartyTrust -Name "Vault"
+```
+
+</CodeBlockConfig>
+
+
+
+## Solution
+
+Set `SignedSamlRequestsRequired` to `false`:
+
+```powershell
+$ Set-AdfsRelyingPartyTrust                 `
+    -TargetName "<ADFS_VAULT_POLICY_NAME>"  `
+    -SignedSamlRequestsRequired $false
+```
+
+For example:
+
+<CodeBlockConfig hideClipboard>
+
+```powershell
+$ Set-AdfsRelyingPartyTrust `
+    -TargetName "Vault"     `
+    -SignedSamlRequestsRequired $false
+```
+
+</CodeBlockConfig>
+
+
+
+## Additional resources
+
+- [SAML auth method Documentation](https://developer.hashicorp.com/vault/docs/auth/saml)
+- [SAML API Documentation](https://developer.hashicorp.com/vault/api-docs/auth/saml)
+- [Set up an AD FS lab environment](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/set-up-an-ad-fs-lab-environment)