UX: Designs for GitLab Passkey Support

Background

We want to support passwordless authentication out of the box in GitLab. This is done with a standard called webauthn, but most people know it as passkeys. These are a standard set by the FIDO alliance that major tech companies support, such as Apple, Google and Microsoft.

Currently we support webauthn-passkeys as a second factor. We want to bring the passkey experience to the primary GitLab login experience.

Purpose

This issue can be used to house the designs for the passkey enabled flows throughout GitLab. In addition to login, we will need a way to manage passkeys and their recovery.

We also need to take a look at this community contribution which has UI work completed for passkeys.

MVC Scope

• Primary sign-in flow and create passkey (MVC)

Iteration

• Delete passkey (add on iteration)
• Upgrade existing passkeys used as 2FA for passwordless sign in (add on iteration)
• Backup code/recovery management (add on iteration)

Proposal

Explore how GitLab can support passwordless authentication:

• How do we work passwordless authentication in our current login flows (sso, username & password, 2FA)? Should we use the icons provided by FIDO - linked in the Resources section?
• How do users add and remove passkeys for passwordless authentication? Not all Webauth device can be used for passwordless authentication, users will manage passkeys for 2FA and passwordless authentication separately in User Settings > Account
• For admins, what settings are needed to securely manage passwordless authentication across their users? Today, admins can set 2FA as a requirement for all users, what settings are needed for passwordless authentication?

The output of this issue will be the final design & spec for Passwordless Authentication and will explore, design and validate the experience.

Use cases

For all use cases, login and password can still used for authentication.

Use Case	Flows
Use passkeys as a primary login (user has no 2FA).	User navigates to user settings, then adds a passkey. Login Options: User lands on login page and has two options for logging in 1 - User clicks on "Sign in with passkey", authenticates with passkey 2 - User logs in with username and password and can successfully login
With existing 2FA, use passkeys for primary login	User navigates to user settings, then adds a passkey. Alternative (Future) Upgrade existing WebAuthN device - user navigates to user settings, 2FA section and upgrades their WebAuthN eligible device to passkeys. Login Experience: User lands on login page and has two options for logging in 1 - User clicks on "Sign in with passkey", authenticates with passkey 2 - User logs in with username and password and challenged with existing 2FA methods
With existing 2FA, use passkeys for primary login and 2FA	User navigates to user settings, adds a passkey and enables the setting to use passkeys as 2FA. Alternative (Future) Upgrade existing WebAuthN device - user navigates to user settings, 2FA section, upgrades their WebAuthN eligible device to passkeys and check the setting to use passkeys as 2FA. Specify what method to use for 2FA Login Options: User lands on login page and has two options for logging in 1 - User clicks on "Sign in with passkey", authenticates with passkey 2 - User logs in with username and password and challenged with Passkey as 2FA method. If passkey is not available for use, user can use OTP or other WebAuthN devices
Users with SSO	Dependent on IdP settings, if local login (defined as login and password) is enabled then the above use cases would apply.
Admin (self managed) restricts users from logging in with passkey	Admin navigates to settings > general > permissions and restrict the primary login with passkeys.

Exploration & Feedback

We explored in the experience in low fidelity to refine the use cases for MVP:

Exploration	Feedback and questions
Add a toggle for admins to enable passkey sign-in	Enabling passkeys as a toggle setting If passkeys are more secure then this should be on by default For compliance reasons, having a toggle setting is a much better experience as there's no security standards for credentials today Quality of credential depends on the properties of the system Passkeys can be used for 2FA? 2FA enforcement can be set at any level, any user who is a member is required to configure 2FA globally Questions How will passkey settings interact with 2FA settings? How will passkey settings interact with the inheritance model?
Add a section under account to set-up passkeys	Duplicative webauthn / passkey entries Passkeys can be used for both passwordless and 2nd factor Questions Does the design represent that passkeys can be used for both 2FA and passwordless Is it intuitive experience if customers had to set up both? Do we include a migration path for existing webauthN devices?
Dependent on group settings, passkeys may or may not be available to user	Questions: Is this a global setting from the user's profile? Will passkeys be available to all users?
	Display "Sign in with passkey" only when applicable or enabled If no passkey exists or not set-up for user, then initial MVC will be to show an error to user

We moved forward with designing the experience for sign in and passkey management

Flow & Options	Designs (linked to specific screens)
Sign in Show to all users, unless group or instance restricts primary sign-in Sign in with passkey is grouped with login and password since it's a primary way of authenticating Info button to bring up additional context for users without passkey set-up - helps feature discovery and adoption Use of icon will need usage agreement @hsutor Authenticating with Passkey Screen Similar layout and copy to WebAuthN as 2FA screen - will need copy revision ( @jglassman1 ) Button to bring user back to sign-in page in case of error	Sign in Authenticating with Passkey Error Authenticating
Passkey Management Option 1: Add Passkey Management to existing area of User Settings > Account Benefits 2FA remains the same Passkeys are managed in similar way - by clicking into a new screen Opt in whether passkeys are used for 2FA Concerns Opting in to use passkeys as 2FA is far removed from the 2FA section This question applies to both options for Passkey Management - what happens in the state where we do not yet upgrade WebAuthN Passkey eligible devices into passkey section?	Manage Passkey Passkeys Default State (Empty State) Name passkey after browser set-up Passkey added and registered - user can now sign in with passkey as primary login
Passkey Management Option 2: Add Passkey Management to new area of User Settings > Authentication Benefits All authentication methods, primaries (login/pword and passkeys) and secondary exist in one page - better user experience 2FA section would list OTP as part of authentication methods table for 2FA Password is currently a section under user settings, consolidating it under one Authentication section provides better grouping Same feature as Option1 - opt in whether passkeys are used for 2FA Concerns Scopes in re-design of 2FA This question applies to both options for Passkey Management - what happens in the state where we have a passkey section but do not upgrade existing WebAuthN Passkey eligible devices into passkey section, will users only be able to add Passkeys in the passkey section?	Manage Passkeys & 2FA - Empty Default State Passkey Added + Consolidated 2FA method list
Admin setting to restrict passkey as primary sign in Located in Settings > General for top group and Admin Area Restricts passkey as primary sign in - user will not see this option on sign-in screen Concern Related to question highlighted in passkey management - If we decide passkeys become the only section for passkey eligible devices as authentication, then we still need to show this section for users even if primary sign-in is restricted, so they may use passkeys for 2FA	Admin Setting Assuming passkeys will remain even when primary sign in is restricted - show banner to notify user that passkeys can be used for 2FA

And sought to move forward with the following option for solution validation:

Flow

Designs

Option 3 Add Authentication Management to User Settings > Authentication Benefits Users can view all authentication methods in one area Authentication methods are sectioned by those available for set-up and active Enables a clear definition for different use cases (primary login, 2FA and future feature to upgrade existing webauthN device to primary) Addresses the concerns from Option 1 and Option 2 on users having to manage existing webauthN passkey devices in a different section Cons Scopes in re-design of two-factor

Option 3 - Passkey Management Add a device will take user to set-up method

General design feedback

• All oAuth sign-in options under or sign in with replaces login and password - this is the best place to add "Sign in with passkey"
• List all two-factor available methods during two-factor authentication flow (includes passkey, OTP, other WebAuthN devices)
• Improve visual distinction between authentication methods available and authentication methods activated

Prototypes

• Sign in with passkey
• Add passkey
• Add 2FA
• Restrict passkey use (admin only)

Solution Validation

🎬 Want an overview? I put together a quick overview of the results

📖 Want to dig into the findings? If you're interested in the more , check out the solution validation issue description.

Final design and specs

➡ Figma link for final designs & specs

Passkey sign in

• Add FIDO passkey logo with once approved for use: https://gitlab.com/gitlab-com/legal-and-compliance/-/issues/1931

Manage authentication - passkeys

Create passkey

Admin settings - restrict use of passkeys for primary authentication

Admin Setting

User view when passkey as primary sign in is restricted

References

• See FIDO-Passkey_Icon_Usage_Guidelines-August2022.pdf