95 lines
4.2 KiB
Markdown
95 lines
4.2 KiB
Markdown
# Passkey Authentication — Chrono CCG
|
|
|
|
## How it works
|
|
|
|
The app uses passkeys (WebAuthn/FIDO2) as the only sign-in method. There are no passwords, usernames, or email
|
|
addresses. Your fingerprint (or device PIN) is the key.
|
|
|
|
Authentication has two phases:
|
|
|
|
1. **Enrollment** — register a passkey once on a device/authenticator
|
|
2. **Sign in** — use that passkey to authenticate on subsequent visits
|
|
|
|
---
|
|
|
|
## First-time setup (enrollment)
|
|
|
|
1. Navigate to `http://localhost:5256/login` (or whatever the server URL is)
|
|
2. You should see: **"No passkey enrolled yet. Register your device to get started."**
|
|
3. Click **Enroll Passkey**
|
|
4. Your browser or password manager (1Password, etc.) will prompt you to create a passkey
|
|
5. Authenticate with your fingerprint, Face ID, or device PIN
|
|
6. You'll be redirected to the app — you are now signed in
|
|
|
|
The credential is stored in the database. From this point on, only registered passkeys can authenticate.
|
|
|
|
---
|
|
|
|
## Signing in after enrollment
|
|
|
|
1. Navigate to the app — if not signed in, you'll be redirected to `/login`
|
|
2. You should see: **"Use your registered passkey to sign in."**
|
|
3. Click **Sign in with Passkey**
|
|
4. Authenticate with your fingerprint, Face ID, or device PIN
|
|
5. You'll be redirected to the app
|
|
|
|
---
|
|
|
|
## Using 1Password
|
|
|
|
1Password supports passkeys natively. When prompted by the browser:
|
|
|
|
1. Click **Enroll Passkey** or **Sign in with Passkey**
|
|
2. A browser dialog will appear asking how to create/use the passkey
|
|
3. Select **1Password** from the list of options
|
|
4. 1Password will prompt for your fingerprint (Touch ID / Windows Hello)
|
|
5. Done
|
|
|
|
**Important:** The site must be accessed from its configured origin (e.g., `http://localhost:5256`). 1Password
|
|
associates passkeys with the domain/origin, so using a different address (e.g., a different port or IP) won't find the
|
|
saved passkey.
|
|
|
|
---
|
|
|
|
## Enrolling additional passkeys
|
|
|
|
Once signed in, you can enroll another passkey (e.g., a hardware key, a second device) by navigating to `/login` while
|
|
already authenticated. The Enroll Passkey button will appear and allow registration of additional credentials.
|
|
|
|
---
|
|
|
|
## Signing out
|
|
|
|
There is no sign-out UI yet. To sign out manually, clear your browser cookies for the site. The session cookie is named
|
|
`.AspNetCore.Cookies`.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
The Fido2 relying party settings live in `appsettings.Development.json`:
|
|
|
|
```json
|
|
"Fido2": {
|
|
"ServerDomain": "localhost",
|
|
"ServerName": "Chrono CCG",
|
|
"Origins": [ "http://localhost:5256", "https://localhost:7266" ]
|
|
}
|
|
```
|
|
|
|
If the server moves to a different host or port, update `Origins` to match the full scheme+host+port the browser uses to
|
|
access it. `ServerDomain` must be the effective domain (no port, no scheme).
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Cause | Fix |
|
|
|--------------------------------------------|-----------------------------------------------------------------------|-------------------------------------------------------------------|
|
|
| `Response.Transports field is required` | Old version of `passkey.js` | Redeploy — fixed in current version |
|
|
| `Relying party ID does not match` | Origin mismatch | Ensure the URL in the browser matches an entry in `Fido2:Origins` |
|
|
| `Session expired. Please retry enrollment` | Took too long between steps | Start over from the login page |
|
|
| `Credential not recognized` | Passkey was created on a different server/domain, or the DB was wiped | Re-enroll |
|
|
| Button does nothing | Blazor circuit not connected yet | Wait a moment after page load and try again |
|
|
| 1Password doesn't offer to save | Browser extension not active | Ensure 1Password browser extension is installed and enabled |
|