From 3701dcf3ca7d14691e78bbdf3b2d9c3a0bf0e550 Mon Sep 17 00:00:00 2001 From: claire bontempo <68122737+hellobontempo@users.noreply.github.com> Date: Tue, 10 Jun 2025 15:38:31 -0700 Subject: [PATCH] Docs: GUI custom login feature (#30799) * saving because laptop is bad and should feel bad * save * make supported login types partial * add api-docs partial * update custom login docs * reword tip? * add delete section * address feedback, update using a direct link section * move tips down * remove table lines and see if that fixes build? * revert changes to custom-messages mdx * add line break? * format fixes * empty commit again * check vercel? * add line break * update "namespace" to be "namespace_path" * reduce use of "preferred" * address feedback * use "settings" to match GUI verbiage * missed a couple feedback comments * add "single" and "multiple" * fix link rendering * fix namespace-path typos for namespace params referencing namespace context * address feedback --------- Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --- website/content/docs/auth/github.mdx | 2 + website/content/docs/auth/jwt/index.mdx | 2 + website/content/docs/auth/ldap.mdx | 2 + website/content/docs/auth/okta.mdx | 2 + website/content/docs/auth/radius.mdx | 2 + website/content/docs/auth/saml/index.mdx | 2 + website/content/docs/auth/token.mdx | 2 + website/content/docs/auth/userpass.mdx | 2 + website/content/docs/ui/custom-login.mdx | 544 ++++++++++++++++++ .../gui-instructions/enable-authn-plugin.mdx | 4 +- .../enable-secrets-plugin.mdx | 2 +- .../gui-instructions/update-authn-plugin.mdx | 14 + .../content/partials/tips/custom-authn.mdx | 6 + .../ui/supported-login-methods-api-docs.mdx | 1 + .../partials/ui/supported-login-methods.mdx | 9 + website/data/docs-nav-data.json | 11 +- 16 files changed, 603 insertions(+), 4 deletions(-) create mode 100644 website/content/docs/ui/custom-login.mdx create mode 100644 website/content/partials/gui-instructions/update-authn-plugin.mdx create mode 100644 website/content/partials/tips/custom-authn.mdx create mode 100644 website/content/partials/ui/supported-login-methods-api-docs.mdx create mode 100644 website/content/partials/ui/supported-login-methods.mdx diff --git a/website/content/docs/auth/github.mdx b/website/content/docs/auth/github.mdx index 7e5ca24ff6..772fee308b 100644 --- a/website/content/docs/auth/github.mdx +++ b/website/content/docs/auth/github.mdx @@ -6,6 +6,8 @@ description: The GitHub auth method allows authentication with Vault using GitHu # GitHub auth method +@include 'tips/custom-authn.mdx' + The `github` auth method can be used to authenticate with Vault using a GitHub personal access token. This method of authentication is most useful for humans: operators or developers using Vault directly via the CLI. diff --git a/website/content/docs/auth/jwt/index.mdx b/website/content/docs/auth/jwt/index.mdx index 8c15917b49..a2a678f9a2 100644 --- a/website/content/docs/auth/jwt/index.mdx +++ b/website/content/docs/auth/jwt/index.mdx @@ -9,6 +9,8 @@ description: >- @include 'x509-sha1-deprecation.mdx' +@include 'tips/custom-authn.mdx' + ~> **Note**: Starting in Vault 1.17, if the JWT in the authentication request contains an `aud` claim (typical case) the associated `bound_audiences` for the "jwt" role must **exactly** match at least one of the `aud` claims declared for diff --git a/website/content/docs/auth/ldap.mdx b/website/content/docs/auth/ldap.mdx index 4515412613..80be96a942 100644 --- a/website/content/docs/auth/ldap.mdx +++ b/website/content/docs/auth/ldap.mdx @@ -8,6 +8,8 @@ description: |- # LDAP auth method +@include 'tips/custom-authn.mdx' + @include 'x509-sha1-deprecation.mdx' The `ldap` auth method allows authentication using an existing LDAP diff --git a/website/content/docs/auth/okta.mdx b/website/content/docs/auth/okta.mdx index 798fac1c6a..49a1d90b66 100644 --- a/website/content/docs/auth/okta.mdx +++ b/website/content/docs/auth/okta.mdx @@ -8,6 +8,8 @@ description: |- # Okta auth method +@include 'tips/custom-authn.mdx' + The `okta` auth method allows authentication using Okta and user/password credentials. This allows Vault to be integrated into environments using Okta. diff --git a/website/content/docs/auth/radius.mdx b/website/content/docs/auth/radius.mdx index f535cf588e..5a4da9749f 100644 --- a/website/content/docs/auth/radius.mdx +++ b/website/content/docs/auth/radius.mdx @@ -8,6 +8,8 @@ description: |- # RADIUS auth method +@include 'tips/custom-authn.mdx' + The `radius` auth method allows users to authenticate with Vault using an existing RADIUS server that accepts the PAP authentication scheme. diff --git a/website/content/docs/auth/saml/index.mdx b/website/content/docs/auth/saml/index.mdx index 73ff1e102d..7278c7963c 100644 --- a/website/content/docs/auth/saml/index.mdx +++ b/website/content/docs/auth/saml/index.mdx @@ -10,6 +10,8 @@ description: >- @include 'alerts/enterprise-and-hcp.mdx' +@include 'tips/custom-authn.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. Authentication is suited for human users by requiring interaction with a web browser. diff --git a/website/content/docs/auth/token.mdx b/website/content/docs/auth/token.mdx index feaf4f1c43..a6f58d3f85 100644 --- a/website/content/docs/auth/token.mdx +++ b/website/content/docs/auth/token.mdx @@ -6,6 +6,8 @@ description: The token store auth method is used to authenticate using tokens. # Token auth method +@include 'tips/custom-authn.mdx' + ~> **NOTE:** The Token auth method cannot be configured with Vault's built-in [Login MFA](/vault/docs/auth/login-mfa) feature. The `token` auth method is built-in and automatically available at `/auth/token`. It diff --git a/website/content/docs/auth/userpass.mdx b/website/content/docs/auth/userpass.mdx index fb6edb7259..1cd9223111 100644 --- a/website/content/docs/auth/userpass.mdx +++ b/website/content/docs/auth/userpass.mdx @@ -8,6 +8,8 @@ description: >- # Userpass auth method +@include 'tips/custom-authn.mdx' + The `userpass` auth method allows users to authenticate with Vault using a username and password combination. diff --git a/website/content/docs/ui/custom-login.mdx b/website/content/docs/ui/custom-login.mdx new file mode 100644 index 0000000000..9077a26639 --- /dev/null +++ b/website/content/docs/ui/custom-login.mdx @@ -0,0 +1,544 @@ +--- +layout: docs +page_title: Manage custom login settings +description: >- + Use custom login flows to control how clients can authenticate to Vault + through the GUI. +--- + +# Manage custom login settings for the Vault GUI + +@include 'alerts/enterprise-and-hcp.mdx' + +Use can use the Vault CLI or API to customize a default and one or more back up +login method for the Vault GUI login form. + +## Before you start + +- **You must have Vault Enterprise 1.20.0 or higher installed.** +- **You must have permission to operate from the `root` or administrative namespace**. +- **You must have the appropriate permissions**: + - To **create login settings**, you must have `create` permission for the [`sys/config/ui/login/default-auth`](/vault/api-docs/system/config-ui-login-default-auth) endpoint. + - To **edit login settings**, you must have `update` permission for the [`sys/config/ui/login/default-auth`](/vault/api-docs/system/config-ui-login-default-auth) endpoint. + - To **delete login settings**, you must have `delete` permission for the [`sys/config/ui/login/default-auth`](/vault/api-docs/system/config-ui-login-default-auth) endpoint. + +## Step 1: Select your authentication method + +Select a supported authentication method for your default and backup methods. +You can choose a single default authentication method, multiple backup +authentication methods, or both. + +@include 'ui/supported-login-methods.mdx' + +Configuration | Result +----------------------- | ------ +Default only | Users see only the selected authentication method during login. +Backup(s) only | Users see only from the selected authentication method(s) during login. +Default and backup(s) | Users see the default method first but can access the backup methods as alternate options. + + +## Step 2: Make the authentication method visible to the GUI. (Optional, but recommended) + +Set the [listing visibility](/vault/api-docs/system/auth#listing_visibility-1) of your authentication +plugin to `unauth` to ensure the Vault GUI uses the correct login URL to use for authentication. +This also simplifies the customized login form by removing the "Advanced settings" toggle. + +Login customizations specify authentication **types**, not specific plugin paths. +As a result, Vault assumes you mounted your login method at the default +[path](/vault/api-docs/system/auth#path) for that auth type. For example, the +default path for the LDAP authentication method is `ldap`. + +To use an authentication plugin mounted on a custom path, you must set +`listing_visibility` to `unauth` in the plugin configuration. Otherwise, Vault +cannot display the authentication option and users must manually input the custom +path to authenticate through the customized login view. + + + +Set the [mount description field](/vault/api-docs/system/auth#description) to +clearly indicate that the mount is a default or backup login method for the +Vault GUI. + + + +### Option 1: Configure a new plugin + + + + +1. Use `vault auth enable` to establish a new instance of the authentication + plugin and set the `-listing-visibility` flag to `unauth`: + + ```shell-session + $ vault auth enable \ + -path \ + -namespace \ + -description \ + -listing-visibility "unauth" \ + + ``` + + For example: + + + + ```shell-session + $ vault auth enable \ + -path gui/ldap \ + -namespace admin \ + -description "Default GUI auth method" \ + -listing-visibility "unauth" \ + ldap + + Success! Enabled ldap auth method at: gui/ldap/ + ``` + + + +1. Use `vault auth list` to verify the plugin configuration. + + For example: + + + + ```shell-session + $ vault auth list -namespace=admin + + Path Type Accessor Description Version + ---- ---- -------- ----------- ------- + gui/ldap/ ldap auth_ldap_c84b8cd2 Default GUI auth method n/a + ``` + + + + + + +@include 'gui-instructions/enable-authn-plugin.mdx' + +- Select the desired plugin. +- Optional: Enter a unique path for the plugin. By default, Vault uses the plugin type as the mount path. +- Enable the **Use as preferred UI login method** toggle. +- Optional: Update the **Description** to help users determine which authentication method they should use. +- Provide any other relevant configuration information for the plugin. +- Click **Enable method**. + + + + +1. Create a JSON file with the configuration information for your authentication + plugin. Use the `config` field to set the `listing_visibility` parameter to + `unauth`. + + For example: + + ```json + { + "description": "Default GUI auth method", + "config": { + "listing_visibility": "unauth" + } + } + ``` + +1. Make a `POST` call to + [`/sys/auth/{plugin_mount_path}`](/vault/api-docs/system/auth#enable-auth-method) + with the JSON data: + + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \ + --data @data.json \ + ${VAULT_ADDR}/v1/sys/auth/ + ``` + + For example: + + + + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \ + --data @data.json \ + ${VAULT_ADDR}/v1/sys/auth/gui/ldap | jq + ``` + + + + `/sys/auth/{plugin_mount_path}` does not return data on success. + + + + +### Option 2: Update an existing plugin + + + + +Use `vault auth tune` to update the `-listing-visibility` flag to `unauth`: + +```shell-session +$ vault auth tune \ + -namespace \ + -description \ + -listing-visibility "unauth" \ + +``` + +For example: + + + +```shell-session +$ vault auth tune \ + -namespace admin \ + -description "Default GUI auth method" \ + -listing-visibility "unauth" \ + gui/ldap + +Success! Tuned the auth method at: gui/ldap/ +``` + + + + + + +@include 'gui-instructions/update-authn-plugin.mdx' + +- Click **Configure >**. +- Enable the **Use as preferred UI login method** toggle. +- Optional: Update **Description** to help users determine which authentication method they should use. +- Click **Update options**. + + + + +1. Create a JSON file with the updated configuration information for your + authentication plugin and set the `listing_visibility` parameter to `unauth`. + + For example: + + ```json + { + "description": "Default GUI auth method", + "listing_visibility": "unauth" + } + ``` + +1. Make a `POST` call to + [`/sys/auth/{plugin_mount_path}/tune`](/vault/api-docs/system/auth#tune-auth-method) + with the JSON data: + + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \ + --data @data.json \ + ${VAULT_ADDR}/v1/sys/auth//tune + ``` + + For example: + + + + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \ + --data @data.json \ + ${VAULT_ADDR}/v1/sys/auth/gui/userpass/tune | jq + ``` + + + + `/sys/auth/{plugin_mount_path}/tune` does not return data on success. + + + + +## Step 3: Set your default and backup authentication methods + +By default, namespaces inherit login settings from their parent unless you explicitly disable inheritance. +To scope a login setting to a specific namespace, set: `disable_inheritance=true`. + + + +- To apply a login customization to the `root` namespace, pass an empty string for the namespace path. +For example, `namespace_path=""`. + + + + + + +1. Use `vault write` with the + [`sys/config/ui/login/default-auth`](/vault/api-docs/system/config-ui-login-default-auth) + endpoint to set the default and/or backup GUI authentication method(s). The following types + are supported: + + @include 'ui/supported-login-methods-api-docs.mdx' + + ```shell-session + $ vault write sys/config/ui/login/default-auth/ \ + default_auth_type= \ + backup_auth_types= \ + backup_auth_types= \ + disable_inheritance= \ + namespace_path= + ``` + + For example, to customize the login options for the `dev` namespace and set + `userpass` as the default authentication method with `ldap` and `token` + as additional, backup options: + + + + ```shell-session + $ vault write sys/config/ui/login/default-auth/dev-gui-login \ + default_auth_type=userpass \ + backup_auth_types=ldap \ + backup_auth_types=token \ + disable_inheritance=false \ + namespace_path=dev + ``` + + + +1. Use `vault read` with the + [`sys/config/ui/login/default-auth/{rule_name}`](/vault/api-docs/system/config-ui-login-default-auth) + endpoint and the new rule name to verify the login configuration. + + For example: + + + + ```shell-session + $ vault read sys/config/ui/login/default-auth/dev-gui-login + + Key Value + --- ----- + backup_auth_types [ldap token] + default_auth_type userpass + disable_inheritance false + namespace_path dev/ + ``` + + + + + + + +To encourage best practices, Vault limits customization configuration to the +CLI or API, but you can view or delete login settings through the Vault GUI. + + +- Navigate to the **Settings** section in the Vault GUI sidebar. +- Select **UI Login Settings**. +- Click on a customization entry from the list of existing login settings to view the rule details. + + + + +1. Create a JSON file with a new custom login configuration rule that specifies your + default and/or backup GUI authentication methods. The following types + are supported: + + @include 'ui/supported-login-methods-api-docs.mdx' + + ```json + { + "namespace_path": "", + "default_auth_type": "", + "disable_inheritance": , + "backup_auth_types": [ + + ] + } + ``` + + For example, to customize the login options for the `dev` namespace and set + `userpass` as the default authentication method with `ldap` and `token` + as additional, backup options: + + + + ```json + { + "namespace_path": "dev", + "default_auth_type": "userpass", + "disable_inheritance": false, + "backup_auth_types": ["ldap", "token"] + } + ``` + + + +1. Make a `POST` call to + [`sys/config/ui/login/default-auth/{rule_name}`](/vault/api-docs/system/config-ui-login-default-auth) + with the JSON data: + + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @data.json \ + ${VAULT_ADDR}/v1/sys/config/ui/login/default-auth/ + ``` + + For example, to create a new login rule called "dev-gui-login": + + + + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @data.json \ + ${VAULT_ADDR}/v1/sys/config/ui/login/default-auth/dev-gui-login | jq + ``` + + + + `/sys/config/ui/login/default-auth/{rule_name}` does not return data on success. + +1. Make a `GET` call to + [`sys/config/ui/login/default-auth/{rule_name}`](/vault/api-docs/system/config-ui-login-default-auth) + with the new rule name to verify the login configuration. + + For example: + + + + ```shell-session + $ curl \ + --request GET \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1/sys/config/ui/login/default-auth/dev-gui-login | jq + ``` + + +
+ + + ```json + { + "data": { + "backup_auth_types": [ + "ldap", + "token" + ], + "default_auth_type": "userpass", + "disable_inheritance": false, + "namespace_path": "dev/" + }, + } + ``` + + + + + + + +## Delete a login rule + + + + +Use `vault delete` with the +[`sys/config/ui/login/default-auth/{rule_name}`](/vault/api-docs/system/config-ui-login-default-auth) +endpoint and rule name to delete a login setting for a namespace. + +```shell-session +$ vault delete sys/config/ui/login/default-auth/ +``` + +For example: + + + +```shell-session +$ vault delete sys/config/ui/login/default-auth/dev-gui-login +``` + + + + + + +You can delete a login rule in two places from the **UI Login Settings** page. + +**From the additional options menu for the customization**: + +1. Find the login rule you want to delete. +1. Open the additional options menu by clicking the three dots. +1. Select **Delete** from the options menu to bring up the delete confirmation modal. + +**From the customization details page**: + +1. Find the login rule you want to delete. +1. Select the rule to open the login settings details page. +1. Click **Delete Rule** to bring up the delete confirmation modal. + + + + +Make a `DELETE` call to the +[`sys/config/ui/login/default-auth/{rule_name}`](/vault/api-docs/system/config-ui-login-default-auth) +endpoint to delete a login setting for a namespace. + +```shell-session +$ curl \ + --request DELETE \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + http://127.0.0.1:8200/v1/sys/config/ui/login/default-auth/| jq +``` + +For example, to delete the rule "dev-gui-login": + + + +```shell-session +$ curl \ + --request DELETE \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1/sys/config/ui/login/default-auth/dev-gui-login | jq +``` + + + + + + +## Bypass custom login settings + +Clients can bypass login customization using the `?with=` query parameter with the Vault GUI URL and either specify +an authentication method [type](/vault/api-docs/system/auth#type) or a plugin mount path whose +[listing_visibility](/vault/api-docs/system/auth#listing_visibility-1) is set to `unauth`. + +| Namespace | AuthN mount path | UI Login URL (appended to `${VAULT_ADDR}`) | +| ------------- | ------------------- | ------------------------------------------------- | +| `root` | default (`ldap`) | `/ui/vault/auth?with=ldap%2F` | +| `root` | custom (`gui/ldap`) | `/ui/vault/auth?with=gui%2Fldap%2F` | +| child (`dev`) | custom (`gui/ldap`) | `/ui/vault/auth?namespace=dev&with=gui%2Fldap%2F` | + +| Namespace | Auth method type | UI Login URL (appended to `${VAULT_ADDR}`) | +| ------------- | ---------------- | -------------------------------------------- | +| `root` | `token` | `/ui/vault/auth?with=token` | +| child (`dev`) | `userpass` | `/ui/vault/auth?namespace=dev&with=userpass` | + + + + +You can copy the Vault UI login link from the configuration details page of a given +mount in the Vault GUI. + + \ No newline at end of file diff --git a/website/content/partials/gui-instructions/enable-authn-plugin.mdx b/website/content/partials/gui-instructions/enable-authn-plugin.mdx index b88cf8c877..c8b1160575 100644 --- a/website/content/partials/gui-instructions/enable-authn-plugin.mdx +++ b/website/content/partials/gui-instructions/enable-authn-plugin.mdx @@ -2,8 +2,8 @@ 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. Log in under the namespace for the plugin or select the namespace from the + selector at the bottom of the left-hand menu. 1. Select **Access** from the left-hand menu. diff --git a/website/content/partials/gui-instructions/enable-secrets-plugin.mdx b/website/content/partials/gui-instructions/enable-secrets-plugin.mdx index a6a2206261..59b546c252 100644 --- a/website/content/partials/gui-instructions/enable-secrets-plugin.mdx +++ b/website/content/partials/gui-instructions/enable-secrets-plugin.mdx @@ -2,7 +2,7 @@ 1. Open the GUI for your Vault instance. - 1. Login under the namespace for the plugin or select the namespace from the + 1. Log in 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. diff --git a/website/content/partials/gui-instructions/update-authn-plugin.mdx b/website/content/partials/gui-instructions/update-authn-plugin.mdx new file mode 100644 index 0000000000..bfba20484e --- /dev/null +++ b/website/content/partials/gui-instructions/update-authn-plugin.mdx @@ -0,0 +1,14 @@ +- Open the plugin **Configure** page: + + 1. Open the GUI for your Vault instance. + + 1. Log in under the namespace for the plugin or select the namespace from the + selector at the bottom of the left-hand menu. + + 1. Select **Access** from the left-hand menu. + + 1. Select **Authentication Methods** from the left-hand menu. + + 1. Select the plugin you want to update. + + 1. Select the **Configuration** tab. \ No newline at end of file diff --git a/website/content/partials/tips/custom-authn.mdx b/website/content/partials/tips/custom-authn.mdx new file mode 100644 index 0000000000..c48523431e --- /dev/null +++ b/website/content/partials/tips/custom-authn.mdx @@ -0,0 +1,6 @@ + + +This method can be chosen as a default or backup login method for Vault Enterprise GUI users. +Refer to the [Manage custom login options](/vault/docs/ui/custom-login) guide for more details. + + \ No newline at end of file diff --git a/website/content/partials/ui/supported-login-methods-api-docs.mdx b/website/content/partials/ui/supported-login-methods-api-docs.mdx new file mode 100644 index 0000000000..72e5aaab5c --- /dev/null +++ b/website/content/partials/ui/supported-login-methods-api-docs.mdx @@ -0,0 +1 @@ +`github`,`jwt`,`ldap`,`oidc`,`okta`,`radius`,`saml`,`token`, and `userpass`. \ No newline at end of file diff --git a/website/content/partials/ui/supported-login-methods.mdx b/website/content/partials/ui/supported-login-methods.mdx new file mode 100644 index 0000000000..47dfae5017 --- /dev/null +++ b/website/content/partials/ui/supported-login-methods.mdx @@ -0,0 +1,9 @@ +- [GitHub](/vault/docs/auth/github) +- [JWT](/vault/docs/auth/jwt) +- [LDAP](/vault/docs/auth/ldap) +- [OIDC](/vault/docs/auth/jwt/oidc-providers) +- [Okta](/vault/docs/auth/okta) +- [RADIUS](/vault/docs/auth/radius) +- [SAML](/vault/docs/auth/saml) +- [Token](/vault/docs/auth/token) +- [Username and password](/vault/docs/auth/userpass) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 1882ee5542..b3ea945521 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1641,7 +1641,16 @@ "path": "ui/browser-support" }, { - "title": "Custom Messages", + "title": "Custom login", + "path": "ui/custom-login", + "badge": { + "text": "ENT", + "type": "filled", + "color": "neutral" + } + }, + { + "title": "Custom messages", "path": "ui/custom-messages", "badge": { "text": "ENT",