mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-05-05 20:36:26 +02:00
Code Issues Projects Releases Wiki Activity

Docs: GUI custom login feature (#30799)

Browse Source 
* 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>
This commit is contained in:
claire bontempo 2025-06-10 15:38:31 -07:00 committed by GitHub
parent c92d973923
commit 3701dcf3ca
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
16 changed files with 603 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/content/docs/auth/github.mdx
View File

@ -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.

2
website/content/docs/auth/jwt/index.mdx
View File

@ -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

2
website/content/docs/auth/ldap.mdx
View File

@ -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

2
website/content/docs/auth/okta.mdx
View File

@ -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.

2
website/content/docs/auth/radius.mdx
View File

@ -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.

2
website/content/docs/auth/saml/index.mdx
View File

@ -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.

2
website/content/docs/auth/token.mdx
View File

@ -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

2
website/content/docs/auth/userpass.mdx
View File

@ -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.

544
website/content/docs/ui/custom-login.mdx Normal file
View File

@ -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.
<Tip title="Make use of metadata">
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.
</Tip>
### Option 1: Configure a new plugin
<Tabs>
<Tab heading="CLI" group="cli">
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 <mount_path> \
-namespace <plugin_namespace> \
-description <visibility_note> \
-listing-visibility "unauth" \
<authentication_method>
```
For example:
<CodeBlockConfig hideClipboard>
```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/
```
</CodeBlockConfig>
1. Use `vault auth list` to verify the plugin configuration.
For example:
<CodeBlockConfig hideClipboard>
```shell-session
$ vault auth list -namespace=admin
Path Type Accessor Description Version
---- ---- -------- ----------- -------
gui/ldap/ ldap auth_ldap_c84b8cd2 Default GUI auth method n/a
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@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**.
</Tab>
<Tab heading="API" group="api">
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/<plugin_mount_path>
```
For example:
<CodeBlockConfig hideClipboard>
```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
```
</CodeBlockConfig>
`/sys/auth/{plugin_mount_path}` does not return data on success.
</Tab>
</Tabs>
### Option 2: Update an existing plugin
<Tabs>
<Tab heading="CLI" group="cli">
Use `vault auth tune` to update the `-listing-visibility` flag to `unauth`:
```shell-session
$ vault auth tune \
-namespace <plugin_namespace> \
-description <visibility_note> \
-listing-visibility "unauth" \
<mount_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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/
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@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**.
</Tab>
<Tab heading="API" group="api">
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/<plugin_mount_path>/tune
```
For example:
<CodeBlockConfig hideClipboard>
```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
```
</CodeBlockConfig>
`/sys/auth/{plugin_mount_path}/tune` does not return data on success.
</Tab>
</Tabs>
## 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`.
<Tip>
- To apply a login customization to the `root` namespace, pass an empty string for the namespace path.
For example, `namespace_path=""`.
</Tip>
<Tabs>
<Tab heading="CLI" group="cli">
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/<unique_rule_name> \
default_auth_type=<default_auth_type> \
backup_auth_types=<backup_auth_type> \
backup_auth_types=<backup_auth_type> \
disable_inheritance=<true_or_false> \
namespace_path=<namespace_where_the_rule_applies>
```
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:
<CodeBlockConfig hideClipboard>
```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
```
</CodeBlockConfig>
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:
<CodeBlockConfig hideClipboard>
```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/
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
<Note>
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.
</Note>
- 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.
</Tab>
<Tab heading="API" group="api">
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": "<namespace_where_the_rule_applies>",
"default_auth_type": "<default_auth_type>",
"disable_inheritance": <true_or_false>,
"backup_auth_types": [
<list_of_backup_auth_type>
]
}
```
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:
<CodeBlockConfig hideClipboard>
```json
{
"namespace_path": "dev",
"default_auth_type": "userpass",
"disable_inheritance": false,
"backup_auth_types": ["ldap", "token"]
}
```
</CodeBlockConfig>
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/<unique_rule_name>
```
For example, to create a new login rule called "dev-gui-login":
<CodeBlockConfig hideClipboard>
```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
```
</CodeBlockConfig>
`/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:
<CodeBlockConfig hideClipboard>
```shell-session
$ curl \
--request GET \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
${VAULT_ADDR}/v1/sys/config/ui/login/default-auth/dev-gui-login | jq
```
</CodeBlockConfig>
<br/>
<CodeBlockConfig hideClipboard>
```json
{
"data": {
"backup_auth_types": [
"ldap",
"token"
],
"default_auth_type": "userpass",
"disable_inheritance": false,
"namespace_path": "dev/"
},
}
```
</CodeBlockConfig>
</Tab>
</Tabs>
## Delete a login rule
<Tabs>
<Tab heading="CLI" group="cli">
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/<unique_rule_name>
```
For example:
<CodeBlockConfig hideClipboard>
```shell-session
$ vault delete sys/config/ui/login/default-auth/dev-gui-login
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
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.
</Tab>
<Tab heading="API" group="api">
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/<unique_rule_name>| jq
```
For example, to delete the rule "dev-gui-login":
<CodeBlockConfig hideClipboard>
```shell-session
$ curl \
--request DELETE \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
${VAULT_ADDR}/v1/sys/config/ui/login/default-auth/dev-gui-login | jq
```
</CodeBlockConfig>
</Tab>
</Tabs>
## 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` |
<Tip title="Copy the login link in the Vault GUI">
You can copy the Vault UI login link from the configuration details page of a given
mount in the Vault GUI.
</Tip>

4
website/content/partials/gui-instructions/enable-authn-plugin.mdx
View File

@ -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.

2
website/content/partials/gui-instructions/enable-secrets-plugin.mdx
View File

@ -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.

14
website/content/partials/gui-instructions/update-authn-plugin.mdx Normal file
View File

@ -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.

6
website/content/partials/tips/custom-authn.mdx Normal file
View File

@ -0,0 +1,6 @@
<Tip title="Supports custom GUI login">
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.
</Tip>

1
website/content/partials/ui/supported-login-methods-api-docs.mdx Normal file
View File

@ -0,0 +1 @@
`github`,`jwt`,`ldap`,`oidc`,`okta`,`radius`,`saml`,`token`, and `userpass`.

9
website/content/partials/ui/supported-login-methods.mdx Normal file
View File

@ -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) <EnterpriseAlert inline="true" />
- [Token](/vault/docs/auth/token)
- [Username and password](/vault/docs/auth/userpass)

11
website/data/docs-nav-data.json
View File

@ -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",