JanssenProject / JanssenProject/jans

docs(jans-fido2): native passkey operations guide (deployment, troubleshooting, test matrix)

Open
#14,610 1 comment 1 reaction 1 assignee Claimed by @imran-ishaq View on GitHub
area-documentation comp-jans-fido2 kind-feature
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.