Skip to content

docs(cloud): document passkey sign-in for Layer5 Cloud accounts and self-hosted identity - #1383

Merged
yi-nuo426 merged 3 commits into
masterfrom
docs/passkeys-sign-in
Nov 20, 2026
Merged

yi-nuo426 merged 3 commits into
masterfrom
docs/passkeys-sign-in

Conversation

@yi-nuo426

@yi-nuo426 yi-nuo426 commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Intent

The user asked to open issues and make sure the user-facing documentation for passkey/WebAuthn sign-in gets updated (#1382). The user explicitly said passkeys do NOT need a dedicated page unless there is a lot to describe about expiry or how often they are requested; there is not (a passkey never expires, is requested only at sign-in, adding/removing one needs a sign-in within the privileged window - 24h hosted, 15m self-hosted chart default - and passkeys work only on cloud.layer5.io, never on custom domains), so the content is folded into existing pages: the getting-started account guide (sign-up table row, sign-in paragraph, an 'Add or remove a passkey' settings section), sessions.md (passkey sign-ins are ordinary sessions; corrected privileged-action window row, which wrongly gave 15 minutes as the Layer5 Cloud value), and the self-hosted identity-services guide (relying-party id/origins/display_name and why id/origins are effectively immutable). The dead commented-out 2FA/passkey block was removed on purpose (2FA does not exist and the pages it linked do not exist). Button labels are rendered by Kratos, so the text describes the buttons rather than quoting labels; 'Add a passkey' and 'Remove' are quoted because they are the product's own strings. Per this repo's AGENTS.md: claims were verified against meshery-cloud origin/master and the live config, and no meshery-cloud (private) PR/issue/file is linked from content - only the release version v1.0.371. The site was built locally with the pinned Hugo and the new anchors resolve.

What Changed

  • Account guide (getting-started-with-layer5-account.md): adds a sign-up table row for registering a passkey alongside email and password. Adds a sign-in paragraph covering the passkey button, autofill, cross-device QR, and the fallback to password. Adds a new "Add or remove a passkey" section covering where to manage passkeys, that they never expire, the privileged-action window, lost-device recovery, the fact that passkeys work only on cloud.layer5.io, and availability from v1.0.371. Also lists passkey changes as privileged actions and removes the dead commented-out 2FA/passkey block.
  • Sessions concept (sessions.md): states that a passkey sign-in creates an ordinary session with no lifetime of its own. Fixes the privileged-action window row, which gave 15 minutes as the Layer5 Cloud value. It now reads 24 hours on Layer5 Cloud and 15 minutes in the self-hosted chart default, with updated examples.
  • Self-hosted identity services (identity-services/index.md): adds a "Passkey sign-in" chart-default row and a new "Passkeys" section documenting the rp.id, rp.origins, and rp.display_name keys. It explains that changing id or removing a sign-in origin strands existing passkeys, and why custom-domain hosts cannot use passkeys.

Risk Assessment

✅ Low: This change only touches docs. I checked the passkey rp keys, the localhost default and the privileged-session windows (24h hosted, 15m chart) against meshery-cloud origin/master. The round-1 fix now limits the stranding claim to changing id or removing the origin users sign in on, which is accurate.

Testing

Ran npm install and built the full site with the repo's local postcss on PATH. Hugo exited 0 and built 3372 pages. Then I checked the generated HTML of the three changed pages: - The anchors #add-or-remove-a-passkey and #passkeys exist. - Every new link to them resolves. - The Sessions table row now gives 24 hours for Layer5 Cloud and 15 minutes for the self-hosted chart. - The commented-out 2FA block is gone. - No raw Markdown or shortcode text leaks into the output. - No meshery-cloud links appear. I served the build locally and screenshotted each changed section in headless Chrome (chrome-devtools-axi); all render cleanly in the site theme. All build output, node_modules, the local server and the browser were removed afterwards.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
A reader opens the account guide's 'Add or remove a passkey' section by its anchor and sees it rendered, listed in the On this page sidebar ✅ pass live account-add-or-remove-a-passkey.png; id="add-or-remove-a-passkey" present in built HTML
The sign-up table row and the sign-in paragraph link to the passkey section, and the link resolves ✅ pass live href="#add-or-remove-a-passkey" (x2) in built account page; account-sign-in-passkey.png
The Sessions page shows the corrected privileged-action window (24h Layer5 Cloud, 15m self-hosted) and its passkey link resolves to the account guide anchor ✅ pass live Built sessions HTML row text; href to getting-started-with-layer5-account/#add-or-remove-a-passkey; sessions-window-row.png
The self-hosted identity-services guide shows the new defaults row linking to a rendered Passkeys section with the rp id/origins/display_name table and the narrowed wording about what strands passkeys ✅ pass live identity-services-passkeys.png; href="#passkeys" and id="passkeys" in built HTML
Adversarial: the removed 2FA comment leaves no stray text, and no raw Markdown, shortcodes or private meshery-cloud links appear in the built pages ✅ pass live grep counts: two-factor=0; '## '/'{{<' leaks=0 on all three pages; no meshery-cloud matches

Account guide - Add or remove a passkey section

Account guide - sign-in with passkey paragraph

Sessions page - corrected privileged-action window row

Self-hosted identity services - Passkeys section

Evidence: Hugo build log
⚠ Hugo is missing, reinstalling now...
☁️ Downloading hugo_extended_0.158.0_darwin-universal.pkg...
🕵️ Verifying checksum...
📦 Extracting...
🎉 Hugo installed successfully!
hugo v0.158.0-f41be7959a44108641f1e081adf5c4be7fc1bb63+extended darwin/amd64 BuildDate=2026-03-16T17:42:04Z VendorInfo=gohugoio
Start building sites … 
hugo v0.158.0-f41be7959a44108641f1e081adf5c4be7fc1bb63+extended darwin/amd64 BuildDate=2026-03-16T17:42:04Z VendorInfo=gohugoio


                  │  EN  
──────────────────┼──────
 Pages            │ 3372 
 Paginator pages  │    0 
 Non-page files   │  491 
 Static files     │  789 
 Processed images │  248 
 Aliases          │  210 
 Cleaned          │    0 

Total in 106456 ms

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅
  • ℹ️ content/en/cloud/guides/self-hosted/planning/identity-services/index.md:91 - The text says "changing either later strands every existing passkey". That is true for id, because every passkey is scoped to the RP ID. It overstates the effect of origins. Adding an origin under the same id strands nothing. Only removing or replacing the origin users sign in on breaks existing passkeys. A suggested narrower wording: "changing id, or removing the origin users sign in on, strands every existing passkey". This keeps the intended 'effectively immutable' guidance without misinforming operators who only want to add a subdomain origin. It is user-visible wording, so the author should decide.

🔧 Fix applied.
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
A reader opens the account guide's 'Add or remove a passkey' section by its anchor and sees it rendered, listed in the On this page sidebar ✅ pass live account-add-or-remove-a-passkey.png; id="add-or-remove-a-passkey" present in built HTML
The sign-up table row and the sign-in paragraph link to the passkey section, and the link resolves ✅ pass live href="#add-or-remove-a-passkey" (x2) in built account page; account-sign-in-passkey.png
The Sessions page shows the corrected privileged-action window (24h Layer5 Cloud, 15m self-hosted) and its passkey link resolves to the account guide anchor ✅ pass live Built sessions HTML row text; href to getting-started-with-layer5-account/#add-or-remove-a-passkey; sessions-window-row.png
The self-hosted identity-services guide shows the new defaults row linking to a rendered Passkeys section with the rp id/origins/display_name table and the narrowed wording about what strands passkeys ✅ pass live identity-services-passkeys.png; href="#passkeys" and id="passkeys" in built HTML
Adversarial: the removed 2FA comment leaves no stray text, and no raw Markdown, shortcodes or private meshery-cloud links appear in the built pages ✅ pass live grep counts: two-factor=0; '## '/'{{<' leaks=0 on all three pages; no meshery-cloud matches
  • npm install &amp;&amp; PATH=&#34;$PWD/node_modules/.bin:$PATH&#34; hugo -d /tmp/nm-site-01M7 (exit 0)
  • grep built HTML for id="add-or-remove-a-passkey", id="passkeys" and the href links that target them
  • grep built sessions page for the Privileged-action window row text
  • grep built account page for leftover two-factor text and for meshery-cloud links (none found)
  • python3 -m http.server + chrome-devtools-axi open/screenshot of the four changed sections
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

Summary by CodeRabbit

  • Documentation
    • Updated account setup guidance to cover password registration with an optional passkey, passkey sign-in, and managing or recovering passkeys.
    • Clarified that passkeys do not change session duration and are requested only during passkey sign-in.
    • Added self-hosted passkey configuration guidance, including supported hosts and how configuration changes can affect existing passkeys.
    • Clarified privileged-action windows for Layer5 Cloud and the self-hosted chart default, with examples including passkey changes.

…lf-hosted identity pages

Passkeys shipped in Layer5 Cloud v1.0.371 with no user-facing docs.
Passkey behaviour is small (no expiry, requested only at sign-in, a
recent sign-in to add or remove one, canonical host only), so it is
folded into existing pages rather than a dedicated one:

- Account guide: passkey option at sign-up, passkey sign-in (button,
  autofill, phone on desktop), and an 'Add or remove a passkey'
  settings section with expiry, privileged-window, lost-device and
  custom-domain behaviour. Removes the commented-out 2FA/passkey block.
- Sessions: passkey sign-ins create ordinary sessions; corrects the
  privileged-action window to 24 hours on Layer5 Cloud (15 minutes is
  the self-hosted chart default).
- Self-hosted identity services: the passkey relying-party settings and
  why id/origins must be fixed before users register.

Claims verified against meshery-cloud master (ui/pages/security/passkeys,
server/handlers/auth_flow.go) and the live production Kratos config.

Closes #1382

Signed-off-by: hortison <160366376+hortison@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 20, 2026 22:06

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@coderabbitai

coderabbitai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Explain Change →

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 85740530-ffdd-46b4-bbc1-7b5a5335d627
Commits

Reviewing files that changed from the base of the PR and between 1771b86 and 677e0c1.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

The documentation now covers passkey registration, sign-in, management, session behavior, recovery, and self-hosted configuration. It also specifies the hosted and self-hosted privileged-action windows.

Changes: Passkey documentation

Layer / File(s) Summary
Session and privileged-action rules
content/en/cloud/concepts/identity-and-security/sessions.md, content/en/cloud/getting-started/getting-started-with-layer5-account.md
Documents 24-hour hosted and 15-minute self-hosted default privileged-action windows. Describes passkey sign-in and its effect on session lifetime.
Account registration, sign-in, and passkey management
content/en/cloud/getting-started/getting-started-with-layer5-account.md
Adds instructions for passkey registration, sign-in, management, and recovery, including device confirmation and account availability details.
Self-hosted passkey settings
content/en/cloud/guides/self-hosted/planning/identity-services/index.md
Documents the chart default and configuration for the relying-party ID, allowed origins, and display name, including their effects on existing passkeys.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Possibly related issues

  • layer5io/docs#1382 requests documentation for passkey sign-in, privileged-action windows, and self-hosted relying-party settings. This PR updates those documentation topics.

Suggested labels: component/cloud-docs

Suggested reviewers: miacycle, thebeginner86, leecalcote

Merge Risk: Minimal · previous review 1771b

This is a documentation-only update on passkey sign-in, sessions, and self-hosted configuration. No concrete defect was established, so it is low risk to merge.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title "docs(cloud): document passkey sign-in for Layer5 Cloud accounts and self-hosted identity" matches the main change. The PR adds passkey sign-in and management documentation to the account gu…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title "docs(cloud): document passkey sign-in for Layer5 Cloud accounts and self-hosted identity" matches the main change. The PR adds passkey sign-in and management documentation to the account guide, the Sessions page, and the self-hosted identity-services page, and it corrects the privileged-action window. The title names the scope (Layer5 Cloud accounts and self-hosted identity) and the change type (docs), so a reviewer scanning history can identify the primary change. It does not mention the session-window correction, which is a secondary change.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 486b7dcd-dca1-45ab-a225-5456c29ca822
Commits

Reviewing files that changed from the base of the PR and between b9e6826 and 1771b86.

Files selected for processing: 3

  • content/en/cloud/concepts/identity-and-security/sessions.md
  • content/en/cloud/getting-started/getting-started-with-layer5-account.md
  • content/en/cloud/guides/self-hosted/planning/identity-services/index.md

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

@github-actions

Copy link
Copy Markdown
Contributor

🚀 Preview deployment: https://docs.layer5.io/pr-preview/pr-1383/

Note: Preview may take a moment (GitHub Pages deployment in progress). Please wait and refresh. Track deployment here

… origins

Signed-off-by: hortison <160366376+hortison@users.noreply.github.com>
Signed-off-by: hortison <160366376+hortison@users.noreply.github.com>
@yi-nuo426
yi-nuo426 force-pushed the docs/passkeys-sign-in branch from 1771b86 to 677e0c1 Compare November 20, 2026 22:12
@yi-nuo426
yi-nuo426 merged commit ba3c6ee into master Nov 20, 2026
5 checks passed
@yi-nuo426
yi-nuo426 deleted the docs/passkeys-sign-in branch November 20, 2026 22:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants