Email 2FA verification for admins logging into Fleet w/o SSO

[noahtalerman]

Goal

User story
As a security team who is checking out the IT team's new tool,
I want us to be able to use email verification for our “break glass” account in Fleet
so that I can feel confident that we're following security best practices.

Objective

Customer promises + renewal requests

Original request

• Two-factor authentication for admins logging into Fleet w/o SSO #5478

Context

• Product designer: @randy-fleet

Changes

Includes updates to creating and editing users, the invitation flow, and introduces a new (optional) magic link (2FA) experience.

Product

• UI changes: Wireframes are in Figma here
• REST API changes: Documentation PR
• CLI (fleetctl) usage changes: Add a new flag to the fleetctl user create command: 2fa - Enable login two-factor authentication (default: false)
• Fleet's agent (fleetd) changes: No changes.
• Changes to paid features or tiers: Fleet Premium only.
  • @noahtalerman: Accidentally committed directly to the 4.59 reference docs branch: 42b279f
• YAML changes: No changes
• Activity changes: No changes
• Permissions changes: No changes
• Other reference documentation changes: No changes
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed: https://github.com/fleetdm/confidential/issues/9205

Engineering

• Feature guide changes: Split into Non-SSO MFA - Docs #23910
  • UPDATE: @noahtalerman: Best practice guide updates here: SSO guide: best practice for email 2FA #25005
• Database schema migrations: Migration required for new table, invite and user updates
• Frontend - implement as in Figma
• Backend - implement the API change as in the above PR
• Test-plan - To be created by the DRI engineer and approved by QA person

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

• Risk level: Low

Automated tests to write

• Migration test

Integration

Fleet Free

• Pre-create MFA enabled user
• Invalid MFA token fails
• Login fails without MFA supported flag
• Login succeeds with MFA supported flag (test through access, check activity log)
• MFA redeem fails if token is expired
• Can remove MFA from user
• User can log in without MFA

License failures:

• MFA on create invite
• Create invite with no MFA, update to MFA
• Create user with MFA
• Update user to include MFA

Fleet Premium

Skipping admin-created tests because we don't have fully set up mailer in integration test suites.

• Invited MFA enabled user fails with SSO
• Create invite with SSO and no MFA, update to turn on MFA and off SSO (should succeed)
• Invited MFA enabled user (from above) succeeds

Service

Session

• Login + session create endpoint (test via endpoint for coverage): MFA with and without verification email support (success cases)
• CompleteMFA: failure, success

User

• CreateUser: fail if MFA and SSO
• CreateUser: fail if MFA and can't send email
• CreateUser: fail if MFA and Free
• CreateUser: succeed if MFA and Premium with mailer
• ModifyUser: fail if MFA and SSO
• ModifyUser: fail if MFA and can't send email
• ModifyUser: fail if turning on MFA and Free
• ModifyUser: allow keeping MFA on if Free if MFA is already on
• ModifyUser: succeed if MFA and Premium with mailer

Invite

• InviteNewUser: fail if MFA and SSO
• InviteNewUser: fail if MFA and Free
• InviteNewUser: succeed if MFA and Premium
• UpdateInvite: fail if MFA and SSO
• UpdateInvite: fail if MFA and Free
• UpdateInvite: succeed if MFA and Premium

Data store

• Session
• Invite: ensure MFA save/load works on create/update
• User: ensure MFA save/load works on create/update

Other tests

• Mail: CanSendEmail

Manual testing steps (checked when QA'd by engineer)

fleetctl

• User create fails with --mfa and --sso
• User create succeeds with --mfa
• User gets a reasonable error message when attempting to log in with MFA

Web UI

• MFA unavailable on Free
• MFA unavailable for users created with SSO "Create user and sync permissions on login"
• MFA unavailable with no mailer
• Invite flow happy path (successful login after create)
• Admin-created happy path (successful login after create)
• Expired MFA token (can edit mfaLinkTTL in sessions.go to make this quicker)
• Can remove MFA from a user while on Free
• Cannot add SSO to a user with MFA
• Cannot add MFA to a user with SSO
• Can add MFA to an existing user (and enforced on next login)
• New order of form fields for Create/edit user modal

Additional Manual QA

• Downgrade from premium - previously 2FA enabled user remains 2FA enabled. 2FA continues to function as expected until user is edited and 2FA option removed. Once removed, 2FA is no longer enforced and no longer selectable in fleet free instance. Upgrading back to fleet Premium allows user to enable 2FA and 2FA functions as expected.
• Unable to re-use sign-in link. Message displayed "That link is expired. Log in again for a new link."
• Create user as 2FA user ensuring they also exist as a user in the SSO environment, confirm 2FA sign-on successful using link. Edit user to use SSO authentication. User is able to log in with "Sign on with SimpleSAML" option and does not receive a 2FA link in the email.
• Team admin can NOT create/edit other team users using 2FA setting (Fixed in [Enable MFA checkbox is always greyed out for team admins #24623])(Enable MFA checkbox is always greyed out for team admins #24623)

Testing notes

You'll need to set up mail serving for this. SSO config also required for some tests

Confirmation

1. Engineer (@____): Added comment to user story confirming successful completion of QA.
2. QA (@____): Added comment to user story confirming successful completion of QA.

[noahtalerman]

Hey @sharon-fdm! Who would be a good engineer for @randy-fleet to partner w/ while designing this one?

[sharon-fdm]

All our BE engineers can help, but @lucasmrod did several tasks in/around this area in the past.

[noahtalerman]

FYI @randy-fleet ^^

[randy-fleet]

@noahtalerman I added a note about reference doc changes needed, and noted where there are no changes needed for Activity and Permissions, but am unsure if there will be CLI/YAML/API changes. Can you help clarify there?

[noahtalerman]

@randy-fleet thanks!

There are no YAML changes but I think we do want to make CLI changes: add a new flag to the fleetctl user create command. Can you please help come up w/ a proposed name for this flag?

fleetctl is Fleet's CLI tool. I suggest following the guide here to download it so you can play around and see the existing options.

To see all options (flags) available for fleetctl user create you can run fleetctl user create -h (-h for help) in your Terminal. This is what the output should look like:

[noahtalerman]

• REST API changes: TODO: Update the existing user API endpoints
• Reference documentation changes: TODO: Need to add optional 2FA setting in Users API docs

@sharon-fdm this story is almost ready for specs.

To alleviate some design capacity and move quickly, I think we'll want the engineering team's help designing the API changes and updating the API docs.

To track this, I moved these checkboxes (above and in the issue description) to the engineering section.

Please let me know if you have questions/concerns.

[noahtalerman]

FYI @randy-fleet ^

[sharon-fdm]

@noahtalerman, no problem, we will try to allocate some cycles for this soon.

cc: @lucasmrod

[sharon-fdm]

@noahtalerman, @lucasmrod is assigned to help with the API design and will get to it after some P2 work.

[randy-fleet]

@noahtalerman I got fleetctl up and running and proposed the new flag on the ticket - thanks!

[noahtalerman]

Thanks @randy-fleet!

I think we want to be more explicit than 2fa. Also, not sure about 2FA. I've also seen "MFA" a lot when Googling / talking to folks. Maybe something like --email-verification? or --email-2fa? or --email-mfa?

Right now, as someone creating a user w/ fleetctl, I'm not sure what --2fa means exactly. What does this mean for the user I'm creating?

We could solve this by explaining that it's email in the description. But what if we add an option for 2FA via authenticator app later? I think we want to leave the door open for another explicit flag.

Also, note on an interesting design pattern for command line tools: command line tools often have a double dash -- before the flag (option) like --email-verification. Commands themselves don't have the -- like the user command in fleetctl create user.

[noahtalerman]

@rachaelshaw if you have time, and Lucas hasn't gotten to API design, I would pick this one up after you get through API design review.

[rachaelshaw]

@noahtalerman @lucasmrod API design PR here, added you both as reviewers. I kept "email" out of the new key name and just called it two_factor_authentication_enabled, so we have room to add other means of 2fa in the future by adding an additional key e.g. two_factor_authentication_type.

[rachaelshaw]

@randy-fleet @noahtalerman noticed one potential issue in the designs that I wasn't sure y'all had talked about: we're specifying that the email should be updated to say "Hello {First name}", but the form asks for a user's full name as one field. Inferring first/last names from full names can be tricky since you can't always rely on the location of spaces (e.g. "Mary Jane Van der Henst") so unless we already have code for handling that somewhere in the product, it may make sense to just do "Hello {Full name}".

[noahtalerman]

@rachaelshaw great catch! I think let's go w/ what's simple for now. Sounds like that's full name.

I updated the Figma here:

cc @randy-fleet

[noahtalerman]

Waiting for the best practice to be added to guides (PR here) before closing this story,

[marko-lisica]

#25005 is merged. Closing this story.

[fleet-release]

Two-factor embrace,
Cloud city's secure embrace,
Peace for admins' chase.