Skip to content

docs: document passkey advanced configuration options #2519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jhickmanit wants to merge 4 commits into
base: master
Choose a base branch
from
+59 −0
Open

docs: document passkey advanced configuration options #2519

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4536462
docs(kratos): document passkey advanced configuration options
jhickmanit Apr 21, 2026
9a98779
docs: update passkey options to match final Kratos API
jhickmanit Apr 22, 2026
7e273fe
docs: prettier
jhickmanit Apr 22, 2026
e17e24e
docs: drop passkey attestation.policy section
jhickmanit Apr 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions docs/kratos/passwordless/05_passkeys.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,65 @@ Alternatively, use the Ory CLI to enable the passkey strategy:
</Tabs>
```

### Advanced configuration

The passkey strategy exposes additional options that control the WebAuthn ceremony. All options are optional. Defaults accept
every standards-compliant passkey, so existing deployments do not need to change anything.

| Option | Type | Default | What it controls |
| ------------------------------------------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authenticator_selection.attachment` | string | _unset_ | Restricts eligible authenticators by attachment modality: `"platform"` (Touch ID, Windows Hello) or `"cross-platform"` (HID tokens, YubiKeys). Omit this field to accept either type. |
| `authenticator_selection.resident_key` | string | `"required"` | Whether the authenticator must create a client-side discoverable credential: `"required"`, `"preferred"`, or `"discouraged"`. |
| `authenticator_selection.user_verification` | string | `"preferred"` | Whether biometrics or a PIN are required: `"required"`, `"preferred"`, or `"discouraged"`. |
| `attestation.preference` | string | `"none"` | Attestation conveyance preference sent to the authenticator: `"none"`, `"indirect"`, `"direct"`, or `"enterprise"`. |
| `timeouts.registration` | duration | library default (5m) | Timeout for the registration ceremony. Use Go duration format, for example `"60s"` or `"5m"`. |
| `timeouts.login` | duration | library default (5m) | Timeout for the login ceremony. Use Go duration format. |

The following example configures cross-platform authenticators (such as a HID token or YubiKey) with required user verification:

```mdx-code-block
<Tabs>
<TabItem value="cli" label="Ory CLI">
<CodeBlock language="shell">{`ory patch identity-config <your-project-id> \\
--add '/selfservice/methods/passkey/config/authenticator_selection/attachment="cross-platform"' \\
--add '/selfservice/methods/passkey/config/authenticator_selection/user_verification="required"'
`}
</CodeBlock>
</TabItem>
<TabItem value="network" label="Ory Network" default>
<CodeBlock language="yaml" title="config.yml">{`selfservice:
methods:
passkey:
enabled: true
config:
authenticator_selection:
attachment: cross-platform
user_verification: required`}</CodeBlock>
</TabItem>
<TabItem value="self-hosted" label="Self-hosted Ory Kratos">
<CodeBlock language="yaml" title="config.yml">{`selfservice:
Comment on lines +139 to +150
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 21, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

In Docusaurus MDX Tabs (@theme/Tabsand@theme/TabItem), is it valid to mark more than one TabItemasdefault? If multiple are marked, which one is selected?

💡 Result:

If you mark more than one with the default prop inside a Docusaurus , it is not treated as a set of multiple defaults. Only one tab value is selected. Which one is selected: the first TabItem (in document order) whose TabItem/default=true is found. Reasoning (based on Docusaurus implementation): Tabs computes the initial selected value by scanning tabValues and using tabValues.find((tabValue) => tabValue.default) (falling back to the first tab if none are marked). Array.find returns the first matching element, so if multiple TabItems have default, the earliest one in the rendered children list wins. If none are marked default, the first tab is shown.

Citations:

Remove the redundant default property from the second TabItem.

Both TabItem entries at lines 152 and 162 are marked default. Docusaurus selects the first tab marked as default in document order, making the second one redundant. Keep the default on the first tab only (line 152: "Ory Network").

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/kratos/passwordless/05_passkeys.mdx` around lines 152 - 163, The second
TabItem element (the one with value="self-hosted" / label="Self-hosted Ory
Kratos") should not include the default attribute because Docusaurus uses the
first default in document order; remove the redundant default from that TabItem
and keep default only on the first TabItem (value="network" / label="Ory
Network") so tabs behave correctly.

methods:
passkey:
enabled: true
config:
rp:
display_name: Your Application name
id: localhost
origins:
- http://localhost:4455
authenticator_selection:
attachment: cross-platform
resident_key: required
user_verification: required
attestation:
preference: none
timeouts:
registration: 5m
login: 5m`}</CodeBlock>
</TabItem>
</Tabs>
```

### Identity schema

If you want to use a custom identity schema, you must define which field of the identity schema is the display name for the
Expand Down
Loading