Vault
Manage custom login settings for the Vault GUI
Enterprise
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 thesys/config/ui/login/default-auth
endpoint. - To edit login settings, you must have
update
permission for thesys/config/ui/login/default-auth
endpoint. - To delete login settings, you must have
delete
permission for thesys/config/ui/login/default-auth
endpoint.
- To create login settings, you must have
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 tounauth
:$ 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
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/
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 thesys/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
, anduserpass
.$ 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 setuserpass
as the default authentication method withldap
andtoken
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 thesys/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/
Delete a login rule
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
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 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.