Skip to content

Commit cc9ece2

Browse files
jhickmanitclaudewassimoo
authored
docs: document passkey advanced configuration options (ory#2519)
* docs(kratos): document passkey advanced configuration options Add an 'Advanced configuration' section under the dedicated passkey strategy that documents: - authenticator_selection (attachment, require_resident_key, user_verification) - attestation (preference, allow_none, allow_self, allow_untrusted) - timeouts (registration, login) Include a warning admonition explaining that disabling attestation.allow_none rejects most consumer passkeys, and add a three-tab example (Ory CLI, Ory Network, self-hosted Kratos) showing cross-platform attachment with required user verification. * docs: update passkey options to match final Kratos API The Kratos PR moved to a simpler API shape after review: - resident_key enum replaces the require_resident_key boolean (values: required, preferred, discouraged; default required) - attestation.policy enum replaces the three allow_* booleans (values: allow_untrusted, allow_self, allow_none; default allow_untrusted) - authenticator_selection.attachment no longer defaults to "platform"; omit it to accept either platform or cross-platform authenticators Rewrite the warning admonition to match the new policy semantics and note that Kratos does not verify attestation certificate chains today, so "allow_self" and "allow_none" are opt-in stricter stances rather than cryptographic validation. Update the self-hosted example to use the new field names. * docs: prettier * docs: drop passkey attestation.policy section Policy knob was removed from the Kratos PR because Kratos has no trust-anchor verification, so strict policy levels did not provide cryptographic validation. Docs now only describe the ceremony options that shipped: authenticator_selection, attestation.preference, timeouts. * docs: reconcile passkey advanced config with shipped Kratos API Adds the missing default-behavior callout (attachment was hardcoded "platform", now defaults to no preference) and clarifies that attestation.preference is request-only — Kratos does not verify or enforce the returned attestation statement. Also corrects the timeouts defaults (5m with user verification, 2m without). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: clarify passkey timeout enforcement and soften advanced-config intro - Note that timeouts.registration/login are browser-enforced; flow lifespans govern server-side validity - Reword section intro so it no longer contradicts the attachment default-change note - Precise wording for the library default timeout values Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: address review feedback on passkey advanced config - Fold the timeouts and attestation notes into the options table per reviewer request; remove the standalone notes - Use 'Ory Kratos' (not 'Kratos') in the attestation/timeout copy - Reword intro ('settings', 'All are optional') and add a warning that changing these settings can lock out existing users (matches Console UI) - 'register using either platform or cross-platform' wording fix - Drop redundant default attribute from the duplicate TabItem in the enable-strategy tabs block Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com>
1 parent 9e311d5 commit cc9ece2

1 file changed

Lines changed: 76 additions & 1 deletion

File tree

‎docs/kratos/passwordless/05_passkeys.mdx‎

Lines changed: 76 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ Alternatively, use the Ory CLI to enable the passkey strategy:
9494
config:
9595
display_name: "My Display Name"`}</CodeBlock>
9696
</TabItem>
97-
<TabItem value="self-hosted" label="Self-hosted Ory Kratos" default>
97+
<TabItem value="self-hosted" label="Self-hosted Ory Kratos">
9898
<CodeBlock language="yaml" title="config.yml">{`selfservice:
9999
methods:
100100
passkey:
@@ -111,6 +111,81 @@ Alternatively, use the Ory CLI to enable the passkey strategy:
111111
</Tabs>
112112
```
113113

114+
### Advanced configuration
115+
116+
The passkey strategy exposes additional settings that control the WebAuthn ceremony. All are optional and existing passkey
117+
credentials keep working. One default changed — see the note on authenticator attachment below.
118+
119+
:::warning
120+
121+
Changing these settings can prevent existing users from signing in with passkeys they already registered. Review the impact before
122+
changing them in production.
123+
124+
:::
125+
126+
| Option | Type | Default | What it controls |
127+
| ------------------------------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
128+
| `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. |
129+
| `authenticator_selection.resident_key` | string | `"required"` | Whether the authenticator must create a client-side discoverable credential: `"required"`, `"preferred"`, or `"discouraged"`. |
130+
| `authenticator_selection.user_verification` | string | `"preferred"` | Whether biometrics or a PIN are required: `"required"`, `"preferred"`, or `"discouraged"`. |
131+
| `attestation.preference` | string | `"none"` | Attestation conveyance preference that Ory Kratos _requests_ from the authenticator: `"none"`, `"indirect"`, `"direct"`, or `"enterprise"`. Request hint only — Ory Kratos does not verify or enforce the returned attestation statement, so it cannot restrict registration to specific authenticator types or models. Most consumer passkeys (iOS, Android) support only `"none"`; requesting `"direct"` or `"enterprise"` may not be honored. |
132+
| `timeouts.registration` | duration | library default | Timeout for the registration ceremony, in Go duration format (for example `"60s"` or `"5m"`). The browser enforces this during the ceremony; Ory Kratos does not reject late responses server-side — the flow lifespan (`selfservice.flows.*.lifespan`) governs server-side validity. When unset, the library default applies: 5 minutes, or 2 minutes when `user_verification` is set to `"discouraged"`. |
133+
| `timeouts.login` | duration | library default | Timeout for the login ceremony, in Go duration format. The browser enforces it like `timeouts.registration`. When unset, the library default applies: 5 minutes, or 2 minutes when `user_verification` is set to `"discouraged"`. |
134+
135+
:::note
136+
137+
**Default behavior change:** Earlier versions of the passkey strategy hardcoded `attachment: platform`, so only built-in
138+
authenticators (Touch ID, Windows Hello) could be registered. The strategy now defaults to **no attachment preference**, which
139+
means users can register using either platform or cross-platform (roaming) authenticators. To restore the previous behavior, set
140+
`authenticator_selection.attachment` to `"platform"`.
141+
142+
:::
143+
144+
The following example configures cross-platform authenticators (such as a HID token or YubiKey) with required user verification:
145+
146+
```mdx-code-block
147+
<Tabs>
148+
<TabItem value="cli" label="Ory CLI">
149+
<CodeBlock language="shell">{`ory patch identity-config <your-project-id> \\
150+
--add '/selfservice/methods/passkey/config/authenticator_selection/attachment="cross-platform"' \\
151+
--add '/selfservice/methods/passkey/config/authenticator_selection/user_verification="required"'
152+
`}
153+
</CodeBlock>
154+
</TabItem>
155+
<TabItem value="network" label="Ory Network" default>
156+
<CodeBlock language="yaml" title="config.yml">{`selfservice:
157+
methods:
158+
passkey:
159+
enabled: true
160+
config:
161+
authenticator_selection:
162+
attachment: cross-platform
163+
user_verification: required`}</CodeBlock>
164+
</TabItem>
165+
<TabItem value="self-hosted" label="Self-hosted Ory Kratos">
166+
<CodeBlock language="yaml" title="config.yml">{`selfservice:
167+
methods:
168+
passkey:
169+
enabled: true
170+
config:
171+
rp:
172+
display_name: Your Application name
173+
id: localhost
174+
origins:
175+
- http://localhost:4455
176+
authenticator_selection:
177+
attachment: cross-platform
178+
resident_key: required
179+
user_verification: required
180+
attestation:
181+
preference: none
182+
timeouts:
183+
registration: 5m
184+
login: 5m`}</CodeBlock>
185+
</TabItem>
186+
</Tabs>
187+
```
188+
114189
### Identity schema
115190

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

0 commit comments

Comments
 (0)