From cf6b087491243993f77fe614b8c78c43cdcb59bc Mon Sep 17 00:00:00 2001 From: rr-bw <102181210+rr-bw@users.noreply.github.com> Date: Wed, 25 Jun 2025 09:32:47 -0700 Subject: [PATCH] docs(password-management): [PM-18573] Document Master Password Management Flows (#15248) Adds documentation for our set/change password flows (master password management flows) --- .../src/auth/password-management/README.md | 216 ++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 libs/angular/src/auth/password-management/README.md diff --git a/libs/angular/src/auth/password-management/README.md b/libs/angular/src/auth/password-management/README.md new file mode 100644 index 00000000000..ca5a6355fcb --- /dev/null +++ b/libs/angular/src/auth/password-management/README.md @@ -0,0 +1,216 @@ +# Master Password Management Flows + +The Auth Team manages several components that allow a user to either: + +1. Set an initial master password +2. Change an existing master password + +This document maps all of our password management flows to the components that handle them. + +
+ +**Table of Contents** + +> - [The Base `InputPasswordComponent`](#the-base-inputpasswordcomponent) +> - [Set Initial Password Flows](#set-initial-password-flows) +> - [Change Password Flows](#change-password-flows) + +
+ +**Acronyms** + + + +
+ +## The Base `InputPasswordComponent` + +Central to our master password management flows is the base [InputPasswordComponent](https://components.bitwarden.com/?path=/docs/auth-input-password--docs), which is responsible for displaying the appropriate form fields in the UI, performing form validation, and generating appropriate cryptographic properties for each flow. This keeps our UI, validation, and key generation consistent across all master password management flows. + +
+ +## Set Initial Password Flows + + + + + + + + + + + + + + + + + + + + + + + + + +
FlowRoute
(on which user sets MP)		Component(s)
+
+ Account Registration +

+
    +
  1. Standard Flow
    2. +
    +
  2. Self Hosted Flow
    3. +
    +
  3. Email Invite Flows (🌐 web only)
    4. +
    +
+ 		/finish-signup + RegistrationFinishComponent +
+ - embeds InputPasswordComponent +
+ Trial Initiation (🌐 web only) + /trial-initiation or
/secrets-manager-trial-initiation		 + CompleteTrialInitiationComponent +
+ - embeds InputPasswordComponent +
+
+ Upon Authentication (an existing authed user) +

+
    +
  1. User JIT provisions* into an MPE org
    2. +
    +
  2. + User JIT provisions* into a TDE org with the "manage account recovery" permission +

    That is, the user was given this permission on invitation or by the time they JIT provision.

    +
    3. +
    +
  3. + TDE user permissions upgraded +

    TDE user authenticates after permissions were upgraded to include "manage account recovery".

    +
    4. +
    +
  4. + TDE offboarding +

    User authenticates after their org offboarded from TDE and is now a MPE org.

    +

    User must be on a trusted device to set MP, otherwise user must go through Account Recovery.

    +
    5. +
+ 		/set-initial-password + SetInitialPasswordComponent +
+ - embeds InputPasswordComponent +
+ +\* A note on JIT provisioned user flows: + +- Even though a JIT provisioned user is a brand-new user who was “just” created, we consider them to be an “existing authed user” _from the perspective of the set initial password flow_. This is because at the time they set their initial password, their account already exists in the database (before setting their password) and they have already authenticated via SSO. +- The same is not true in the _Account Registration_ flows above—that is, during account registration when a user reaches the `/finish-signup` or `/trial-initiation` page to set their initial password, their account does not yet exist in the database, and will only be created once they set an initial password. + +
+ +## Change Password Flows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlowRoute
(on which user changes MP)		Component(s)
+
+ Account Settings + (Docs) +
+ (🌐 web only) +

+

User changes MP via account settings.

+
+ 		+ /settings/security/password +
(security-routing.module.ts) + 		+ PasswordSettingsComponent +
- embeds ChangePasswordComponent +
- embeds InputPasswordComponent +
+
+ Upon Authentication +

+
    +
  1. + Login with non-compliant MP after email accept (🌐 web only) +

    User clicks an org email invite link and logs in with their MP that does not meet the org’s policy requirements.

    +
    2. +
    +
  2. + Login with non-compliant MP +

    Existing org user logs in with their MP that does not meet updated org policy requirements.

    +
    3. +
    +
  3. + Login after Account Recovery +

    User logs in after their MP was reset via Account Recovery.

    +
    4. +
+ 		/change-password + ChangePasswordComponent +
- embeds InputPasswordComponent +
+
+ Emergency Access Takeover + (Docs) +
+ (🌐 web only) +

+

Emergency access Grantee changes the MP for the Grantor.

+
+ 		Grantee opens dialog while on /settings/emergency-access + EmergencyAccessTakeoverDialogComponent +
- embeds InputPasswordComponent +
+
+ Account Recovery + (Docs) +
+ (🌐 web only) +

+

Org member with "manage account recovery" permission changes the MP for another org user via Account Recovery.

+
+ 		Org member opens dialog while on /organizations/{org-id}/members + AccountRecoveryDialogComponent +
- embeds InputPasswordComponent +