Passkey Authentication

[judsd]

Summary

Passkeys offer a fresh take on password-free and soon, even username-free logins.

In non-enterprise Directus setups without SAML, passkeys are valuable for bolstering secure authentication and access.

Basic Example

No response

Motivation

Enhanced Security: Harder to guess than regular passwords.
Simplicity: Easier to remember or manage.
Quick Entry: Faster login process.
No Reuse: Passkeys are often temporary, reducing risk of reuse.
Phishing Resistance: Less vulnerable to phishing attacks.

and we are willing to sponsor this feature.

Detailed Design

Terminology

WebAuthn: Web Authentication API for public key-based credentials.
Passkey: A hardware device, mobile device, or biometric data used for authentication.
Credential ID: A unique identifier for each passkey.

Requirements:

Directus 9.x or higher
WebAuthn-compatible browser
Hardware key (e.g., YubiKey), or a biometric-enabled device

Data Model Changes:

Add new columns in the directus_users table:
webauthn_credential_id (String)
webauthn_public_key (String)

It actually might be more ideal to have a separate table for the keys, as in the future you might want to bring support to multiple keys per user.

API Endpoints:

POST /auth/webauthn-register: Register a new passkey.

Input: credential
Output: success: true/false
POST /auth/webauthn-auth: Authenticate using a passkey.

Input: assertion
Output: JWT token
Workflow:
Register Passkey: User chooses to register a new WebAuthn device. The frontend requests the POST /auth/webauthn-register endpoint.

Corner Case: If the user already has a registered device, ask to overwrite or add another.
Store Credentials: After successful registration, store webauthn_credential_id and webauthn_public_key in the directus_users table.

Authenticate: When logging in, the user can choose WebAuthn. The frontend calls POST /auth/webauthn-auth.

Corner Case: If the device isn't recognized, fallback to password login.

Example Use Cases:

User registers their fingerprint and logs in using it.
User tries to authenticate with an unrecognized device, and the system falls back to password login.

Security Considerations:

Implement rate limiting on WebAuthn registration and authentication endpoints.

Frontend Changes:

Add a "Register WebAuthn Device" button in user settings.
Add a "Login with WebAuthn" button on the login screen.

Backend Changes:

Integrate a WebAuthn library to handle registration and authentication.

Testing:

Unit tests for WebAuthn registration and authentication.
End-to-end tests for logging in with and without a passkey.

Requirements List

Must-Have:

1. User Registration: Users must be able to register a WebAuthn device.
2. Database Changes: The directus_users table must support WebAuthn fields (webauthn_credential_id, webauthn_public_key).
3. Authentication: Users must be able to authenticate using a registered WebAuthn device.
4. Security: Rate limiting on WebAuthn registration and authentication endpoints.
5. Backend API: Implement POST /auth/webauthn-register and POST /auth/webauthn-auth.

Should-Have:

1. Multiple Devices: Users should be able to register more than one WebAuthn device.
2. Fallback: Fallback to password authentication if WebAuthn fails.
3. User Interface: Clear UI indicators for WebAuthn as an authentication option.

Could-Have:

1. Audit Logs: Track successful and failed WebAuthn login attempts.
2. Notifications: Notify users when a new WebAuthn device is registered.
3. Device Management: UI for managing multiple WebAuthn devices.

Won't-Have (this time):

1. SMS Backup: Two-factor authentication via SMS as a backup.
2. QR Code Support: Using QR codes to initiate WebAuthn registration.

Drawbacks

1. Complexity: Adds complexity to both the backend and frontend.
2. Browser Support: Not all browsers fully support WebAuthn.
3. User Adoption: Requires users to have WebAuthn-compatible devices.
4. Fallback Risks: If WebAuthn fails, falling back to passwords can be a security risk.
5. Development Time: Takes time to implement, test, and deploy.
6. User Training: Users may need guidance on how to use new login methods.
7. Cost: Hardware keys, if used, can add an extra cost.

Alternatives

1. Two-Factor Authentication (2FA): Use SMS or authenticator apps for additional security.

   • Pros: Easier to implement, wide user adoption.
   • Cons: Less secure than WebAuthn, vulnerable to phishing.

2. OAuth Providers: Using Google, Facebook, etc., for login.

   • Pros: Quick to implement, familiar to users.
   • Cons: Dependence on third-party services, privacy concerns.

3. Biometric Authentication: Use native biometrics (fingerprint, face recognition) of devices.

   • Pros: Very secure and user-friendly.
   • Cons: Device-dependent, not universally applicable.

4. Passwordless Email Links: Send one-time-use login links via email.

   • Pros: Simple for users, no password to remember.
   • Cons: Less secure, email becomes a single point of failure.

Impact of Not Implementing WebAuthn

1. Security Risks: Remain vulnerable to password-related attacks like phishing and brute-force attacks.
2. Competitive Disadvantage: Lack of a modern, secure login method could make Directus less appealing.
3. User Expectations: As WebAuthn becomes standard, not offering it might disappoint security-conscious users.
4. Regulatory Impact: Might not meet future regulatory requirements for secure authentication.

Adoption Strategy

Adoption:

1. Documentation: Detailed docs to explain how to use WebAuthn-based login.
2. Tutorials/Webinars: Educational content to help developers understand the new feature.
3. Sample Code: Provide examples in the Directus GitHub repository.

Breaking Change:

• No: This feature would be an additional method of authentication and should not affect existing login mechanisms.

Migration:

• Database Migration: A database script can add new WebAuthn-related fields to the directus_users table.
• Legacy Support: An opt-in setting can allow developers to choose WebAuthn or the existing method.

Impact on Other Directus Projects:

1. Directus Extensions: Any extension relying on user authentication should be checked for compatibility.
2. Directus SDKs: SDKs may need updates to support WebAuthn-based login.
3. Third-party Integrations: Shouldn't be affected if WebAuthn is optional and the existing login remains.

In summary, this should be a smooth, non-breaking change that adds an extra layer of security, provided it's implemented carefully with good documentation.

Unresolved Questions

No response

[judsd]

I searched issues instead of discussions.

There is an existing discussion for the same request.
#18755