Manage custom login settings | Vault

Appropriate Vault Enterprise license or HCP Vault Dedicated cluster required.

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 endpoint.
- To edit login settings, you must have update permission for the sys/config/ui/login/default-auth endpoint.
- To delete login settings, you must have delete permission for the sys/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.

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

Make use of metadata

Set the mount description field to clearly indicate that the mount is a default or backup login method for the Vault GUI.

Option 1: Configure a new plugin

Use vault auth enable to establish a new instance of the authentication plugin and set the -listing-visibility flag to unauth:

$ vault auth enable              \
  -path <mount_path>             \
  -namespace <plugin_namespace>  \
  -description <visibility_note> \
  -listing-visibility "unauth"   \
  <authentication_method>

For example:

$ 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/

Use vault auth list to verify the plugin configuration.

For example:

$ vault auth list -namespace=admin

Path         Type        Accessor                  Description                Version
----         ----        --------                  -----------                -------
gui/ldap/    ldap        auth_ldap_c84b8cd2        Default GUI auth method    n/a

Open the Enable an Authentication Method page:
1. Open the GUI for your Vault instance.
2. Log in under the namespace for the plugin or select the namespace from the selector at the bottom of the left-hand menu.
3. Select Access from the left-hand menu.
4. Select Authentication Methods from the left-hand menu.
5. Click Enable new method + on the Authentication Methods page.

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.

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:
```
{
  "description": "Default GUI auth method",
  "config": {
    "listing_visibility": "unauth"
  }
}
```

Make a POST call to /sys/auth/{plugin_mount_path} with the JSON data:

$ 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:

$ 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:

$ vault auth tune              \
  -namespace <plugin_namespace>  \
  -description <visibility_note> \
  -listing-visibility "unauth"   \
  <mount_path>

For example:

$ vault auth tune                        \
  -namespace admin                       \
  -description "Default GUI auth method" \
  -listing-visibility "unauth"           \
  gui/ldap

Success! Tuned the auth method at: gui/ldap/

Open the plugin Configure page:
1. Open the GUI for your Vault instance.
2. Log in under the namespace for the plugin or select the namespace from the selector at the bottom of the left-hand menu.
3. Select Access from the left-hand menu.
4. Select Authentication Methods from the left-hand menu.
5. Select the plugin you want to update.
6. Select the Configuration tab.

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.

Create a JSON file with the updated configuration information for your authentication plugin and set the listing_visibility parameter to unauth.
For example:
```
{
  "description": "Default GUI auth method",
  "listing_visibility": "unauth"
}
```

Make a POST call to /sys/auth/{plugin_mount_path}/tune with the JSON data:

$ 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:

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

Tip

To apply a login customization to the root namespace, pass an empty string for the namespace path. For example, namespace_path="".

Use vault write with the sys/config/ui/login/default-auth endpoint to set the default and/or backup GUI authentication method(s). The following types are supported:

github,jwt,ldap,oidc,okta,radius,saml,token, and userpass.

$ 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:

$ 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

Use vault read with the sys/config/ui/login/default-auth/{rule_name} endpoint and the new rule name to verify the login configuration.

For example:

$ 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/

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:

github,jwt,ldap,oidc,okta,radius,saml,token, and userpass.

{
  "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:

{
  "namespace_path": "dev",
  "default_auth_type": "userpass",
  "disable_inheritance": false,
  "backup_auth_types": ["ldap", "token"]
}

Make a POST call to sys/config/ui/login/default-auth/{rule_name} with the JSON data:

$ 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":

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

Make a GET call to sys/config/ui/login/default-auth/{rule_name} with the new rule name to verify the login configuration.

For example:

$ curl                                               \
    --request GET                                    \
    --header "X-Vault-Token: ${VAULT_TOKEN}"         \
    ${VAULT_ADDR}/v1/sys/config/ui/login/default-auth/dev-gui-login | jq

{
  "data": {
    "backup_auth_types": [
      "ldap",
      "token"
    ],
    "default_auth_type": "userpass",
    "disable_inheritance": false,
    "namespace_path": "dev/"
  },
}

Use vault delete with the sys/config/ui/login/default-auth/{rule_name} endpoint and rule name to delete a login setting for a namespace.

$ vault delete sys/config/ui/login/default-auth/<unique_rule_name>

For example:

$ 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:

Find the login rule you want to delete.
Open the additional options menu by clicking the three dots.
Select Delete from the options menu to bring up the delete confirmation modal.

From the customization details page:

Find the login rule you want to delete.
Select the rule to open the login settings details page.
Click Delete Rule to bring up the delete confirmation modal.

Make a DELETE call to the sys/config/ui/login/default-auth/{rule_name} endpoint to delete a login setting for a namespace.

$ 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":

$ curl                                               \
    --request DELETE                                 \
    --header "X-Vault-Token: ${VAULT_TOKEN}"         \
    ${VAULT_ADDR}/v1/sys/config/ui/login/default-auth/dev-gui-login | jq

Clients can bypass login customization using the ?with= query parameter with the Vault GUI URL and either specify an authentication method type or a plugin mount path whose listing_visibility 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`

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.

Manage custom login settings for the Vault GUI

Before you start

Step 1: Select your authentication method

Step 2: Make the authentication method visible to the GUI. (Optional, but recommended)

Option 1: Configure a new plugin

Option 2: Update an existing plugin

Step 3: Set your default and backup authentication methods

Delete a login rule

Bypass custom login settings