Docs: GUI custom login feature by hellobontempo · Pull Request #30799 · hashicorp/vault

hellobontempo · 2025-05-30T21:29:41Z

Description

Docs for feature merged by PR #30700

To view latest preview scroll all the way down and click the latest View deployment beside the Vercel bot below.

Most of the feature documentation is located at: /vault/docs/ui/custom-login but a tip has been added to supported auth methods as well, navigate to /vault/docs/auth/ldap to see in LDAP, for example:

TODO only if you're a HashiCorp employee

Backport Labels: If this fix needs to be backported, use the appropriate backport/ label that matches the desired release branch. Note that in the CE repo, the latest release branch will look like backport/x.x.x, but older release branches will be backport/ent/x.x.x+ent.
- LTS: If this fixes a critical security vulnerability or severity 1 bug, it will also need to be backported to the current LTS versions of Vault. To ensure this, use all available enterprise labels.
ENT Breakage: If this PR either 1) removes a public function OR 2) changes the signature
of a public function, even if that change is in a CE file, double check that
applying the patch for this PR to the ENT repo and running tests doesn't
break any tests. Sometimes ENT only tests rely on public functions in CE
files.
Jira: If this change has an associated Jira, it's referenced either
in the PR description, commit message, or branch name.
RFC: If this change has an associated RFC, please link it in the description.
ENT PR: If this change has an associated ENT PR, please link it in the
description. Also, make sure the changelog is in this PR, not in your ENT PR.

github-actions · 2025-05-30T21:30:29Z

CI Results:
All Go tests succeeded! ✅

github-actions · 2025-05-30T21:30:52Z

Build Results:
All builds succeeded! ✅

website/content/docs/ui/custom-login.mdx

finnstech · 2025-06-02T17:26:57Z

website/content/docs/ui/custom-login.mdx

+<Tip>
+
+- To apply a login customization to the `root` namespace, pass an empty string: `namespace=""`.
+


should this say root or admin (for HVD)?

No, root and admin are different. Maybe it's easier to think of root as a "lack" of a namespace because it's the top-most level. Passing admin would be necessary to set for the HVD admin namespace.

website/content/docs/ui/custom-login.mdx

finnstech · 2025-06-02T17:30:06Z

website/content/docs/ui/custom-login.mdx

+Default only            | Clients must use the selected authentication method during login
+Preferred only          | Clients must choose among the selected authentication methods during login
+Default and preferred   | Clients see the default method first but can toggle to view the preferred backup methods
+


"Clients see the default method first but can toggle to view the preferred backup methods"

to

"Clients see the default method first but can access the preferred methods as backup methods"

because the preferred methods live under the backup link if there's a default set, right?

Not sure exactly what you mean by "under" I used the word "toggle" because they are accessible by clicking "Sign in with other methods"

finnstech · 2025-06-02T17:30:51Z

website/content/docs/ui/custom-login.mdx

+
+If [listing visibility](/vault/api-docs/system/auth#listing_visibility-1) is unset or set to `hidden`, 
+the Vault GUI assumes the default mount path for login, which matches the method type.
+


Could you explain more about what exactly this means? Is there another doc to link to that goes into more detail? This is a complicated nuance

There are docs linked already (that's what the markdown syntax of [link text](href) means).

website/content/docs/ui/custom-login.mdx

hellobontempo · 2025-06-02T21:09:05Z

website/content/docs/ui/custom-login.mdx

+
+@include 'ui/supported-login-methods-api-docs.mdx'
+
+<Tip>


Does this tip make sense here? I wasn't really sure where to put it 🤔

It does, I think it makes sense here.

website/content/docs/ui/custom-login.mdx

Monkeychip · 2025-06-05T20:56:24Z

website/content/docs/ui/custom-login.mdx

+
+## Using a Direct Link
+
+The `?with=` query parameter can be used at any point to override login customizations. For example,


@deidraprado I'm tagging you because you’ll have the most insight into how users might interpret this. These are the docs for the custom login feature, and this specific part is about how you can override the default or backup method at any time if you don’t have something like “token” set as one. You and I had discussed this concern, so I wanted your take: any feedback on how this is worded, or do you think it’s clear enough for folks to understand?

LGTM! the only (very minor) thing that could be tweaked, is a link to:
https://developer.hashicorp.com/vault/api-docs/system/mounts#listing_visibility
instead of just having it in code
(the reason I say that is that I had no idea listing_visibility existed!)

Sounds good! Most people don't know it's a thing which is why I sprinkled links all over the place 😂 Easy enough to add here, too!

website/content/partials/ui/supported-login-methods-api-docs.mdx

…ontext

schavis · 2025-06-10T03:44:37Z

website/content/docs/ui/custom-login.mdx

+Login settings can be used to customize which methods display in the web UI login form by setting a default and back up login methods. 
+Available to be created via the CLI or HTTP API.


Suggested change

Login settings can be used to customize which methods display in the web UI login form by setting a default and back up login methods.

Available to be created via the CLI or HTTP API.

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.

Style correction: write in the active voice, write directly to the user in how-to guides

schavis · 2025-06-10T03:45:31Z

website/content/docs/ui/custom-login.mdx

+
+## Before you start 
+
+@include 'alerts/restricted-admin.mdx'


Suggested change

@include 'alerts/restricted-admin.mdx'

We should just list the permission requirements in the list instead of inserting an aside

schavis · 2025-06-10T03:46:45Z

website/content/docs/ui/custom-login.mdx

+@include 'alerts/restricted-admin.mdx'
+
+- **You must have Vault Enterprise 1.20.0 or higher installed.**
+- **You must have the appropriate permissions**:


Suggested change

- **You must have the appropriate permissions**:

- **You must have permission to operate from the `root` namespace**.

- **You must have the appropriate permissions**:

I almost wrote:

You must have permission to operate from the root or admin namespace."

But decided against it because I wanted to differentiate between HCP admin/ namespaces (administrative) and namespaces that just happened to be named admin

website/content/docs/ui/custom-login.mdx

schavis · 2025-06-10T04:25:12Z

website/content/docs/ui/custom-login.mdx

+</Tab>
+</Tabs>
+
+## Using a direct link


Suggested change

## Using a direct link

## Bypass authentication customization

website/content/docs/ui/custom-login.mdx

schavis · 2025-06-10T04:35:50Z

website/data/docs-nav-data.json

      },
      {
-        "title": "Custom Messages",
+        "title": "Custom login",


Suggested change

"title": "Custom login",

"title": "Customize GUI authN",

Whoops I missed this earlier - is this imperative? Also - what is the reasoning behind "AuthN"?

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

schavis and others added 6 commits May 13, 2025 17:01

saving because laptop is bad and should feel bad

618f93a

save

cf6c260

Merge branch 'main' into docs/gui-custom-login

c79c31d

make supported login types partial

05f3937

add api-docs partial

05f9534

update custom login docs

6972c27

hellobontempo requested review from a team as code owners May 30, 2025 21:29

hellobontempo added the docs label May 30, 2025

hellobontempo requested review from elliesterner and scellef May 30, 2025 21:29

hellobontempo added pr/no-changelog pr/no-milestone labels May 30, 2025

github-actions bot added the hashicorp-contributed-pr If the PR is HashiCorp (i.e. not-community) contributed label May 30, 2025

hellobontempo requested review from schavis and removed request for elliesterner and scellef May 30, 2025 21:31

reword tip?

4b014a2

vercel bot deployed to Preview May 30, 2025 21:43 View deployment

add delete section

ccb709d

vercel bot deployed to Preview May 30, 2025 22:19 View deployment

finnstech reviewed Jun 2, 2025

View reviewed changes

hellobontempo and others added 3 commits June 2, 2025 13:08

address feedback, update using a direct link section

cc4ac2c

Merge branch 'main' into docs/gui-custom-login

bcd5c5c

move tips down

0aa0422

hellobontempo commented Jun 2, 2025

View reviewed changes

hellobontempo added 2 commits June 2, 2025 14:15

remove table lines and see if that fixes build?

5524585

revert changes to custom-messages mdx

cb854bf

Monkeychip reviewed Jun 5, 2025

View reviewed changes

website/content/docs/ui/custom-login.mdx Outdated Show resolved Hide resolved

Monkeychip reviewed Jun 5, 2025

View reviewed changes

website/content/docs/ui/custom-login.mdx Outdated Show resolved Hide resolved

Monkeychip reviewed Jun 5, 2025

View reviewed changes

website/content/docs/ui/custom-login.mdx Outdated Show resolved Hide resolved

Monkeychip reviewed Jun 5, 2025

View reviewed changes

website/content/docs/ui/custom-login.mdx Outdated Show resolved Hide resolved

Monkeychip reviewed Jun 5, 2025

View reviewed changes

website/content/docs/ui/custom-login.mdx Outdated Show resolved Hide resolved

Monkeychip reviewed Jun 5, 2025

View reviewed changes

website/content/docs/ui/custom-login.mdx Outdated Show resolved Hide resolved

Monkeychip reviewed Jun 5, 2025

View reviewed changes

website/content/partials/ui/supported-login-methods-api-docs.mdx Show resolved Hide resolved

address feedback

3d30a7e

vercel bot deployed to Preview June 9, 2025 18:31 View deployment

hellobontempo added 3 commits June 9, 2025 14:56

use "settings" to match GUI verbiage

10fd245

missed a couple feedback comments

b235bef

add "single" and "multiple"

beb2a95

vercel bot deployed to Preview June 9, 2025 19:09 View deployment

fix link rendering

e4b4dd0

vercel bot deployed to Preview June 9, 2025 19:24 View deployment

fix namespace-path typos for namespace params referencing namespace c…

42c5741

…ontext

vercel bot deployed to Preview June 9, 2025 20:05 View deployment

hellobontempo added the backport/1.20.x label Jun 9, 2025

schavis requested changes Jun 10, 2025

View reviewed changes

address feedback

e4146bd

hellobontempo requested a review from schavis June 10, 2025 16:31

vercel bot deployed to Preview June 10, 2025 16:35 View deployment

schavis approved these changes Jun 10, 2025

View reviewed changes

hellobontempo merged commit 3701dcf into main Jun 10, 2025
33 of 34 checks passed

hellobontempo deleted the docs/gui-custom-login branch June 10, 2025 22:38

hc-github-team-secure-vault-core mentioned this pull request Jun 10, 2025

Backport of Docs: GUI custom login feature into release/1.20.x #30935

Merged

6 tasks

		<Tip>

		- To apply a login customization to the `root` namespace, pass an empty string: `namespace=""`.


		If [listing visibility](/vault/api-docs/system/auth#listing_visibility-1) is unset or set to `hidden`,
		the Vault GUI assumes the default mount path for login, which matches the method type.


		## Using a Direct Link

		The `?with=` query parameter can be used at any point to override login customizations. For example,

		Login settings can be used to customize which methods display in the web UI login form by setting a default and back up login methods.
		Available to be created via the CLI or HTTP API.

	- You must have the appropriate permissions:
	- You must have permission to operate from the `root` namespace.
	- You must have the appropriate permissions:

	## Using a direct link
	## Bypass authentication customization

Conversation

hellobontempo commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

TODO only if you're a HashiCorp employee

Uh oh!

github-actions bot commented May 30, 2025

Uh oh!

github-actions bot commented May 30, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hellobontempo Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hellobontempo Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hellobontempo Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

hellobontempo commented May 30, 2025 •

edited

Loading

hellobontempo Jun 2, 2025 •

edited

Loading

hellobontempo Jun 2, 2025 •

edited

Loading

hellobontempo Jun 10, 2025 •

edited

Loading