JanssenProject / JanssenProject/jans
docs(jans-fido2): native passkey operations guide (deployment, troubleshooting, test matrix)
- Dominant language
- Java
- Stars
- 647
- Forks
- 173
- Avg merge
- 1d 18h
- Merged PRs (30d)
- 110
Description
**Is your feature request related to a problem? Please describe.**
The Corbado article's core point is that passkeys fail *operationally*, not cryptographically — teams lack deployment playbooks, test matrices, and debugging guidance for native. Jans has a metrics guide (`docs/METRICS_WIKI.md`) but no native-mobile operations guide, and the FIDO docs are already scattered.
**Describe the solution you'd like**
Add a `docs/…/native-passkeys.md` operations guide covering:
- iOS AASA setup + Apple CDN verification; Android `assetlinks.json` + Play App Signing fingerprint; upload-key vs. Play-key gotchas.
- Credential Manager vs. legacy Android FIDO2 API; WebView vs. native vs. system-browser fallback.
- Recommended **test matrix** (per the article's minimum physical set: iPhone Face ID + Touch ID, Pixel, Samsung Galaxy, Android 9–12 for Play Services backport behavior).
- Mapping of common errors → Jans internal diagnostic codes; recommended dashboards and alert thresholds.
- Rollout strategy: monitor → limited cohort → production enforcement; fallback/recovery requirements.
- The RP config → generate/deploy → readiness-check flow, with the AASA/`assetlinks.json` `/.well-known/` + no-redirect + same-domain rules called out.
- Link the jans-chip Android + iOS samples (#14551 — a single issue covering both platforms) as reference implementations.
**Describe alternatives you've considered**
- *Fold into the existing passkey docs restructure* — the restructure should *link* it, but native operations is a distinct, deep topic that deserves its own page.
- *API-reference-only* — insufficient; the value is the operational playbook and test matrix, not endpoint docs.
**Additional context**
Capstone that ties the preceding backend features and the sample apps together. Should land after the features it documents.
Corbado article — https://www.corbado.com/blog/native-ios-android-passkey-implementation-challenges ;
ChatGPT analysis — https://chatgpt.com/share/6a5129bc-a8f4-83ea-8649-3e463e0a7db3
Contributor guide
Assessment
This issue has not been assessed yet.