docs: refactor fido and passkey docs#14547
Conversation
Signed-off-by: Dhaval Desai <343411+ossdhaval@users.noreply.github.com>
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
mo-auto
added
area-documentation
📝 WalkthroughWalkthroughFIDO2 documentation is reorganized around configuration references, passkey implementation, administration, metadata, logging, and conditional UI. MkDocs navigation is updated, obsolete pages are removed, and new configuration and passkey guide pages are added. ChangesFIDO2 configuration and reference documentation
Passkey implementation and administration
FIDO2 operational documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related issues
Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Error: Hi @ossdhaval, You did not reference an open issue in your PR. I attempted to create an issue for you. |
coderabbitai
Bot
added
comp-jans-fido2
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/janssen-server/config-guide/fido2-config/janssen-fido2-configuration.md`:
- Around line 193-194: Update the two FIDO documentation links in the
configuration guide so their relative paths include the additional
parent-directory traversal needed to resolve from config-guide/fido2-config/ to
the docs/janssen-server/fido/ directory.
In `@docs/janssen-server/fido/conditional-ui-and-fallback.md`:
- Around line 654-656: Update the FIDO2 Configuration link in the Related
Documentation entry to reference the existing fido2-server-properties-config.md
page, preserving its descriptive text and surrounding documentation links.
In `@docs/janssen-server/fido/fido2-server-properties-config.md`:
- Line 30: Update the fido2Configuration description to hyphenate
“protocol-specific” when it modifies “details,” leaving the rest of the
documentation unchanged.
In `@docs/janssen-server/fido/logs.md`:
- Around line 80-88: Update both fenced command blocks in the documentation
around the post-config-scripts command and the fido2 restart instructions to use
the shell language identifier, preserving their command contents unchanged.
- Around line 78-82: Update the command example in the logging-level
instructions to use the put-properties-fido2 operation ID instead of
post-config-scripts, while keeping the existing configuration data file and
command structure unchanged.
In `@docs/janssen-server/fido/README.md`:
- Around line 34-38: Polish the FIDO Metric API introduction for grammatical
correctness, and capitalize the final “assertion completions” bullet to match
the capitalization of the preceding list items.
- Line 48: Update the “Fido Metadata Service (MDS)” heading to capitalize the
product name as “FIDO,” preserving the rest of the heading text.
In `@docs/janssen-server/fido/vendor-metadata.md`:
- Around line 11-15: Update the metadata references in the introductory
paragraph and Local metadata section: change the local metadata link target to
`#local-metadata`, and replace serverMetadataPath with serverMetadataFolder while
linking its configuration reference to `#servermetadatafolder`. Preserve the
surrounding documentation and description.
In `@docs/janssen-server/recipes/passkey-impl-guide.md`:
- Line 129: Correct the heading capitalization for “command Line (Jans CLI)” so
it uses standard title capitalization, changing “command” to “Command” while
preserving the rest of the heading.
- Around line 56-57: Revise the introductory paragraph describing the two
passkey implementation options to improve grammar and readability, ensuring the
comparison between Agama-based and script-based implementations flows clearly
while preserving the original meaning.
In `@docs/script-catalog/fido2_extension/fido2-extension.md`:
- Around line 54-55: Add a blank line between the “Use case: Sample Fido2
Interception Form” heading and the following paragraph so the heading is
surrounded by blank lines.
In `@mkdocs.yml`:
- Line 224: Update all FIDO2 configuration references to use the actual
fido2-server-properties-config.md filename: change the navigation entry in
mkdocs.yml, the relative link in docs/janssen-server/fido/README.md, and the
relative link in docs/janssen-server/recipes/passkey-impl-guide.md.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 20b7374b-d75f-47ad-974d-e36afcceb3bc
📒 Files selected for processing (12)
docs/janssen-server/config-guide/fido2-config/janssen-fido2-configuration.mddocs/janssen-server/fido/README.mddocs/janssen-server/fido/conditional-ui-and-fallback.mddocs/janssen-server/fido/config.mddocs/janssen-server/fido/fido2-server-properties-config.mddocs/janssen-server/fido/logs.mddocs/janssen-server/fido/passwordlessLoginExperience.mddocs/janssen-server/fido/types-of-creds.mddocs/janssen-server/fido/vendor-metadata.mddocs/janssen-server/recipes/passkey-impl-guide.mddocs/script-catalog/fido2_extension/fido2-extension.mdmkdocs.yml
💤 Files with no reviewable changes (3)
- docs/janssen-server/fido/types-of-creds.md
- docs/janssen-server/fido/passwordlessLoginExperience.md
- docs/janssen-server/fido/config.md
Signed-off-by: Dhaval Desai <343411+ossdhaval@users.noreply.github.com>
coderabbitai
Bot
added
kind-feature
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/janssen-server/fido/fido2-server-properties-config.md (2)
44-44: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winAlign
unfinishedRequestExpirationwith the configuration guide.This page shows
120, while the CLI example injanssen-fido2-configuration.mdand the supplied dynamic configuration template use180. Because the column is labeled “Default / Example,” readers cannot determine the intended value.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/janssen-server/fido/fido2-server-properties-config.md` at line 44, Update the unfinishedRequestExpiration entry in the configuration table to use 180 as the Default / Example value, aligning it with the CLI example and dynamic configuration template.
15-30: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winDocument all top-level fields returned by the FIDO2 configuration API.
The sibling CLI example in
docs/janssen-server/config-guide/fido2-config/janssen-fido2-configuration.mdalso returnspersonCustomObjectClassList,sessionIdPersistInCache, anderrorReasonEnabled, but this reference omits them. Add these fields or explicitly state that the table is intentionally partial.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/janssen-server/fido/fido2-server-properties-config.md` around lines 15 - 30, The FIDO2 configuration properties table is missing top-level fields exposed by the configuration API. Update the table to include personCustomObjectClassList, sessionIdPersistInCache, and errorReasonEnabled, using the corresponding descriptions and types from the sibling Janssen FIDO2 configuration documentation; do not leave the table implicitly partial.docs/janssen-server/recipes/passkey-impl-guide.md (1)
77-85: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winDocument the required base64url encoding for
allowList.The guide shows raw JSON, but
Fido2ExternalAuthenticator.pybase64url-decodes the cookie before callingjson.loads. Following this example causes the cookie to be discarded, so conditional/usernameless login cannot use the credential allow list. Document the encoded value (or change the script contract). The referenced script also does not setSameSite=Strict, so clarify which component owns that attribute.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/janssen-server/recipes/passkey-impl-guide.md` around lines 77 - 85, Update the allowList cookie documentation in Step 2 to state that the JSON value must be base64url-encoded before storage, matching Fido2ExternalAuthenticator.py’s decoding contract. Clarify which component is responsible for setting SameSite=Strict, since the referenced script does not apply that attribute; keep the existing Secure and HttpOnly guidance aligned with the actual owner.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/janssen-server/fido/logs.md`:
- Around line 80-82: Update the documented Jans CLI operation in the FIDO2
logging procedure from post-config-scripts to put-properties-fido2 so it applies
the loggingLevel and loggingLayout properties, or verify and track the
corresponding CLI mapping change before retaining the existing operation.
In `@docs/janssen-server/recipes/passkey-impl-guide.md`:
- Around line 129-130: Insert a blank line between the “### Command Line (Jans
CLI)” heading and the following list item to satisfy Markdownlint MD022.
In `@docs/script-catalog/fido2_extension/fido2-extension.md`:
- Line 57: Insert a blank line immediately before the “### Script Type: Python”
heading so it is separated from the preceding paragraph; leave the heading and
surrounding content unchanged.
---
Outside diff comments:
In `@docs/janssen-server/fido/fido2-server-properties-config.md`:
- Line 44: Update the unfinishedRequestExpiration entry in the configuration
table to use 180 as the Default / Example value, aligning it with the CLI
example and dynamic configuration template.
- Around line 15-30: The FIDO2 configuration properties table is missing
top-level fields exposed by the configuration API. Update the table to include
personCustomObjectClassList, sessionIdPersistInCache, and errorReasonEnabled,
using the corresponding descriptions and types from the sibling Janssen FIDO2
configuration documentation; do not leave the table implicitly partial.
In `@docs/janssen-server/recipes/passkey-impl-guide.md`:
- Around line 77-85: Update the allowList cookie documentation in Step 2 to
state that the JSON value must be base64url-encoded before storage, matching
Fido2ExternalAuthenticator.py’s decoding contract. Clarify which component is
responsible for setting SameSite=Strict, since the referenced script does not
apply that attribute; keep the existing Secure and HttpOnly guidance aligned
with the actual owner.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: c757cb58-b0ef-423a-9729-3484d6bee513
📒 Files selected for processing (9)
docs/janssen-server/config-guide/fido2-config/janssen-fido2-configuration.mddocs/janssen-server/fido/README.mddocs/janssen-server/fido/conditional-ui-and-fallback.mddocs/janssen-server/fido/fido2-server-properties-config.mddocs/janssen-server/fido/logs.mddocs/janssen-server/fido/vendor-metadata.mddocs/janssen-server/recipes/passkey-impl-guide.mddocs/script-catalog/fido2_extension/fido2-extension.mdmkdocs.yml
Signed-off-by: Dhaval Desai <343411+ossdhaval@users.noreply.github.com>
coderabbitai
Bot
added
kind-enhancement
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/janssen-server/recipes/passkey-impl-guide.md (3)
82-89: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winDocument the required Base64URL encoding for
allowList.The referenced
Fido2ExternalAuthenticator.pydecodes the cookie value as Base64URL before callingjson.loads. Following this example literally stores raw JSON, causing the script to reject the cookie and fall back to an empty allowlist.* **Cookie Structure**: - [{"id": "<credential-id-base64url>", "type": "public-key", "transports": ["internal", "usb"]}] + Base64URL-encoded JSON: + [{"id": "<credential-id-base64url>", "type": "public-key", "transports": ["internal", "usb"]}]🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/janssen-server/recipes/passkey-impl-guide.md` around lines 82 - 89, Update the allowList cookie documentation to require Base64URL-encoding the JSON cookie value before storage, matching the decoding performed by Fido2ExternalAuthenticator.py. Clarify that the encoded value must contain the documented credential structure, while preserving the existing Secure, HttpOnly, and SameSite requirements.
139-145: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winUpdate the CLI description for
get-properties-fido2.
get-properties-fido2returns FIDO2 configuration properties, not registered device entries. Change the first bullet to “retrieve current FIDO2 configuration properties,” or point readers to the device-management/TUI flow if that’s the intent.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/janssen-server/recipes/passkey-impl-guide.md` around lines 139 - 145, Update the first bullet describing the get-properties-fido2 operation to state that it retrieves current FIDO2 configuration properties, replacing the incorrect reference to registered device entries. Leave the put-properties-fido2 guidance unchanged.
150-154: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winUse the FIDO2 Config API endpoint. The documented
PUT /jans-config-api/fido2/configurationpath is incorrect; the FIDO2 Config API usesPUT /jans-config-api/fido2/fido2-config.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/janssen-server/recipes/passkey-impl-guide.md` around lines 150 - 154, Update the documented FIDO2 configuration endpoint in the passkey implementation guide from /jans-config-api/fido2/configuration to /jans-config-api/fido2/fido2-config, while keeping the surrounding automation guidance and OpenAPI reference unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/janssen-server/recipes/passkey-impl-guide.md`:
- Around line 82-89: Update the allowList cookie documentation to require
Base64URL-encoding the JSON cookie value before storage, matching the decoding
performed by Fido2ExternalAuthenticator.py. Clarify that the encoded value must
contain the documented credential structure, while preserving the existing
Secure, HttpOnly, and SameSite requirements.
- Around line 139-145: Update the first bullet describing the
get-properties-fido2 operation to state that it retrieves current FIDO2
configuration properties, replacing the incorrect reference to registered device
entries. Leave the put-properties-fido2 guidance unchanged.
- Around line 150-154: Update the documented FIDO2 configuration endpoint in the
passkey implementation guide from /jans-config-api/fido2/configuration to
/jans-config-api/fido2/fido2-config, while keeping the surrounding automation
guidance and OpenAPI reference unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 0e8c3ee8-0c6f-4628-a818-b826992f9b3f
📒 Files selected for processing (3)
docs/janssen-server/fido/logs.mddocs/janssen-server/recipes/passkey-impl-guide.mddocs/script-catalog/fido2_extension/fido2-extension.md
Signed-off-by: Dhaval Desai <343411+ossdhaval@users.noreply.github.com>
coderabbitai
Bot
added
kind-feature
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/janssen-server/recipes/passkey-impl-guide.md (1)
82-89: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winDocument the required Base64URL encoding for
allowList.The referenced
Fido2ExternalAuthenticator.pydecodes the cookie value as Base64URL before parsing JSON. This example currently shows raw JSON, so an implementation following the guide will produce an unparsable cookie and break usernameless credential selection. Clarify that the JSON payload must be Base64URL-encoded before being stored in the cookie.Proposed clarification
* **Cookie Structure**: + The cookie value must be the Base64URL-encoded JSON below: ```json [{"id": "<credential-id-base64url>", "type": "public-key", "transports": ["internal", "usb"]}]</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/janssen-server/recipes/passkey-impl-guide.mdaround lines 82 - 89,
Update the allowList Cookie Structure documentation to state that the JSON
payload must be Base64URL-encoded before storage, matching the decoding
performed by Fido2ExternalAuthenticator.py. Clarify that the shown JSON is the
pre-encoding payload and that the cookie value must contain its
Base64URL-encoded representation.</details> <!-- cr-comment:v1:3c8e9a18b9ccbb7dc03f1723 --> </blockquote></details> </blockquote></details>🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@docs/janssen-server/fido/vendor-metadata.md`: - Line 15: Update the configuration link in the sentence describing serverMetadataFolder to use the property-specific anchor `#servermetadatafolder`, while preserving the existing destination document and surrounding wording. --- Outside diff comments: In `@docs/janssen-server/recipes/passkey-impl-guide.md`: - Around line 82-89: Update the allowList Cookie Structure documentation to state that the JSON payload must be Base64URL-encoded before storage, matching the decoding performed by Fido2ExternalAuthenticator.py. Clarify that the shown JSON is the pre-encoding payload and that the cookie value must contain its Base64URL-encoded representation.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID:
7056763f-c26d-4f9e-96fe-60c84e6fe808📒 Files selected for processing (2)
docs/janssen-server/fido/vendor-metadata.mddocs/janssen-server/recipes/passkey-impl-guide.md
|
|
||
| ### 1. Local metadata service: | ||
| Janssen's FIDO server has a [configuration parameter](./config.md) called `serverMetadataFolder` which by default points to a directory location `/etc/jans/conf/fido2/server_metadata` where the administrator can (obtain from a vendor and ) place authenticator metadata in json format. | ||
| Janssen's FIDO server has a [configuration parameter](./fido2-server-properties-config.md#fido2-configuration-object-fido2configuration) called `serverMetadataFolder` which by default points to a directory location `/etc/jans/conf/fido2/server_metadata` where the administrator can (obtain from a vendor and ) place authenticator metadata in json format. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Link directly to the serverMetadataFolder property.
The current link targets the generic FIDO2 configuration object. Use the property-specific anchor #servermetadatafolder so readers land on the documented setting.
Proposed fix
-Janssen's FIDO server has a [configuration parameter](./fido2-server-properties-config.md#fido2-configuration-object-fido2configuration) called `serverMetadataFolder`
+Janssen's FIDO server has a [configuration parameter](./fido2-server-properties-config.md#servermetadatafolder) called `serverMetadataFolder`🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/janssen-server/fido/vendor-metadata.md` at line 15, Update the
configuration link in the sentence describing serverMetadataFolder to use the
property-specific anchor `#servermetadatafolder`, while preserving the existing
destination document and surrounding wording.
2 participants
Prepare
Description
PR refactors fido and passkey documentation to achieve:
Target issue
closes #issue-number-here
Implementation Details
Test and Document the changes
Please check the below before submitting your PR. The PR will not be merged if there are no commits that start with
docs:to indicate documentation changes or if the below checklist is not selected.Closes #14548,
Summary by CodeRabbit