From 3349dc745d39c508682f8ed206e6ecd8f1fade79 Mon Sep 17 00:00:00 2001 From: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com> Date: Thu, 24 Oct 2024 14:47:33 -0400 Subject: [PATCH] Add SAML example to docs (#27121) * Add SAML example * Docs/add saml edits (#28732) * editing suggestions (start) * save edits * Update website/content/docs/auth/saml/adfs.mdx * Update website/content/docs/auth/saml/index.mdx * Update website/content/docs/auth/saml/adfs.mdx * Update website/content/docs/auth/saml/troubleshoot-adfs/index.mdx --------- Co-authored-by: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com> * Fix content errors * missed one >_< --------- Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --- website/content/docs/auth/saml/adfs.mdx | 252 ++++++++++++++++++ .../docs/auth/{saml.mdx => saml/index.mdx} | 4 +- .../docs/auth/saml/link-vault-group-to-ad.mdx | 196 ++++++++++++++ .../saml/troubleshoot-adfs/adfs-event-320.mdx | 81 ++++++ .../saml/troubleshoot-adfs/bad-mapping.mdx | 187 +++++++++++++ .../saml/troubleshoot-adfs/boundsubjects.mdx | 86 ++++++ .../auth/saml/troubleshoot-adfs/index.mdx | 85 ++++++ .../create-acl-policy.mdx | 12 + .../gui-page-instructions/create-group.mdx | 12 + .../enable-authn-plugin.mdx | 12 + .../enable-secrets-plugin.mdx | 10 + website/data/docs-nav-data.json | 39 ++- 12 files changed, 972 insertions(+), 4 deletions(-) create mode 100644 website/content/docs/auth/saml/adfs.mdx rename website/content/docs/auth/{saml.mdx => saml/index.mdx} (99%) create mode 100644 website/content/docs/auth/saml/link-vault-group-to-ad.mdx create mode 100644 website/content/docs/auth/saml/troubleshoot-adfs/adfs-event-320.mdx create mode 100644 website/content/docs/auth/saml/troubleshoot-adfs/bad-mapping.mdx create mode 100644 website/content/docs/auth/saml/troubleshoot-adfs/boundsubjects.mdx create mode 100644 website/content/docs/auth/saml/troubleshoot-adfs/index.mdx create mode 100644 website/content/partials/gui-page-instructions/create-acl-policy.mdx create mode 100644 website/content/partials/gui-page-instructions/create-group.mdx create mode 100644 website/content/partials/gui-page-instructions/enable-authn-plugin.mdx create mode 100644 website/content/partials/gui-page-instructions/enable-secrets-plugin.mdx diff --git a/website/content/docs/auth/saml/adfs.mdx b/website/content/docs/auth/saml/adfs.mdx new file mode 100644 index 000000000000..5d2172109257 --- /dev/null +++ b/website/content/docs/auth/saml/adfs.mdx @@ -0,0 +1,252 @@ +--- +layout: docs +page_title: Use Active Directory Federation Services for SAML +description: >- + Configure Vault to use Active Directory Federation Services (AD FS) as a SAML + provider. +--- + +# Use Active Directory Federation Services for SAML + +@include 'alerts/enterprise-and-hcp.mdx' + +Configure your Vault instance to work with Active Directory Federation Services +(AD FS) and use AD FS accounts for SAML authentication. + + + +## 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](/vault/docs/auth/saml) enabled**. +- **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 the SAML authN method for Vault + + + + + +1. Set the `VAULT_ADDR` environment variable to your Vault instance URL. For + example: + + ```shell-session + $ export VAULT_ADDR="https://myvault.example.com:8200" + ``` + +1. Set the `VAULT_TOKEN` environment variable with your admin token: + + ```shell-session + $ export VAULT_TOKEN="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" + ``` + +1. Enable the SAML plugin. Use the `-namespace` flag to enable the plugin under + a specific namespace. For example: + + ```shell-session + $ vault -namespace=ns_admin auth enable saml + ``` + + + + + +@include 'gui-page-instructions/enable-authn-plugin.mdx' + +- Enable the SAML plugin: + + 1. Select the **SAML** token. + 1. Set the mount path. + 1. Click **Enable Method**. + + + + + + + +## Step 2: Create a new relying party trust in AD + +1. Open your Windows Server UI. + +1. Go to the **Server Manager** screen. + +1. Click **Tools** and select **AD FS Management**. + +1. Right-click **Relying Party Trusts** and select **Add Relying Party Trust...**. + +1. Follow the prompts to create a new party trust with the following settings: + + | Option | Setting + | ----------------------------------------------------- | ------- + | Claims aware | checked + | Enter data about relying party manually | checked + | Display name | "Vault" + | Certificates | None + | Enable support for the SAML 2.0 WebSSO protocol | checked + | SAML callback URL | Callback endpoint for your SAML plugin + | Relying party trust identifier | Any meaningful, unique string. For example "VaultIdentifier" + | Access control policy | Any valid policy or `Permit everyone` + | Configure claims issuance policy for this application | checked + + + + The callback endpoint for your SAML plugin is: + + `https://${VAULT_ADDRESS}/v1///auth//callback` + + For example, if you mounted the plugin under the `ns_admin` namespace on the + path `org/security`, the callback endpoint URL would be: + + `https://${VAULT_ADDRESS}/v1/ns_admin/auth/org/security/saml/callback` + + + + + +## Step 3: Configure the claim issuance policy in AD + +1. Open your Windows Server UI. + +1. Go to the **Server Manager** screen. + +1. Click **Tools** and select **AD FS Management**. + +1. Right-click your new **Relying Party Trust** entry and select + **Edit Claim Issuance Policy...**. + +1. Click **Add Rule...** and follow the prompts to create a new **Transform + Claim Rule** with the following settings: + + | Option | Setting + | ------------------------------- | ------- + | Send LDAP Attributes as Claims | selected + | Rule name | Any meaningful string (e.g., "Vault SAML Claims") + | Attribute store | `Active Directory`. + +1. Complete the LDAP attribute array with the following settings: + + | LDAP attribute | Outgoing claim type | + |------------------------------------|-------------------------------| + | `E-Mail-Addresses` | `Name ID` | + | `E-Mail-Addresses` | `E-Mail Address` | + | `Token-Groups - Unqualified Names` | `groups` or `Group` | + + + +## Step 4: Update the SAML signature in AD + +1. Open a PowerShell terminal on your Windows server. + +1. Set the SAML signature for your relying party trust identifier to `false`: + + ```powershell + Set-ADFSRelyingPartyTrust ` + -TargetName "" ` + -SignedSamlRequestsRequired $false + ``` + + For example: + + + + ```powershell + Set-ADFSRelyingPartyTrust ` + -TargetName "MyVaultIdentifier" ` + -SignedSamlRequestsRequired $false + ``` + + + +## Step 5: Create a default AD FS role in Vault + +Use the Vault CLI to create a default role for users authenticating +with AD FS where: + +- `SAML_PLUGIN_PATH` is the full path (`/MOUNT_PATH/NAME`) to your + SAML plugin. +- `VAULT_ROLE` is the name of your new AD FS role. For example, `adfs-default`. +- `DOMAIN_LIST` is a comma separated list of target domains in Active Directory. + For example: `*@example.com,*@ext.example.com`. +- `GROUP_ATTRIBUTES_REF` is: + - `groups` if your LDAP token group is `groups` + - `http://schemas.xmlsoap.org/claims/Group` if your LDAP token group is + `Group` +- `AD_GROUP_LIST` is a comma separated list of Active Directory groups that + will authenticate with SAML. For example: `VaultAdmin,VaultUser`. + +```shell-session +$ vault write /role/ \ + bound_subjects="" \ + bound_subjects_type="glob" \ + groups_attribute= \ + bound_attributes=groups="" \ + token_policies="default" \ + ttl="1h" +``` + +For example: + + + +```shell-session +$ vault write auth/saml/role/adfs-default \ + bound_subjects="*@example.com,*@ext.example.com" \ + bound_subjects_type="glob" \ + groups_attribute=groups \ + bound_attributes=groups="VaultAdmin,VaultUser" \ + token_policies="default" \ + ttl="1h" +``` + + + + + +## Step 6: Configure the SAML plugin in Vault + +Use the Vault CLI to finish configuring the SAML plugin where: + +- `SAML_PLUGIN_PATH` is the full path to your SAML plugin: + `/auth//`. +- `VAULT_ROLE` is the name of your new AD FS role in Vault. +- `TRUST_IDENTIFIER` is the ID of your new relying party trust in AD FS. +- `SAML_CALLBACK_URL` is the callback endpoint for your SAML plugin: + `http://${VAULT_ADDR}//auth///callback`. +- `ADFS_URL` is the discovery URL for your AD FS instance. +- `METADATA_FILE_PATH` is the path on your AD FS instance to the federation + metadata file. + +```shell-session +$ vault write /config \ + default_role="" \ + entity_id="" \ + acs_urls=" \ + idp_metadata_url="/" +``` + +For example: + + + +```shell-session +$ vault write ns_admin/auth/org/security/saml/config \ + default_role="adfs-default" \ + entity_id="MyVaultIdentifier" \ + acs_urls="${VAULT_ADDR}/v1/ns_admin/auth/org/security/saml/callback" \ + idp_metadata_url="https://adfs.example.com/metadata/2007-06/federationmetadata.xml" +``` + + + + + +## Next steps + +- [Link your Active Directory groups to Vault](/vault/docs/auth/saml/link-vault-group-to-ad) +- [Troubleshoot your SAML + AD FS configuration](/vault/docs/auth/saml/troubleshoot-adfs) diff --git a/website/content/docs/auth/saml.mdx b/website/content/docs/auth/saml/index.mdx similarity index 99% rename from website/content/docs/auth/saml.mdx rename to website/content/docs/auth/saml/index.mdx index 54cde9a354bb..7b004c1c6148 100644 --- a/website/content/docs/auth/saml.mdx +++ b/website/content/docs/auth/saml/index.mdx @@ -8,7 +8,7 @@ description: >- # SAML auth method - +@include 'alerts/enterprise-and-hcp.mdx' The `saml` auth method allows users to authentication with Vault using their identity within a [SAML V2.0](https://saml.xml.org/saml-specifications) identity provider. @@ -190,4 +190,4 @@ You can read more at the Microsoft identity platform's ## API The SAML authentication plugin has a full HTTP API. Refer to the -[SAML API documentation](/vault/api-docs/auth/saml) for more details. +[SAML API documentation](/vault/api-docs/auth/saml) for more details. \ No newline at end of file diff --git a/website/content/docs/auth/saml/link-vault-group-to-ad.mdx b/website/content/docs/auth/saml/link-vault-group-to-ad.mdx new file mode 100644 index 000000000000..962d3dae740a --- /dev/null +++ b/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 + + + + + +Enable an instance of the KV secret engine for AD FS under a custom path: + +```shell-session +$ vault secrets enable -path= kv-v2 +``` + +For example: + + + +```shell-session +$ vault secrets enable -path=adfs-kv kv-v2 +``` + + + + + + + +@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**. + + + + + + +## Step 2: Create a read-only policy for the `kv` plugin + + + + + +Use `vault write` to create a read-only policy for AD FS clients that use the +new KV plugin: + +```shell-session +$ vault policy write - << EOF +# Read and list policy for the AD FS KV mount +path "/*" { + capabilities = ["read", "list"] +} +EOF +``` + +For example: + + + +```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 +``` + + + + + + + +@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 "/*" { + capabilities = ["read", "list"] + } + ``` + + + + + + + +## Step 3: Create and link a Vault group to AD + + + + + +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 '.["/"].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)" + ``` + + + + + + +@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)` + + + + + + +## 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 + ``` + +1. Read your test value from the KV plugin: + + ```shell-session + $ vault kv get adfs-kv/test + ``` diff --git a/website/content/docs/auth/saml/troubleshoot-adfs/adfs-event-320.mdx b/website/content/docs/auth/saml/troubleshoot-adfs/adfs-event-320.mdx new file mode 100644 index 000000000000..f9d771314494 --- /dev/null +++ b/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: + + + +```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. +``` + + + + + +## Analysis + +Verify that `SignedSamlRequestsRequired` is `false` for your AD FS Relying Party +Trust for Vault: + +```powershell +Get-AdfsRelyingPartyTrust -Name "" +``` + +For example: + + + +```powershell +Get-AdfsRelyingPartyTrust -Name "Vault" +``` + + + + + +## Solution + +Set `SignedSamlRequestsRequired` to `false`: + +```powershell +$ Set-AdfsRelyingPartyTrust ` + -TargetName "" ` + -SignedSamlRequestsRequired $false +``` + +For example: + + + +```powershell +$ Set-AdfsRelyingPartyTrust ` + -TargetName "Vault" ` + -SignedSamlRequestsRequired $false +``` + + + + + +## Additional resources + +- [SAML auth method Documentation](/vault/docs/auth/saml) +- [SAML API Documentation](/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) diff --git a/website/content/docs/auth/saml/troubleshoot-adfs/bad-mapping.mdx b/website/content/docs/auth/saml/troubleshoot-adfs/bad-mapping.mdx new file mode 100644 index 000000000000..554316a8c1fc --- /dev/null +++ b/website/content/docs/auth/saml/troubleshoot-adfs/bad-mapping.mdx @@ -0,0 +1,187 @@ +--- +layout: docs +page_title: "Troubleshoot ADFS and SAML: automatic group mapping fails" +description: >- + Fix connection problems in Vault due to a bad mapping between groups and + policies when using Active Directory Federation Services (ADFS) as an SAML + provider. +--- + +# Automatic group mapping fails + +Troubleshoot problems where the debugging data suggests a bad or nonexistent +mapping between your Vault role and AD FS the Claim Issuance Policy. + + + +## Example debugging data + + + +```json +[DEBUG] auth.saml.auth_saml_1d2227e7: validating user context for role: api=callback role_name=default-saml +role="{ + "token_bound_cidrs":null, + "token_explicit_max_ttl":0, + "token_max_ttl":0, + "token_no_default_policy":false, + "token_num_uses":0, + "token_period":0, + "token_policies":["default"], + "token_type":0, + "token_ttl":0, + "BoundSubjects":["*@example.com","*@ext.example.com"], + "BoundSubjectsType":"glob", + "BoundAttributes":{"http://schemas.xmlsoap.org/claims/Group":["VaultAdmin","VaultUser"]}, + "BoundAttributesType":"string", + "GroupsAttribute":"groups" + }" +user context="{ + "attributes": + { + "http://schemas.xmlsoap.org/claims/Group":["Domain Users","VaultAdmin"], + "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress":["rs@example.com"] + }, + "subject":"rs@example.com" +}" +``` + + + + + +## Analysis + +Use `vault read` to review the current role configuration: + + + +```shell-session +$ vault read auth//role/ + +Key Value +--- ----- +bound_attributes map[http://schemas.xmlsoap.org/claims/Group:[VaultAdmin VaultUser]] +bound_attributes_type string +bound_subjects [*@example.com *@ext.example.com] +bound_subjects_type glob +groups_attribute groups +token_bound_cidrs [] +token_explicit_max_ttl 0s +token_max_ttl 0s +token_no_default_policy false +token_num_uses 0 +token_period 0s +token_policies [default] +token_ttl 0s +token_type default +``` + + + +The Vault role uses `groups` for the group attribute, so Vault expects user +context in the SAML response to include a `groups` attribute with the form: + + + +```text +user context="{ + "attributes": + { + "groups":[]", + ... + } +}" +``` + + +But the SAML response indicates the Claim Issuance Policy uses `Group` for the +group attribute, so the user context uses `Group` to key the bound groups: + + + + +```text +user context="{ + "attributes": + { + "http://schemas.xmlsoap.org/claims/Group":["Domain Users","VaultAdmin"], + ... + }, + "subject":"rs@example.com" +}" +``` + + + + + +## Solution + + + + + +The first option to resolve the problem is update `group_attribute` for the +Vault role to use `Group`: + +```shell-session +$ vault write auth//role/ \ + groups_attribute=http://schemas.xmlsoap.org/claims/Group +``` + +For example: + + + +```shell-session +$ vault write auth/saml/role/adfs-default \ + groups_attribute=http://schemas.xmlsoap.org/claims/Group +``` + + + + + + + +The second option to resolve the problem is to update your AD FS configuration +to use `groups` and confirm the bound attributes in Vault match the expected +groups: + +1. Update your AD FS the Claim Issuance Policy to use `groups` for unqualified + names: + + | LDAP attribute | Outgoing claim type + |------------------------------------|-------------------- + | `Token-Groups - Unqualified Names` | `groups` + +1. Verify the bound attribute for your Vault role match the groups listed in the + SAML response: + + ```shell-session + $ vault write auth//role/ \ + bound_attributes=groups="" + ``` + + For example: + + + + ```shell-session + $ vault write auth/saml/role/default-adfs \ + bound_attributes=groups="VaultAdmin,VaultUser" + ``` + + + + + + + + +## Additional resources + +- [SAML auth method Documentation](/vault/docs/auth/saml) +- [SAML API Documentation](/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) diff --git a/website/content/docs/auth/saml/troubleshoot-adfs/boundsubjects.mdx b/website/content/docs/auth/saml/troubleshoot-adfs/boundsubjects.mdx new file mode 100644 index 000000000000..6ed4e01d7f7b --- /dev/null +++ b/website/content/docs/auth/saml/troubleshoot-adfs/boundsubjects.mdx @@ -0,0 +1,86 @@ +--- +layout: docs +page_title: "Troubleshoot ADFS and SAML: invalid BoundSubjects" +description: >- + Fix connection problems in Vault due to an invalid BoundSubject entry when + using Active Directory Federation Services (ADFS) as an SAML provider. +--- + +# Clients cannot connect to Vault: invalid `BoundSubjects` + +Troubleshoot problems where the debugging data suggests a problem with bound +subjects. + + + +## Example debugging data + + + +```json +[DEBUG] auth.saml.auth_saml_b1886dfe: validating user context for role: api=callback role_name=default-saml +role="{ + "token_bound_cidrs":null, + "token_explicit_max_ttl":0, + "token_max_ttl":0, + "token_no_default_policy":false, + "token_num_uses":0, + "token_period":0, + "token_policies":["default"], + "token_type":0, + "token_ttl":0, + "BoundSubjects":["*@example.com *@ext.example.com"], + "BoundSubjectsType":"glob", + "BoundAttributes":{"groups":["VaultAdmin","VaultUser"]}, + "BoundAttributesType":"string", + "GroupsAttribute":"groups" +}" +user context="{ + "attributes": + { + "groups":["Domain Users","VaultAdmin"], + "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress":["rs@example.com"] + }, + "subject":"rs@example.com" +}" +``` + + + + + +## Analysis + +The SAML role expects a single string with a comma separated list of relevant +domains for `BoundSubjects`, but the provided string is malformed. + + +## Solution + +To resolve the problem, update your SAML role and correct the `BoundSubjects` +string: + +```shell-session +$ vault write auth//role/ \ +bound_subjects="" +``` + +For example: + + + +```shell-session +$ vault write auth/saml/role/adfs-default \ +bound_subjects="*@example.com, *@ext.example.com" +``` + + + + + + +## Additional resources + +- [SAML auth method Documentation](/vault/docs/auth/saml) +- [SAML API Documentation](/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) diff --git a/website/content/docs/auth/saml/troubleshoot-adfs/index.mdx b/website/content/docs/auth/saml/troubleshoot-adfs/index.mdx new file mode 100644 index 000000000000..7dbd90690dc5 --- /dev/null +++ b/website/content/docs/auth/saml/troubleshoot-adfs/index.mdx @@ -0,0 +1,85 @@ +--- +layout: docs +page_title: Troubleshoot ADFS and SAML +description: >- + Troubleshoot problems in Vault when using use Active Directory Federation + Services (ADFS) as an SAML provider. +--- + +# Troubleshoot your SAML AD FS configuration + +Troubleshooting guidance for solving problems with AD FS and SAML. + +## Temporarily enable verbose logging + + + + Expanding SAML response data is a **temporary** change. Do not leave verbose + logging on in production as SAML responses may contain sensitive information. + + + +1. Enable verbose logging for your SAML plugin: + + ```shell-session + $ vault write auth//config \ + default_role="" \ + verbose_logging=true + ``` + +1. Stream the debug logs directly to the terminal: + + ```shell-session + $ vault monitor -log-level=debug + ``` + +## Analyze the expanded SAML response + +To debug SAML problems, consider the following fields in the expanded response +objects: + +- **`role`** - the configuration details of your SAML role +- **`user context`** - details about the client connecting to Vault + +When debugging SAML problems, start with the bound subjects and bound attributes +of your SAML role. The provided values should match the attribute details in the +user context. For example: + + + +```json +[DEBUG] auth.saml.auth_saml_1d2227e7: validating user context for role: api=callback role_name=default-saml +role="{ + "token_bound_cidrs":null, + "token_explicit_max_ttl":0, + "token_max_ttl":0, + "token_no_default_policy":false, + "token_num_uses":0, + "token_period":0, + "token_policies":["default"], + "token_type":0, + "token_ttl":0, + "BoundSubjects":["*@example.com","*@ext.example.com"], + "BoundSubjectsType":"glob", + "BoundAttributes":{"groups":["VaultAdmin","VaultUser"]}, + "BoundAttributesType":"string", + "GroupsAttribute":"groups" +}" +user context="{ + "attributes": + { + "groups":["Domain Users","VaultAdmin"], + "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress":["rs@example.com"] + }, + "subject":"rs@example.com" +}" +``` + + + + +## Troubleshooting walkthroughs + +- [AD FS error 320](/vault/docs/auth/saml/troubleshoot-adfs/adfs-event-320) +- [Automatic group mapping fails](/vault/docs/auth/saml/troubleshoot-adfs/bad-mapping) +- Clients cannot connect to Vault: [Invalid `BoundSubjects`](/vault/docs/auth/saml/troubleshoot-adfs/boundsubjects) diff --git a/website/content/partials/gui-page-instructions/create-acl-policy.mdx b/website/content/partials/gui-page-instructions/create-acl-policy.mdx new file mode 100644 index 000000000000..52501aac0d0a --- /dev/null +++ b/website/content/partials/gui-page-instructions/create-acl-policy.mdx @@ -0,0 +1,12 @@ +- Open the **Create ACL Policy** page: + + 1. Open the GUI for your Vault instance. + + 1. Login under the namespace for the policy or select the namespace from the + selector at the bottom of the left-hand menu and re-authenticate. + + 1. Select **Policies** from the left-hand menu. + + 1. Select **ACL Policies** from the left-hand menu. + + 1. Click **Create ACL policy +** on the **ACL Policies** page. \ No newline at end of file diff --git a/website/content/partials/gui-page-instructions/create-group.mdx b/website/content/partials/gui-page-instructions/create-group.mdx new file mode 100644 index 000000000000..7a69681d9247 --- /dev/null +++ b/website/content/partials/gui-page-instructions/create-group.mdx @@ -0,0 +1,12 @@ +- Open the **Create Group** page: + + 1. Open the GUI for your Vault instance. + + 1. Login under the namespace for the group or select the namespace from the + selector at the bottom of the left-hand menu and re-authenticate. + + 1. Select **Access** from the left-hand menu. + + 1. Select **Groups** from the left-hand menu. + + 1. Click **Create group +** on the **Groups** page. \ No newline at end of file diff --git a/website/content/partials/gui-page-instructions/enable-authn-plugin.mdx b/website/content/partials/gui-page-instructions/enable-authn-plugin.mdx new file mode 100644 index 000000000000..b88cf8c877a0 --- /dev/null +++ b/website/content/partials/gui-page-instructions/enable-authn-plugin.mdx @@ -0,0 +1,12 @@ +- Open the **Enable an Authentication Method** page: + + 1. Open the GUI for your Vault instance. + + 1. Login under the namespace for the plugin or select the namespace from the + selector at the bottom of the left-hand menu and re-authenticate. + + 1. Select **Access** from the left-hand menu. + + 1. Select **Authentication Methods** from the left-hand menu. + + 1. Click **Enable new method +** on the **Authentication Methods** page. \ No newline at end of file diff --git a/website/content/partials/gui-page-instructions/enable-secrets-plugin.mdx b/website/content/partials/gui-page-instructions/enable-secrets-plugin.mdx new file mode 100644 index 000000000000..a6a220626107 --- /dev/null +++ b/website/content/partials/gui-page-instructions/enable-secrets-plugin.mdx @@ -0,0 +1,10 @@ +- Open the **Enable a Secrets Engine** page: + + 1. Open the GUI for your Vault instance. + + 1. Login under the namespace for the plugin or select the namespace from the + selector at the bottom of the left-hand menu and re-authenticate. + + 1. Select **Secrets Engines** from the left-hand menu. + + 1. Click **Enable new engine +** on the **Secrets Engines** page. \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index b1c960a29f2c..a73aba34bc07 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1903,12 +1903,47 @@ }, { "title": "SAML", - "path": "auth/saml", "badge": { "text": "ENTERPRISE", "type": "outlined", "color": "neutral" - } + }, + "routes": [ + { + "title": "Overview", + "path": "auth/saml" + }, + { + "title": "Use AD FS for SAML authN", + "path": "auth/saml/adfs" + }, + { + "title": "Link SAML AD groups to Vault", + "path": "auth/saml/link-vault-group-to-ad" + }, + { + "title": "Troubleshoot SAML+ADFS", + "routes": [ + { + "title": "Before you start", + "path": "auth/saml/troubleshoot-adfs" + }, + { + "title": "Bad mapping", + "path": "auth/saml/troubleshoot-adfs/bad-mapping" + }, + { + "title": "Invalid `BoundSubjects`", + "path": "auth/saml/troubleshoot-adfs/boundsubjects" + }, + { + "title": "AD FS event 320", + "path": "auth/saml/troubleshoot-adfs/adfs-event-320" + } + ] + + } + ] }, { "title": "TLS Certificates",