1.21 - RC Add MFA TOTP Self-Enroll Docs

[hellobontempo]

1. Adds self-enroll section below "Configuring MFA Methods"

2. Adds subsections for self-enroll vs admin managed TOTP setups to the "Time-based One-time Password (TOTP)" section

[github-actions]

Vercel Previews Deployed

Name	Status	Preview	Updated (UTC)
Dev Portal	🔄 Building (Inspect)	---	---
Unified Docs API	✅ Ready (Inspect)	Visit Preview	Tue Oct 7 23:28:54 UTC 2025

[hellobontempo]

Do you think it's worth mentioning somewhere that the UI only enters the self-enroll workflow if only one enforcement is configured because that's when /validate returns self_enrollment_enabled: true? Maybe in the section Configure the TOTP Method.

Technically, users could circumvent this by manually requesting self-enroll via curl, right? Though, I'm not sure it's worth going into that level of detail...

@kubawi

[kubawi]

Very good point, I completely forgot about that. Yes, I think we should mention it wherever we can as long as this makes sense, to avoid users being confused. Maybe it would make sense to add screenshots of the whole flow somewhere? 🤔

[hellobontempo]

Yeah - I was holding off on screenshots until I heard back from the education team (since I just took a best guess at where to add docs 😂 )

But yes - @schavis - do you have thoughts on:

1. If and where we should add screenshots to walkthrough the UI login flow?
2. Where we should callout that even if enable_self_enrollment is configured to true the UI will only enter self-enroll if only one MFA login enforcement is configured.

[schavis]

I'm not sure what happened to my original reply from last night =\

If and where we should add screenshots to walkthrough the UI login flow?

In general, we try to limit the number of screenshots due to the maintenance burden. Is there a "hero" screenshot we can reference to help folks orient themselves in the GUI?

Where we should callout that even if enable_self_enrollment is configured to true

Since we're essentially calling out a configuration gotcha, I'd recommend adding it as part of the instructions under "Option 1: Configure TOTP for self-enrollment".

[hellobontempo]

The QR code appears after the user logs in, so I'm not sure that it would provide much of a benefit. I'm thinking we can add it later, if we think it'd be helpful, but for now I don't think it's necessary.

I'll add below!

[schavis]

Suggested change

	Use the TOTP `method_id` and the `entity_id` of the associated user to generate a QR code.
	Use the TOTP `method_id` and an `entity_id` from a successful MFA login to
	generate a QR code. For example:

Edited to match previous suggestion

[hellobontempo]

I was confused at the original wording of this to be honest! I think what's confusing to me is entity_id is generated for a user after they log in the first time, but it's not from a successful MFA login- since that can't happen until the QR code is generated. @kubawi - what's your interpretation of the original wording? This is for the pre self-enroll workflow.

The entity_id is just to determine who the QR code (MFA secret) needs to be generated for. Reworded for clarity

[kubawi]

Yes, you're right (that of the associated user) is the correct wording. You do need an ID of an existing entity to create a TOTP credential, but that entity doesn't have to come from a successful MFA login, it can come from anywhere.

If you're interested in more details, here is my understanding of how auth and entities work, but I am not an identity expert 😄

You can technically have an entity before a first login on an auth method. Entities are used as a one central object to represent all of the user's identities across the auth methods, so you could have a single entity created for you first, then have it aliased to identities in GitHub and LDAP, for example. Aliases are what we use to map identities from the auth providers (e.g. your LDAP user and your GitHub user) to the single identity representation that is an Entity.

Here are some of our docs on the topic:

• https://developer.hashicorp.com/vault/docs/concepts/identity#entities-and-aliases
• https://developer.hashicorp.com/vault/docs/concepts/identity#implicit-entities

The MFA-enforced login attempt response deliberately does not contain any entity info, even though internally we already have an entity created for the user at that point, which highlights the real value of this feature, BTW. Without it, if you're onboarding users in LDAP (or any other auth system), they don't have entities before the first login attempt, so you either need to preemptively create them for any user (big management overhead) or make sure that everyone logs in before you enforce MFA (a bit of a security risk, and this approach does not account for new users joining).

[hellobontempo]

Awesome, thanks for the detailed response! That was my understanding. This particular doc seemed to be guiding users to use the generated entity_id after login, so I was following that. (Apparently I opened a can of worms, because I was just trying to fix the misspelled "sucessful" typo 🥲 )

[hellobontempo]

Increased this header size so it is now included in the page table of contents

[hellobontempo]

Added this, contents is copy/pasted from the sample output above

[github-actions]

Broken Link Checker

No broken links found! 🎉