bf8078e enhance WebAuthn implementation and error handling.
d5e6783 improved WebAuthn error messages and session handling. Compatibility guidance in error states, and Improve user guidance for common authentication issues.
5130071 improved security key management interface, also updated locales
3994b25 Merge branch 'dev' into feat/internal-user-passkey-support
6ccc05b Update security key error handling and user feedback. Improve user guidance for security key interactions and Implement proper error handling for permission denials and timing issues.
5009906 renamed passkey to security key to stay aligned with the UI and other backend naming.
By creating this pull request, I grant the project maintainers an unlimited, perpetual license to use, modify, and redistribute these contributions under any terms they choose, including both the AGPLv3 and the Fossorial Commercial license terms. I represent that I have the right to grant this license for all contributed content.
Description
This pull request introduces a secure Passkey Authentication system for internal users, leveraging the WebAuthn standard to enable passwordless login. This modern approach provides a robust and secure alternative to traditional password-based authentication. The system includes a interface allowing users to easily register, view, and remove their keys, complemented by clear visual feedback.
Key Features & Changes
1. Authentication Flow
Login Integration: A new Security Key login option is now available alongside the traditional password login.
Selective Availability: Security Key authentication is currently restricted to internal users only.
2. Security Key Management Interface
Dedicated Management Dialog: A modern user interface has been implemented for viewing and managing all registered Security keys.
Visual Status Indicators: The interface clearly displays passkey names and their last usage dates for easy identification.
Security Measures: Sensitive operations within the management interface (e.g., Security Key registration or deletion) require re-verification of the user's password for added security.
3. Security Considerations
Challenge-Response Protocol: The system fully implements the WebAuthn challenge-response protocol to ensure strong, cryptographically secure authentication.
Expiration Controls: Authentication challenges have a strict 5-minute expiration period, mitigating replay attacks.
Access Controls: Strict verification of user permissions and ownership for passkey operations is enforced.
4. User Experience Enhancements
Clear Success/Error Messaging: Users receive comprehensive and easy-to-understand feedback for all security keys operations.
Multiple Device Support: The system includes recommendations for users to register backup Security Key, promoting resilience in case a primary device is lost or inaccessible.
Login: Log in as an internal user using your traditional password.
Navigate to Security Keys Management: Go to user profile section and locate the new Manage Security Keys option.
Initiate Registration: Click on "Add New Passkey (+) " button.
Password Verification: You should be prompted to re-enter your password to confirm your identity. Enter your password.
Passkey Device Interaction: Follow the prompts from your device (e.g., fingerprint, face ID, PIN) to register the Security Key.
Confirmation: Verify that the new passkey appears in the "Security Key Management" list with its name (e.g., "This Device") and a "Last Used" date.
Register a Second Security Key (Optional): Repeat the process to register a Security Key from a different device if available (e.g., another computer, phone). Observe the recommendation to register backup Security Keys.
Scenario 2: Logging in with a Security Key.
Logout: Log out of your current session.
Initiate Security Key Sign In: On the login page, select the option to "Sign In with Security Key."
Device Selection (if multiple): If you registered multiple passkeys, you might be prompted to choose which one to use. Select one.
Security Key Device Interaction: Complete the authentication process using your device (e.g., fingerprint, face ID, phone).
Successful Login: Confirm that you are successfully logged into your account without needing to enter a password.
Scenario 3: Deleting a Passkey
Login: Log in to your account (either with password or passkey).
Navigate to Security Key Management: Go back to the Security Key Management section.
Initiate Deletion: Click the "Delete" option next to one of your registered Security Keys.
Password Verification: You should again be prompted to re-enter your password for confirmation. Enter your password.
Confirmation: Verify that the Security Key is successfully removed from the list.
Scenario 4: Login Prompts & Edge Cases
Attempt Password Login with Existing Security Key:
Ensure the user you are testing with has at least one passkey registered (from Scenario 1).
On the login page, enter the user's username and password in the traditional login fields.
Instead of immediate login, verify that the system prompts the user to authenticate with their Security Key. Follow the passkey prompt to complete the login.
Failed Security Key Registration: During registration, try to cancel the passkey prompt on your device or intentionally fail the biometric verification. Observe the error message and ensure it's user-friendly.
Failed Security Key Login: On the login page, attempt to use a Security Key but intentionally fail the device prompt. Verify that the error message is clear and guides the user.
Expired Challenge: Attempt to register a passkey, but delay the device interaction for more than 5 minutes. Observe the error indicating the challenge has expired.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.
## 📋 Pull Request Information
**Original PR:** https://github.com/fosrl/pangolin/pull/1011
**Author:** [@adrianeastles](https://github.com/adrianeastles)
**Created:** 7/4/2025
**Status:** ✅ Merged
**Merged:** 7/14/2025
**Merged by:** [@miloschwartz](https://github.com/miloschwartz)
**Base:** `dev` ← **Head:** `feat/internal-user-passkey-support`
---
### 📝 Commits (10+)
- [`db76558`](https://github.com/fosrl/pangolin/commit/db765589441f4ae89c3c8ce82edcca840bc544f4) refactor: rename passkeyChallenge to webauthnChallenge
- [`f317171`](https://github.com/fosrl/pangolin/commit/f31717145f54bbcbf86f52ab9215ecfcdd766db7) feat(passkeys): Add password verification for passkey management
- [`1559a2a`](https://github.com/fosrl/pangolin/commit/1559a2a943f660773427e4bbfbea89656cd75e03) Fixed database dependencies.
- [`bf8078e`](https://github.com/fosrl/pangolin/commit/bf8078ed660db6a761c493f2a40f214a094ddf0b) enhance WebAuthn implementation and error handling.
- [`d5e6783`](https://github.com/fosrl/pangolin/commit/d5e67835aa4f695d8980dad6a59de156e156fb0c) improved WebAuthn error messages and session handling. Compatibility guidance in error states, and Improve user guidance for common authentication issues.
- [`5130071`](https://github.com/fosrl/pangolin/commit/5130071a60f4759544beb946a99fd2607f003411) improved security key management interface, also updated locales
- [`3994b25`](https://github.com/fosrl/pangolin/commit/3994b25a71a62061ac82eead3f82eb04f3889427) Merge branch 'dev' into feat/internal-user-passkey-support
- [`6ccc05b`](https://github.com/fosrl/pangolin/commit/6ccc05b18319a9e8285134f72567ad8bd3e52d04) Update security key error handling and user feedback. Improve user guidance for security key interactions and Implement proper error handling for permission denials and timing issues.
- [`5009906`](https://github.com/fosrl/pangolin/commit/5009906385c44bce01e522490d6bb92e4b510ab7) renamed passkey to security key to stay aligned with the UI and other backend naming.
- [`a093c54`](https://github.com/fosrl/pangolin/commit/a093c54b162ad378b4978f4dfd8ca0f84f6771db) simplified security key management interface.
### 📊 Changes
**29 files changed** (+2131 additions, -76 deletions)
<details>
<summary>View changed files</summary>
📝 `messages/de-DE.json` (+19 -1)
📝 `messages/en-US.json` (+26 -1)
📝 `messages/es-ES.json` (+19 -1)
📝 `messages/fr-FR.json` (+20 -2)
📝 `messages/it-IT.json` (+19 -1)
📝 `messages/nl-NL.json` (+19 -1)
📝 `messages/pl-PL.json` (+19 -1)
📝 `messages/pt-PT.json` (+19 -1)
📝 `messages/tr-TR.json` (+19 -1)
📝 `messages/zh-CN.json` (+22 -4)
📝 `package-lock.json` (+218 -20)
📝 `package.json` (+6 -3)
📝 `server/db/pg/schema.ts` (+24 -0)
📝 `server/db/sqlite/driver.ts` (+2 -0)
📝 `server/db/sqlite/migrate.ts` (+33 -0)
📝 `server/db/sqlite/schema.ts` (+23 -0)
📝 `server/index.ts` (+1 -1)
📝 `server/routers/auth/index.ts` (+4 -3)
📝 `server/routers/auth/login.ts` (+18 -1)
➕ `server/routers/auth/securityKey.ts` (+683 -0)
_...and 9 more files_
</details>
### 📄 Description
## Community Contribution License Agreement
By creating this pull request, I grant the project maintainers an unlimited, perpetual license to use, modify, and redistribute these contributions under any terms they choose, including both the AGPLv3 and the Fossorial Commercial license terms. I represent that I have the right to grant this license for all contributed content.
## Description
This pull request introduces a secure **Passkey Authentication system** for internal users, leveraging the WebAuthn standard to enable passwordless login. This modern approach provides a robust and secure alternative to traditional password-based authentication. The system includes a interface allowing users to easily register, view, and remove their keys, complemented by clear visual feedback.
## Key Features & Changes
### 1\. Authentication Flow
* **Login Integration:** A new Security Key login option is now available alongside the traditional password login.
* **Selective Availability:** Security Key authentication is currently restricted to internal users only.
### 2\. Security Key Management Interface
* **Dedicated Management Dialog:** A modern user interface has been implemented for viewing and managing all registered Security keys.
* **Visual Status Indicators:** The interface clearly displays passkey names and their last usage dates for easy identification.
* **Security Measures:** Sensitive operations within the management interface (e.g., Security Key registration or deletion) require re-verification of the user's password for added security.
### 3\. Security Considerations
* **Challenge-Response Protocol:** The system fully implements the **WebAuthn** challenge-response protocol to ensure strong, cryptographically secure authentication.
* **Expiration Controls:** Authentication challenges have a strict 5-minute expiration period, mitigating replay attacks.
* **Access Controls:** Strict verification of user permissions and ownership for passkey operations is enforced.
### 4\. User Experience Enhancements
* **Clear Success/Error Messaging:** Users receive comprehensive and easy-to-understand feedback for all security keys operations.
* **Multiple Device Support:** The system includes recommendations for users to register backup Security Key, promoting resilience in case a primary device is lost or inaccessible.
## Visual Improvements
https://github.com/user-attachments/assets/014236e2-a08e-493f-9143-1a019d24ed4b
## How to Test?
### Scenario 1: Registering a Security Key.
1. **Login:** Log in as an internal user using your traditional password.
2. **Navigate to Security Keys Management:** Go to user profile section and locate the new `Manage Security Keys` option.
3. **Initiate Registration:** Click on "Add New Passkey (+) " button.
4. **Password Verification:** You should be prompted to re-enter your password to confirm your identity. Enter your password.
5. **Passkey Device Interaction:** Follow the prompts from your device (e.g., fingerprint, face ID, PIN) to register the Security Key.
6. **Confirmation:** Verify that the new passkey appears in the "Security Key Management" list with its name (e.g., "This Device") and a "Last Used" date.
7. **Register a Second Security Key (Optional):** Repeat the process to register a Security Key from a different device if available (e.g., another computer, phone). Observe the recommendation to register backup Security Keys.
### Scenario 2: Logging in with a Security Key.
1. **Logout:** Log out of your current session.
2. **Initiate Security Key Sign In:** On the login page, select the option to "Sign In with Security Key."
3. **Device Selection (if multiple):** If you registered multiple passkeys, you might be prompted to choose which one to use. Select one.
4. **Security Key Device Interaction:** Complete the authentication process using your device (e.g., fingerprint, face ID, phone).
5. **Successful Login:** Confirm that you are successfully logged into your account without needing to enter a password.
### Scenario 3: Deleting a Passkey
1. **Login:** Log in to your account (either with password or passkey).
2. **Navigate to Security Key Management:** Go back to the `Security Key Management` section.
3. **Initiate Deletion:** Click the "Delete" option next to one of your registered Security Keys.
4. **Password Verification:** You should again be prompted to re-enter your password for confirmation. Enter your password.
5. **Confirmation:** Verify that the Security Key is successfully removed from the list.
### Scenario 4: Login Prompts & Edge Cases
1. **Attempt Password Login with Existing Security Key:**
* Ensure the user you are testing with has at least one passkey registered (from Scenario 1).
* On the login page, enter the user's **username and password** in the traditional login fields.
* Instead of immediate login, verify that the system **prompts the user to authenticate with their Security Key**. Follow the passkey prompt to complete the login.
2. **Failed Security Key Registration:** During registration, try to cancel the passkey prompt on your device or intentionally fail the biometric verification. Observe the error message and ensure it's user-friendly.
3. **Failed Security Key Login:** On the login page, attempt to use a Security Key but intentionally fail the device prompt. Verify that the error message is clear and guides the user.
4. **Expired Challenge:** Attempt to register a passkey, but delay the device interaction for more than 5 minutes. Observe the error indicating the challenge has expired.
---
<sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
📋 Pull Request Information
Original PR: https://github.com/fosrl/pangolin/pull/1011
Author: @adrianeastles
Created: 7/4/2025
Status: ✅ Merged
Merged: 7/14/2025
Merged by: @miloschwartz
Base:
dev← Head:feat/internal-user-passkey-support📝 Commits (10+)
db76558refactor: rename passkeyChallenge to webauthnChallengef317171feat(passkeys): Add password verification for passkey management1559a2aFixed database dependencies.bf8078eenhance WebAuthn implementation and error handling.d5e6783improved WebAuthn error messages and session handling. Compatibility guidance in error states, and Improve user guidance for common authentication issues.5130071improved security key management interface, also updated locales3994b25Merge branch 'dev' into feat/internal-user-passkey-support6ccc05bUpdate security key error handling and user feedback. Improve user guidance for security key interactions and Implement proper error handling for permission denials and timing issues.5009906renamed passkey to security key to stay aligned with the UI and other backend naming.a093c54simplified security key management interface.📊 Changes
29 files changed (+2131 additions, -76 deletions)
View changed files
📝
messages/de-DE.json(+19 -1)📝
messages/en-US.json(+26 -1)📝
messages/es-ES.json(+19 -1)📝
messages/fr-FR.json(+20 -2)📝
messages/it-IT.json(+19 -1)📝
messages/nl-NL.json(+19 -1)📝
messages/pl-PL.json(+19 -1)📝
messages/pt-PT.json(+19 -1)📝
messages/tr-TR.json(+19 -1)📝
messages/zh-CN.json(+22 -4)📝
package-lock.json(+218 -20)📝
package.json(+6 -3)📝
server/db/pg/schema.ts(+24 -0)📝
server/db/sqlite/driver.ts(+2 -0)📝
server/db/sqlite/migrate.ts(+33 -0)📝
server/db/sqlite/schema.ts(+23 -0)📝
server/index.ts(+1 -1)📝
server/routers/auth/index.ts(+4 -3)📝
server/routers/auth/login.ts(+18 -1)➕
server/routers/auth/securityKey.ts(+683 -0)...and 9 more files
📄 Description
Community Contribution License Agreement
By creating this pull request, I grant the project maintainers an unlimited, perpetual license to use, modify, and redistribute these contributions under any terms they choose, including both the AGPLv3 and the Fossorial Commercial license terms. I represent that I have the right to grant this license for all contributed content.
Description
This pull request introduces a secure Passkey Authentication system for internal users, leveraging the WebAuthn standard to enable passwordless login. This modern approach provides a robust and secure alternative to traditional password-based authentication. The system includes a interface allowing users to easily register, view, and remove their keys, complemented by clear visual feedback.
Key Features & Changes
1. Authentication Flow
2. Security Key Management Interface
3. Security Considerations
4. User Experience Enhancements
Visual Improvements
https://github.com/user-attachments/assets/014236e2-a08e-493f-9143-1a019d24ed4b
How to Test?
Scenario 1: Registering a Security Key.
Manage Security Keysoption.Scenario 2: Logging in with a Security Key.
Scenario 3: Deleting a Passkey
Security Key Managementsection.Scenario 4: Login Prompts & Edge Cases
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.