https://www.ory.sh/ logo
Join Slack
Powered by
<@U04UQ68083H> Hey, guide me through passkeys. We ...
# ory-copilot
w
@chilly-king-10285 Hey, guide me through passkeys. We have 3 platforms (IOS mobile, Android mobile, and Web) for all of these I want use passkeys. We use self-hosted ORY Kratos
b
A message from kapa.ai
Certainly! Here’s a focused guide to enabling passkeys (passwordless authentication using WebAuthn) across iOS, Android, and Web with self-hosted Ory Kratos: --- ## 1. Understanding Passkeys & WebAuthn - Passkeys are a user-friendly implementation of the WebAuthn standard, allowing passwordless authentication using public key cryptography. - They are supported by major platforms (Apple, Google, Microsoft) and work across devices and browsers that implement WebAuthn. - Passkeys can be used for both platform (device-integrated, e.g., FaceID, TouchID) and cross-platform (e.g., YubiKey, phone as authenticator) authentication scenarios [Passkeys & WebAuthN](https://www.ory.sh/docs/kratos/passwordless/passkeys). --- ## 2. Platform Support & Constraints - WebAuthn is a browser standard: It works in browsers on all platforms, but does not work in native mobile apps directly. For mobile, you typically use a WebView or open a browser window for authentication [WebAuthn constraints](https://www.ory.sh/docs/kratos/passwordless/passkeys#constraints). - Cross-device login: Passkeys can be used across devices via BLE, QR code, or platform-specific sync (e.g., iCloud Keychain, Google Password Manager) [Logging in with a passkey across multiple devices](https://www.ory.sh/docs/kratos/passwordless/passwordless#logging-in-with-a-passkey-across-multiple-devices). --- ## 3. Enabling Passkeys in Self-hosted Ory Kratos ### Configuration In your 
config.yml
for Kratos, enable the passkey strategy:
Copy code
yaml selfservice:   methods:     passkey:       enabled: true       config:         rp:           display_name: "Your Application Name"           id: <http://your-domain.com|your-domain.com>           origins:             - <https://your-domain.com>
- `display_name`: What users see in the passkey prompt. - `id`: The top-level domain. - `origins`: The exact URLs where authentication is initiated (must include scheme, host, and port if not 443/80) [Passkeys with the dedicated passkey strategy](https://www.ory.sh/docs/kratos/passwordless/passkeys#passkeys-with-the-dedicated-passkey-strategy). ### Identity Schema If you use a custom identity schema, mark the field (e.g., email) as the display name for passkeys:
Copy code
json {   "traits": {     "email": {       "type": "string",       "format": "email",       "<http://ory.sh/kratos|ory.sh/kratos>": {         "credentials": {           "passkey": {             "display_name": true           }         }       }     }   } }
[Identity schema example](https://www.ory.sh/docs/kratos/passwordless/passkeys#passkeys-with-the-dedicated-passkey-strategy) --- ## 4. Implementation for Each Platform ### Web - Use the browser’s built-in WebAuthn API. - Ory provides a JavaScript file (
/.well-known/ory/webauthn.js
) to help with the flow. Add it to your login page and use the provided handlers to trigger passkey authentication [Custom UI integration](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-advanced-integration#passwordless-authentication). ### iOS & Android - Native apps cannot use WebAuthn directly. Instead, open a browser window (e.g., using ASWebAuthenticationSession on iOS or Chrome Custom Tabs on Android) to perform the authentication flow. - After authentication, handle the redirect back to your app using Universal Links (iOS) or App Links (Android) [Social sign-in for native and mobile apps](https://www.ory.sh/docs/kratos/social-signin/native-apps). - You can use Ory’s [React Native reference implementation](https://github.com/ory/kratos-selfservice-ui-react-native) as a starting point for integrating authentication flows in mobile apps [React Native integration guide](https://www.ory.sh/docs/getting-started/integrate-auth/react-native). --- ## 5. User Experience - On all platforms, users will see a browser prompt to use a passkey (e.g., FaceID, TouchID, device PIN, or external security key). - Passkeys can be shared across devices within the same ecosystem (e.g., iCloud Keychain for Apple devices) or used cross-platform via BLE or QR code [Cross-Platform Passkeys](https://www.ory.sh/blog/overview-login-password-passkey-webauthn-totp-sso-faceid). --- ## 6. Important Notes - **WebAuthn does not work in native mobile apps directly**; always use a browser-based flow for passkey authentication on mobile. - Ensure your origins and redirect URIs are correctly configured for all platforms. - Test the flow on all target devices and browsers to ensure a smooth user experience. --- If you need more detailed code samples or have a specific framework in mind, let me know!
w
Ok, how can i test the whole flow using my browser
@chilly-king-10285 Ok, how can i test the whole flow using my browser
b
A message from kapa.ai
To test the passkey (WebAuthn) authentication flow in your browser with self-hosted Ory Kratos, follow these steps: --- ### 1. Enable Passkey Authentication in Kratos Update your 
config.yml
to enable the passkey strategy:
Copy code
yaml selfservice:   methods:     passkey:       enabled: true       config:         rp:           display_name: "Your Application Name"           id: localhost           origins:             - <http://localhost:4455>
Make sure to restart Kratos after updating the configuration. [See configuration details](https://www.ory.sh/docs/kratos/passwordless/passkeys#passkeys-with-the-dedicated-passkey-strategy) --- ### 2. Prepare Your Identity Schema If you use a custom identity schema, ensure the field you want as the display name for passkeys is marked accordingly:
Copy code
json {   "traits": {     "email": {       "type": "string",       "format": "email",       "<http://ory.sh/kratos|ory.sh/kratos>": {         "credentials": {           "passkey": {             "display_name": true           }         }       }     }   } }
[Identity schema example](https://www.ory.sh/docs/kratos/passwordless/passkeys#passkeys-with-the-dedicated-passkey-strategy) --- ### 3. Start the Self-Service Flow in Your Browser - Open your browser and navigate to your login or registration page (e.g., `http://localhost:4455/login`). - The UI should present an option to use a passkey (if you use Ory’s default UI or have implemented passkey support in your custom UI). --- ### 4. Complete the Flow - When you select the passkey option, your browser will prompt you to register or use a passkey (e.g., FaceID, TouchID, Windows Hello, or a security key). - Follow the browser prompts to complete registration or login. --- ### 5. Verify the Flow - On successful authentication, you should be redirected to your application’s dashboard or the configured return URL. - If there are errors, Kratos will return them in the flow response, and your UI should display them accordingly. --- Note: If you are building a custom UI, you may need to integrate the WebAuthn JavaScript API and handle the flow as described in the Ory documentation. The default Ory UI already supports passkeys if enabled in your configuration. --- This process allows you to test the full passkey flow end-to-end in your browser using your self-hosted Ory Kratos instance. If you need to see the exact API calls or want to use cURL for testing, let me know!
w
@chilly-king-10285 I having error with message "additionalProperties "passkey" not allowed" My config is following
Copy code
passkey:
      enabled: true
      config:
        rp:
          display_name: Test local env.
          # Set 'id' to the top-level domain.
          id: local.test.tech
          # Set 'origin' to the exact URL of the page that prompts the user to use WebAuthn. You must include the scheme, host, and port.
          origins:
            - <http://resr.local.alx.tech:3000/login>
b
A message from kapa.ai
The error message 
"additionalProperties 'passkey' not allowed"
typically indicates an issue with your identity schema, not your Kratos configuration. This happens when you add a 
passkey
property to a field in your identity schema, but the schema does not allow additional properties. For example, if your identity schema looks like this:
Copy code
json {   "traits": {     "email": {       "type": "string",       "format": "email",       "<http://ory.sh/kratos|ory.sh/kratos>": {         "credentials": {           "passkey": {             "display_name": true           }         }       }     }   } }
But you have 
"additionalProperties": false
set somewhere in your schema (often inside the 
traits
object), then any property not explicitly listed (like 
passkey
) will cause this error. How to fix: - Make sure that the 
<http://ory.sh/kratos|ory.sh/kratos>
extension is inside the 
email
property, not at the same level as 
traits
. - If you have 
"additionalProperties": false
in your schema, ensure that the 
<http://ory.sh/kratos|ory.sh/kratos>
property is explicitly allowed. Example fix:
Copy code
json {   "type": "object",   "properties": {     "traits": {       "type": "object",       "properties": {         "email": {           "type": "string",           "format": "email",           "<http://ory.sh/kratos|ory.sh/kratos>": {             "credentials": {               "passkey": {                 "display_name": true               }             }           }         }       },       "required": ["email"],       "additionalProperties": false     }   } }
If you want to allow the 
<http://ory.sh/kratos|ory.sh/kratos>
property, you may need to adjust your schema to permit it as an additional property or explicitly define it. See the [Ory documentation on customizing identity schemas for passkeys](https://www.ory.sh/docs/kratos/manage-identities/customize-identity-schema#passkey-display-name) for more details. Summary: The error is not with your Kratos config, but with your identity schema's handling of additional properties. Adjust your schema as shown above to resolve the issue. [Reference: Passkey display name in identity schema](https://www.ory.sh/docs/kratos/manage-identities/customize-identity-schema#passkey-display-name)
w
@chilly-king-10285 here is my schema { "$id": "https://schemas.ory.sh/presets/kratos/dealer_v2.email.schema.json", "title": "Person", "type": "object", "properties": { "traits": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "title": "E-Mail", "ory.sh/kratos": { "credentials": { "password": { "identifier": true }, "webauthn": { "identifier": true }, "totp": { "account_name": true } }, "recovery": { "via": "email" }, "verification": { "via": "email" } }, "maxLength": 320 }, "appleId": { "type": "string", "maxLength": 320 }, "googleId": { "type": "string", "maxLength": 320 }, "microsoftId": { "type": "string", "maxLength": 320 }, "phoneNumber": { "type": "string", "format": "tel" }, "countryCode": { "title": "Country", "type": "string", "enum": ["ES", "FR", "GB", "IT", "PL", "PT"] }, "providerId": { "type": "string", "enum": [ "google-web-test", "google-web-test2", "google-ios", "google-android", "microsoft", "apple" ] }, "name": { "type": "object", "properties": { "first": { "title": "First name", "type": "string" }, "last": { "title": "Last name", "type": "string" } } }, "dateOfBirth": { "title": "Date of birth", "type": "string", "format": "date" } }, "additionalProperties": false } } }
b
A message from kapa.ai
Your schema is missing the passkey configuration under the 
<http://ory.sh/kratos|ory.sh/kratos>
extension for the 
email
field. To enable passkey support, you need to add the 
passkey
property as shown in the Ory documentation. Also, ensure that the property name is exactly 
"<http://ory.sh/kratos|ory.sh/kratos>"
(not a URL or Markdown link). Here is how your 
email
field should look, based on the official documentation:
Copy code
json "email": {   "type": "string",   "format": "email",   "title": "E-Mail",   "<http://ory.sh/kratos|ory.sh/kratos>": {     "credentials": {       "password": {         "identifier": true       },       "webauthn": {         "identifier": true       },       "totp": {         "account_name": true       },       "passkey": {         "display_name": true       }     },     "recovery": {       "via": "email"     },     "verification": {       "via": "email"     }   },   "maxLength": 320 }
Key points: - The property must be 
"<http://ory.sh/kratos|ory.sh/kratos>"
, not 
"<http://ory.sh/kratos|ory.sh/kratos>"
. - Add the 
"passkey": { "display_name": true }
block under 
credentials
for the 
email
field. This matches the structure shown in the Ory documentation for enabling passkeys in your identity schema [Passkey display name](https://www.ory.sh/docs/kratos/manage-identities/customize-identity-schema#passkey-display-name) and [Passkeys with the dedicated passkey strategy](https://www.ory.sh/docs/kratos/passwordless/passkeys#passkeys-with-the-dedicated-passkey-strategy). If you update your schema as above, the 
"additionalProperties 'passkey' not allowed"
error should be resolved.
w
@chilly-king-10285 the issue persists, the version of my Kratos is v1.2.0. Does it support passkey ?
b
A message from kapa.ai
Based on the available knowledge sources, Ory Kratos supports the passkey strategy (dedicated passkey method) and related identity schema extensions as of version v1.3.1 and in the current documentation. However, there is no explicit information in the knowledge sources confirming that Ory Kratos v1.2.0 supports the dedicated passkey strategy or the required identity schema extensions for passkeys. The documentation and user reports reference passkey support and configuration in v1.3.1 and later, and there are no clear indications that these features are available or stable in v1.2.0. For example, a user in a GitHub issue about YubiKey and passkey strategy references v1.3.1 and the relevant documentation, but there is no mention of v1.2.0 in relation to passkey support. This suggests that passkey support may not be fully available or may be incomplete in v1.2.0 [Unable to use YubiKey with passkey strategy](https://github.com/ory/kratos/issues/4377). In summary: I'm sorry, but the knowledge sources do not explicitly confirm that Ory Kratos v1.2.0 supports the passkey strategy. The features and schema extensions for passkeys are documented for v1.3.1 and later. If you require passkey support, you may need to upgrade to a newer version of Ory Kratos.
w
@chilly-king-10285 yes, that was about version. Is there way to integrate passkey + kratos with native app using flatter ? Maybe there is some sdk exists and we don't need to use WebView
b
A message from kapa.ai
Based on the knowledge sources, there is currently no way to integrate passkey (WebAuthn) authentication with Ory Kratos in a native Flutter app without using a browser or WebView. Key points from the documentation and community discussions: - WebAuthn is a browser-only standard. It does not work in native mobile apps directly. The Ory documentation and multiple sources explicitly state that WebAuthn (and thus passkeys) require browser APIs and cannot be used natively in mobile apps, including Flutter apps. You must use a browser-based flow (e.g., open a browser window or WebView) for authentication on mobile devices [WebAuthn and FIDO2 (YubiKey)](https://www.ory.sh/docs/kratos/mfa/webauthn-fido-yubikey), [Passkeys & WebAuthN Constraints](https://www.ory.sh/docs/kratos/passwordless/passkeys#constraints), [Github Issue: Flutter native app and biometric authentication](https://github.com/ory/network/issues/284). - No native Flutter SDK for passkeys with Kratos. There is no mention of a Flutter SDK or package that enables native passkey/WebAuthn integration with Ory Kratos. The only available approach is to use a browser-based flow, as described above. - Workaround: The recommended approach is to open a browser window (using platform-specific APIs like ASWebAuthenticationSession on iOS or Chrome Custom Tabs on Android) from your Flutter app to perform the authentication, then handle the redirect back to your app [Social sign-in for native and mobile apps](https://www.ory.sh/docs/kratos/social-signin/native-apps). Summary: You cannot use passkeys/WebAuthn natively in a Flutter app with Ory Kratos. You must use a browser-based flow for authentication. There is no SDK that enables native passkey integration with Kratos at this time. If you need biometric authentication natively in Flutter, you would need to implement it separately from Ory Kratos, and it would not be integrated with Kratos' authentication/session management.
w
@chilly-king-10285 In order to register new passkey user have to be authenticated ? Or it's can be done for non-authenticated users too ?
b
A message from kapa.ai
In Ory Kratos, registering a new passkey can be done as part of the registration flow, which does not require the user to be authenticated. The registration flow is designed for new users who are not yet logged in, and passkey (WebAuthn) can be used as a registration method in this context. The API documentation for the registration flow explicitly states that authentication is not required for this operation [Kratos API Reference – getRegistrationFlow](https://www.ory.sh/docs/kratos/reference/api) [Kratos API Reference – updateRegistrationFlow](https://www.ory.sh/docs/kratos/reference/api). In contrast, adding a new passkey to an existing account (for example, as a second factor or additional credential) would be done through the settings flow, which does require the user to be authenticated. Summary: - Registering a new passkey during user registration: No authentication required. - Adding a passkey to an existing account (settings): User must be authenticated. This is confirmed by the API documentation, which states that the registration flow does not require authentication [Kratos API Reference – getRegistrationFlow](https://www.ory.sh/docs/kratos/reference/api).
w
@chilly-king-10285 what about users that already exists in Kratos, but not currently authenticated. Is it possible to them register new passkey via login flow or they must login first
b
A message from kapa.ai
For users who already exist in Kratos but are not currently authenticated, they cannot register a new passkey without first authenticating. According to the Ory Kratos flow design, registering a new passkey as a credential for an existing account is handled through the settings flow, which requires the user to be authenticated (i.e., logged in) [Kratos API Reference – updateSettingsFlow](https://www.ory.sh/docs/kratos/reference/api). The login flow is intended for authenticating users using existing credentials (such as password, passkey, code, etc.), not for registering new credentials. The ability to add or register a new passkey for an existing user is only available in the settings flow, which is protected and requires a valid session [Kratos API Reference – updateSettingsFlow](https://www.ory.sh/docs/kratos/reference/api). In summary: - Existing users who are not authenticated must log in first. - Only after authentication can they register a new passkey via the settings flow. If you need to allow users to register a new passkey, they must be logged in to access the settings flow. There is no support in the knowledge sources for registering a new passkey for an existing user via the login flow.
w
@chilly-king-10285 Could you explain to me what is opt.spublickKey.user.id is ? It's part of webauthn.js script and related to passkey creation flow
Copy code
let opts = createData.credentialOptions
    opts.publicKey.user.name = displayName
    opts.publicKey.user.displayName = displayName
    opts.publicKey.user.id = __oryWebAuthnBufferDecode(opts.publicKey.user.id)
    opts.publicKey.challenge = __oryWebAuthnBufferDecode(
      opts.publicKey.challenge,
    )
b
A message from kapa.ai
I'm sorry, but the knowledge sources do not contain explicit information about the meaning or structure of 
opts.publicKey.user.id
in the context of the 
webauthn.js
script or the passkey creation flow. However, based on the context provided in your code snippet and the general WebAuthn flow described in the Ory documentation, 
opts.publicKey.user.id
is likely a value used to uniquely identify the user during the WebAuthn registration process. In the WebAuthn standard, the 
user.id
field is a binary identifier that must be unique for each user within your application. The script decodes this value from a buffer before passing it to the WebAuthn API, which is a standard step in preparing the registration options for the browser's WebAuthn API. If you need more detailed or authoritative information about this field specifically in Ory's implementation, it is not available in the provided knowledge sources. For more details, you may want to consult the [official WebAuthn specification](https://w3c.github.io/webauthn/) or Ory's source code and documentation directly.
w
@chilly-king-10285 what flows should i use in order to create and user passkey ? (From Kratos side). Something like 
/self-service/settings/browser
, 
/self-service/login/browser
 , 
/self-service/registratio/browser
b
A message from kapa.ai
To create and use a passkey (WebAuthn credential) with Ory Kratos, you should use the following self-service flows, depending on the user's context: 1. Registration Flow (
/self-service/registration/browser
): Use this flow to allow new users to register with a passkey. This does not require the user to be authenticated. The registration flow can be initialized for browser-based clients, and the passkey method can be enabled as part of the registration process [Registration Flow](https://www.ory.sh/docs/kratos/self-service/flows/user-registration). 2. Login Flow (
/self-service/login/browser
): Use this flow to allow existing users to log in using a passkey. The login flow supports multiple authentication methods, including passkey, and is intended for users who already have a passkey registered with their account [Login Flow](https://www.ory.sh/docs/kratos/self-service/flows/user-login). 3. Settings Flow (
/self-service/settings/browser
): Use this flow to allow authenticated users to add (register) a new passkey to their existing account. The settings flow is only available to users who are already logged in [Settings Flow](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#user-and-profile-settings-for-server-side-browser-clients). Summary Table: | Flow Type | Endpoint | When to Use | |--------------|---------------------------------------|--------------------------------------------------| | Registration | 
/self-service/registration/browser
| New user registering with a passkey | | Login | 
/self-service/login/browser
| Existing user logging in with a passkey | | Settings | 
/self-service/settings/browser
| Authenticated user adding a new passkey | These flows are the standard way to create and use passkeys in Ory Kratos for browser-based applications [Self-service flows overview](https://www.ory.sh/docs/kratos/self-service#performing-login-registration-settings--flows).
A message from kapa.ai
To create and use a passkey with Ory Kratos, you should use the following self-service flows: - Registration Flow (
/self-service/registration/browser
): Use this flow to allow new users to register with a passkey. This flow does not require the user to be authenticated and is intended for new account creation using passkey as an authentication method [Registration](https://www.ory.sh/docs/kratos/self-service/flows/user-registration). - Login Flow (
/self-service/login/browser
): Use this flow to allow existing users to log in with a passkey. This is for users who have already registered a passkey and want to authenticate using it [Login](https://www.ory.sh/docs/kratos/self-service/flows/user-login). - Settings Flow (
/self-service/settings/browser
): Use this flow to allow authenticated users to add (register) a new passkey to their existing account. This flow is only available to users who are already logged in [User and profile settings](https://www.ory.sh/docs/kratos/self-service/flows/user-settings). These are the standard flows in Ory Kratos for creating and using passkeys in browser-based applications [Self-service flows](https://www.ory.sh/docs/kratos/self-service#performing-login-registration-settings--flows).
A message from kapa.ai
To create and use a passkey in Ory Kratos, you should use the following self-service flows: - Registration Flow (
/self-service/registration/browser
): Use this flow to allow new users to register with a passkey. This is for users who do not yet have an account and want to use a passkey as their primary credential [Registration Flow](https://www.ory.sh/docs/kratos/self-service/flows/user-registration). - Login Flow (
/self-service/login/browser
): Use this flow to allow existing users to log in with a passkey. This is for users who have already registered a passkey and want to authenticate using it [Login Flow](https://www.ory.sh/docs/kratos/self-service/flows/user-login). - Settings Flow (
/self-service/settings/browser
): Use this flow to allow authenticated users to add (register) a new passkey to their existing account. This flow is only available to users who are already logged in [Settings Flow](https://www.ory.sh/docs/kratos/self-service/flows/user-settings). These flows are the standard way to create and use passkeys in Ory Kratos for browser-based applications [Self-service flows](https://www.ory.sh/docs/kratos/self-service#performing-login-registration-settings--flows).
A message from kapa.ai
To create and use a passkey in Ory Kratos, you should use the following self-service flows: - Registration Flow (
/self-service/registration/browser
): Use this flow to allow new users to register with a passkey. This flow is intended for users who do not yet have an account and want to use a passkey as their primary credential [Registration](https://www.ory.sh/docs/kratos/self-service/flows/user-registration). - Login Flow (
/self-service/login/browser
): Use this flow to allow existing users to log in with a passkey. This is for users who have already registered a passkey and want to authenticate using it [Login](https://www.ory.sh/docs/kratos/self-service/flows/user-login). - Settings Flow (
/self-service/settings/browser
): Use this flow to allow authenticated users to add (register) a new passkey to their existing account. This flow is only available to users who are already logged in [Settings](https://www.ory.sh/docs/kratos/self-service/flows/user-settings). These are the standard flows in Ory Kratos for creating and using passkeys in browser-based applications [Self-service flows](https://www.ory.sh/docs/kratos/self-service#performing-login-registration-settings--flows).
A message from kapa.ai
To create and use a passkey in Ory Kratos, you should use the following self-service flows: - Registration Flow (
/self-service/registration/browser
): Use this flow to allow new users to register with a passkey. This is for users who do not yet have an account and want to use a passkey as their primary credential [Registration](https://www.ory.sh/docs/kratos/self-service/flows/user-registration). - Login Flow (
/self-service/login/browser
): Use this flow to allow existing users to log in with a passkey. This is for users who have already registered a passkey and want to authenticate using it [Login](https://www.ory.sh/docs/kratos/self-service/flows/user-login). - Settings Flow (
/self-service/settings/browser
): Use this flow to allow authenticated users to add (register) a new passkey to their existing account. This flow is only available to users who are already logged in [Settings](https://www.ory.sh/docs/kratos/self-service/flows/user-settings). These flows are the standard way to create and use passkeys in Ory Kratos for browser-based applications [Self-service flows](https://www.ory.sh/docs/kratos/self-service#performing-login-registration-settings--flows).
w
@chilly-king-10285 tell me more about /self-service/registration/browser option. How i need to create passkey in this case ? What are my steps here
b
A message from kapa.ai
Certainly! Here’s how the 
/self-service/registration/browser
flow works in Ory Kratos, and how you would create a passkey as part of this flow: --- ### What is 
/self-service/registration/browser
? This endpoint initializes a browser-based registration flow. It sets up all necessary cookies and anti-CSRF measures for secure registration. When you visit this endpoint, Kratos will redirect you (or respond with JSON if using AJAX) to your registration UI, including a 
flow
ID in the URL. This flow object contains all the information needed to render the registration form, including available methods like password, OIDC, or passkey if enabled [Registration Flow](https://www.ory.sh/docs/kratos/self-service/flows/user-registration). --- ### Steps to Create a Passkey During Registration 1. Initialize the Registration Flow Open the registration endpoint in your browser:
Copy code
GET /self-service/registration/browser
This will redirect you to your registration UI with a 
?flow=<flow-id>
parameter [Create registration flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#create-registration-flow). 2. Render the Registration Form Fetch the registration flow data using the flow ID:
Copy code
GET /self-service/registration/flows?id=<flow-id>
The response will include the available registration methods (e.g., password, passkey) and the required form fields [Get registration flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#get-registration-flow). 3. User Chooses Passkey If passkey is enabled in your Kratos config and identity schema, the UI will present a passkey option. When the user selects this, your frontend should trigger the WebAuthn registration process using the options provided in the flow data. 4. Create the Passkey (WebAuthn Registration) The frontend uses the WebAuthn API (with the options from Kratos) to prompt the user to create a passkey (e.g., FaceID, TouchID, security key). The result is a credential that the browser returns to your frontend. 5. Submit the Registration Flow Send a POST request to:
Copy code
POST /self-service/registration?flow=<flow-id>
Include the passkey credential and any required traits (e.g., email) in the payload. The exact fields are specified in the flow’s 
ui.nodes
property [Submit registration flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#submit-registration-flow). 6. Registration Complete If successful, Kratos creates the new user with the passkey as their credential and redirects them to the configured post-registration URL. --- Summary: - Start the flow at 
/self-service/registration/browser
- Render the form using the flow data - Let the user create a passkey via WebAuthn - Submit the result to Kratos to complete registration This is the standard, secure way to register a new user with a passkey in Ory Kratos [Self-service flows](https://www.ory.sh/docs/kratos/self-service#performing-login-registration-settings--flows).
A message from kapa.ai
The 
/self-service/registration/browser
endpoint in Ory Kratos is used to initialize a browser-based registration flow. This flow is designed for new users to register, and it supports passkey (WebAuthn) as a registration method if enabled in your Kratos configuration and identity schema. ### Steps to Create a Passkey During Registration 1. Initialize the Registration Flow Open the registration flow by making a GET request to:
Copy code
/self-service/registration/browser
This will set the necessary cookies and anti-CSRF tokens. If accessed in a browser, it redirects to your registration UI with a 
flow
query parameter. If accessed via AJAX, it returns the flow data as JSON, including the available registration methods and required form fields [createBrowserRegistrationFlow](https://www.ory.sh/docs/kratos/reference/api). 2. Render the Registration Form Use the flow data (especially 
ui.nodes
) to render the registration form. If passkey is enabled, the form will include the option to register using a passkey. The fields and methods shown depend on your Kratos project configuration and identity schema [Custom UI with Ory Elements](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-ory-elements#login-and-registration-pages). 3. User Initiates Passkey Registration When the user selects the passkey option, your frontend should use the WebAuthn API with the options provided in the flow data to prompt the user to create a passkey (e.g., using FaceID, TouchID, or a security key) [Passkeys & WebAuthN](https://www.ory.sh/docs/kratos/passwordless/passkeys). 4. Submit the Registration Data After the user completes the passkey creation, submit the registration form to the action URL provided in the flow data (typically 
/self-service/registration?flow=<flow-id>
). The payload should include the passkey credential and any required traits (such as email), as specified in the flow’s 
ui.nodes
 [Submit registration flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#submit-registration-flow). 5. Registration Completion If the registration is successful, Kratos will create the new user with the passkey as their credential and redirect them to the configured post-registration URL. Note: The exact fields and steps may vary depending on your identity schema and project configuration. Always use the flow data (
ui.nodes
) to determine what needs to be rendered and submitted. For more details, see the [Ory Kratos registration flow documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-registration).
A message from kapa.ai
The 
/self-service/registration/browser
endpoint in Ory Kratos is used to initialize a browser-based registration flow. This flow is designed for new users to register, and it supports passkey (WebAuthn) as a registration method if enabled in your Kratos configuration and identity schema. ### Steps to Create a Passkey During Registration 1. Initialize the Registration Flow Make a GET request to 
/self-service/registration/browser
. This sets up the necessary cookies and anti-CSRF tokens. If accessed in a browser, it redirects to your registration UI with a 
flow
query parameter. If accessed via AJAX, it returns the flow data as JSON, including available registration methods and required form fields [createBrowserRegistrationFlow](https://www.ory.sh/docs/kratos/reference/api). 2. Render the Registration Form Use the flow data (especially 
ui.nodes
) to render the registration form. If passkey is enabled, the form will include the option to register using a passkey. The fields and methods shown depend on your Kratos project configuration and identity schema [Create registration flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#create-registration-flow). 3. User Initiates Passkey Registration When the user selects the passkey option, your frontend should use the WebAuthn API with the options provided in the flow data to prompt the user to create a passkey (e.g., using FaceID, TouchID, or a security key) [Passkeys & WebAuthN](https://www.ory.sh/docs/kratos/passwordless/passkeys). 4. Submit the Registration Data After the user completes the passkey creation, submit the registration form to the action URL provided in the flow data (typically 
/self-service/registration?flow=<flow-id>
). The payload should include the passkey credential and any required traits (such as email), as specified in the flow’s 
ui.nodes
 [Submit registration flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#submit-registration-flow). 5. Registration Completion If the registration is successful, Kratos will create the new user with the passkey as their credential and redirect them to the configured post-registration URL. Note: The exact fields and steps may vary depending on your identity schema and project configuration. Always use the flow data (
ui.nodes
) to determine what needs to be rendered and submitted. For more details, see the [Ory Kratos registration flow documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-registration).
A message from kapa.ai
To create and use a passkey in Ory Kratos, you should use the following self-service flows, depending on the user's context: - Registration Flow (
/self-service/registration/browser
): Use this flow to allow new users to register with a passkey. This is for users who do not yet have an account and want to use a passkey as their primary credential. The registration flow supports the passkey method if it is enabled in your configuration and identity schema [Registration](https://www.ory.sh/docs/kratos/self-service/flows/user-registration). - Login Flow (
/self-service/login/browser
): Use this flow to allow existing users to log in with a passkey. This is for users who have already registered a passkey and want to authenticate using it. The login flow supports multiple authentication methods, including passkey, if enabled [Login](https://www.ory.sh/docs/kratos/self-service/flows/user-login). - Settings Flow (
/self-service/settings/browser
): Use this flow to allow authenticated users to add (register) a new passkey to their existing account. This flow is only available to users who are already logged in [Settings](https://www.ory.sh/docs/kratos/self-service/flows/user-settings). These flows are the standard way to create and use passkeys in Ory Kratos for browser-based applications [Self-service flows](https://www.ory.sh/docs/kratos/self-service#performing-login-registration-settings--flows).
w
@chilly-king-10285 what about linking and un-linking oidc providers with users account ? For browser flow we can use /self-service/settings/browser endpoint and every needed nodes like link and unlink will be presented there. What can we use on mobile side for the same puspose ?
b
A message from kapa.ai
For linking and unlinking OIDC (social sign-in) providers to a user's account, the browser flow (
/self-service/settings/browser
) provides the necessary UI nodes (such as "link" and "unlink") for these actions. However, on the mobile (API) side, this functionality is currently not available. According to the Ory documentation and GitHub issues, social sign-in linking and unlinking is not supported in API-based settings flows (which are used by native and mobile apps). The documentation explicitly states: > Social Sign In is not possible for API Clients. It will be possible in a future version, which is partially tracked as [kratos#273](https://github.com/ory/kratos/issues/273) [Link and unlink from Google, Facebook, GitHub, ..., OpenID Connect / OAuth 2.0](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#link-and-unlink-from-google-facebook-github--openid-connect--oauth-20) Additionally, a GitHub issue confirms this limitation: > I believe this is a shortcoming of the API flows, and actually a missing feature. While we do support OIDC on native now, we never got around to also adding that support to the settings flow [Settings flow does not have 
link
option with OIDC & Password methods enabled](https://github.com/ory/kratos/issues/4185) Summary: - Browser: Use 
/self-service/settings/browser
for linking/unlinking OIDC providers. - Mobile/API: This feature is not currently supported for API-based flows. There is no official way to link or unlink OIDC providers from a native/mobile app at this time. If you need this feature for mobile, you will need to wait for future Ory Kratos releases that add support for OIDC linking/unlinking in API flows.
A message from kapa.ai
For linking and unlinking OIDC (social sign-in) providers to a user's account, the browser flow (
/self-service/settings/browser
) provides the necessary UI nodes for these actions. However, on the mobile (API) side, this functionality is currently not available. The Ory documentation explicitly states: > Social Sign In is not possible for API Clients. It will be possible in a future version, which is partially tracked as [kratos#273](https://github.com/ory/kratos/issues/273) [Link and unlink from Google, Facebook, GitHub, ..., OpenID Connect / OAuth 2.0](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#link-and-unlink-from-google-facebook-github--openid-connect--oauth-20) Additionally, a GitHub issue confirms this limitation: > I believe this is a shortcoming of the API flows, and actually a missing feature. While we do support OIDC on native now, we never got around to also adding that support to the settings flow [Settings flow does not have 
link
option with OIDC & Password methods enabled](https://github.com/ory/kratos/issues/4185) In summary: - Browser: Use 
/self-service/settings/browser
for linking/unlinking OIDC providers. - Mobile/API: This feature is not currently supported for API-based flows. There is no official way to link or unlink OIDC providers from a native/mobile app at this time.
A message from kapa.ai
For linking and unlinking OIDC (social sign-in) providers with a user's account, the browser flow (
/self-service/settings/browser
) exposes the necessary UI nodes (such as "link" and "unlink") for these actions. However, on the mobile (API) side, this functionality is currently not available. The Ory documentation clearly states: > Social Sign In is not possible for API Clients. It will be possible in a future version, which is partially tracked as [kratos#273](https://github.com/ory/kratos/issues/273) [Link and unlink from Google, Facebook, GitHub, ..., OpenID Connect / OAuth 2.0](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#link-and-unlink-from-google-facebook-github--openid-connect--oauth-20) Additionally, a GitHub issue confirms: > I believe this is a shortcoming of the API flows, and actually a missing feature. While we do support OIDC on native now, we never got around to also adding that support to the settings flow [Settings flow does not have 
link
option with OIDC & Password methods enabled](https://github.com/ory/kratos/issues/4185) In summary: - For browser-based applications, use 
/self-service/settings/browser
to link or unlink OIDC providers. - For mobile or native applications using the API flow, this feature is not currently supported. There is no official way to link or unlink OIDC providers from a native/mobile app at this time.
A message from kapa.ai
For linking and unlinking OIDC (social sign-in) providers with a user's account, the browser flow (
/self-service/settings/browser
) provides the necessary UI nodes for these actions. However, on the mobile (API) side, this functionality is currently not available. The Ory documentation explicitly states that: > Social Sign In is not possible for API Clients. It will be possible in a future version, which is partially tracked as [kratos#273](https://github.com/ory/kratos/issues/273) [Link and unlink from Google, Facebook, GitHub, ..., OpenID Connect / OAuth 2.0](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#link-and-unlink-from-google-facebook-github--openid-connect--oauth-20) Additionally, a GitHub issue confirms this limitation: > I believe this is a shortcoming of the API flows, and actually a missing feature. While we do support OIDC on native now, we never got around to also adding that support to the settings flow [Settings flow does not have 
link
option with OIDC & Password methods enabled](https://github.com/ory/kratos/issues/4185) In summary: - Browser: Use 
/self-service/settings/browser
for linking/unlinking OIDC providers. - Mobile/API: This feature is not currently supported for API-based flows. There is no official way to link or unlink OIDC providers from a native/mobile app at this time.
A message from kapa.ai
For linking and unlinking OIDC (social sign-in) providers with a user's account, the browser flow (
/self-service/settings/browser
) exposes the necessary UI nodes (such as "link" and "unlink") for these actions. On the mobile (API) side, this functionality is currently not available. The Ory documentation explicitly states: > Social Sign In is not possible for API Clients. It will be possible in a future version, which is partially tracked as [kratos#273](https://github.com/ory/kratos/issues/273) This means that, at present, there is no supported way to link or unlink OIDC providers from a native or mobile app using the API-based settings flow. This limitation is also confirmed in community discussions and GitHub issues, where it is described as a missing feature in the API flows for native/mobile clients [Link and unlink from Google, Facebook, GitHub, ..., OpenID Connect / OAuth 2.0](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#link-and-unlink-from-google-facebook-github--openid-connect--oauth-20) [Settings flow does not have 
link
option with OIDC & Password methods enabled](https://github.com/ory/kratos/issues/4185). Summary: - Browser: Use 
/self-service/settings/browser
for linking/unlinking OIDC providers. - Mobile/API: This feature is not currently supported for API-based flows. There is no official way to link or unlink OIDC providers from a native/mobile app at this time.
w
@chilly-king-10285 how can i do unlinking in native apps ? Since /self-service/settings/api not the case here
b
A message from kapa.ai
Currently, unlinking OIDC (social sign-in) providers from a user's account is not supported in native apps or API-based flows in Ory Kratos. The documentation explicitly states that social sign-in linking and unlinking is only available in the browser-based settings flow (
/self-service/settings/browser
). For API clients (such as native mobile apps), this feature is not yet implemented: > Social Sign In is not possible for API Clients. It will be possible in a future version, which is partially tracked as [kratos#273](https://github.com/ory/kratos/issues/273) [Link and unlink from Google, Facebook, GitHub, ..., OpenID Connect / OAuth 2.0](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#link-and-unlink-from-google-facebook-github--openid-connect--oauth-20) Additionally, this limitation is confirmed in community discussions and GitHub issues, where it is described as a missing feature for API/native flows [Settings flow does not have 
link
option with OIDC & Password methods enabled](https://github.com/ory/kratos/issues/4185). In summary: You cannot currently perform unlinking of OIDC providers in native apps using the API. This functionality is only available in the browser flow, and support for API/native flows is planned for a future release.
w
@chilly-king-10285 /self-service/registration/browser don't have any nodes for passkey creation or using.
b
A message from kapa.ai
If 
/self-service/registration/browser
does not present any nodes for passkey creation or usage, there are a few possible reasons based on the knowledge sources: 1. Passkey Method Not Enabled in Configuration The passkey method must be explicitly enabled in your Kratos configuration. Your 
config.yml
should include:
Copy code
yaml    selfservice:      methods:        passkey:          enabled: true          config:            rp:              display_name: "Your Application Name"              id: <http://your-domain.com|your-domain.com>              origins:                - <https://your-domain.com>
If this is missing or misconfigured, passkey nodes will not appear in the registration flow [Passkeys with the dedicated passkey strategy](https://www.ory.sh/docs/kratos/passwordless/passkeys#passkeys-with-the-dedicated-passkey-strategy). 2. Identity Schema Not Configured for Passkey Your identity schema must specify which field is used as the passkey display name. For example:
Copy code
json    {      "traits": {        "email": {          "type": "string",          "<http://ory.sh/kratos|ory.sh/kratos>": {            "credentials": {              "passkey": {                "display_name": true              }            }          }        }      }    }
If this is not set, the passkey method will not be available in the registration flow [Passkey display name in identity schema](https://www.ory.sh/docs/kratos/passwordless/passkeys#passkeys-with-the-dedicated-passkey-strategy). 3. Kratos Version Passkey support is only available in newer versions of Kratos (v1.3.1 and later). If you are using an older version (e.g., v1.2.0), passkey nodes will not be present, as this feature is not supported in that version [Unable to use YubiKey with passkey strategy](https://github.com/ory/kratos/issues/4377). 4. Flow Initialization and UI Rendering Ensure you are correctly initializing the registration flow and rendering all nodes from the 
ui.nodes
array in your custom UI. If your UI only renders certain methods or fields, passkey nodes may be omitted even if they are present in the flow data [Custom UI integration](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-advanced-integration#passwordless-authentication). If you have checked all of the above and passkey nodes still do not appear, it is likely due to version limitations or a misconfiguration in your identity schema or Kratos config. The knowledge sources do not provide additional troubleshooting steps beyond these points.
A message from kapa.ai
To create and use a passkey in Ory Kratos, you should use the following self-service flows, depending on the user's context: - Registration Flow (
/self-service/registration/browser
): Use this flow to allow new users to register with a passkey. This is for users who do not yet have an account and want to use a passkey as their primary credential. The registration flow supports the passkey method if it is enabled in your configuration and identity schema [Registration](https://www.ory.sh/docs/kratos/self-service/flows/user-registration). - Login Flow (
/self-service/login/browser
): Use this flow to allow existing users to log in with a passkey. This is for users who have already registered a passkey and want to authenticate using it. The login flow supports multiple authentication methods, including passkey, if enabled [Login](https://www.ory.sh/docs/kratos/self-service/flows/user-login). - Settings Flow (
/self-service/settings/browser
): Use this flow to allow authenticated users to add (register) a new passkey to their existing account. This flow is only available to users who are already logged in [Settings](https://www.ory.sh/docs/kratos/self-service/flows/user-settings). These flows are the standard way to create and use passkeys in Ory Kratos for browser-based applications [Self-service flows](https://www.ory.sh/docs/kratos/self-service#performing-login-registration-settings--flows).
A message from kapa.ai
For linking and unlinking OIDC (social sign-in) providers with a user's account, the browser flow (
/self-service/settings/browser
) exposes the necessary UI nodes (such as "link" and "unlink") for these actions. On the mobile (API) side, this functionality is currently not available. The Ory documentation explicitly states: > Social Sign In is not possible for API Clients. It will be possible in a future version, which is partially tracked as [kratos#273](https://github.com/ory/kratos/issues/273) This means that, at present, there is no supported way to link or unlink OIDC providers from a native or mobile app using the API-based settings flow. This limitation is also confirmed in community discussions and GitHub issues, where it is described as a missing feature in the API flows for native/mobile clients [Link and unlink from Google, Facebook, GitHub, ..., OpenID Connect / OAuth 2.0](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#link-and-unlink-from-google-facebook-github--openid-connect--oauth-20) [Settings flow does not have 
link
option with OIDC & Password methods enabled](https://github.com/ory/kratos/issues/4185). Summary: - Browser: Use 
/self-service/settings/browser
for linking/unlinking OIDC providers. - Mobile/API: This feature is not currently supported for API-based flows. There is no official way to link or unlink OIDC providers from a native/mobile app at this time.
w
@chilly-king-10285 is it possible to create flowId via ory kratos SDk ? We are using asp net core
b
A message from kapa.ai
Based on the knowledge sources, you can create a flow (and obtain a flow ID) using the Ory Kratos SDKs, but there is no explicit example for ASP.NET Core or a .NET SDK in the provided documentation. The available SDK examples are for JavaScript/TypeScript, Go, and cURL. For example, in JavaScript/TypeScript, you can create a registration flow like this:
Copy code
js import { Configuration, FrontendApi } from "@ory/client"  const frontend = new FrontendApi(   new Configuration({     basePath: `https://${process.env.ORY_PROJECT_SLUG}.<http://projects.oryapis.com|projects.oryapis.com>`,   }), )  export async function createRegistration() {   return await frontend.createNativeRegistrationFlow() }
[Create registration flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#create-registration-flow) And in Go:
Copy code
go flow, _, err := ory.FrontendApi.CreateNativeLoginFlow(ctx).Execute()
[Go SDK example](https://www.ory.sh/docs/kratos/sdk/go#frontend-api) Summary: - The Ory Kratos API allows you to create flows (and get flow IDs) via SDKs and direct API calls. - There is no official .NET/ASP.NET Core SDK mentioned in the knowledge sources. - If you are using ASP.NET Core, you can interact with the Ory Kratos REST API directly to create flows and obtain flow IDs, as shown in the cURL and other SDK examples. If you need to create a flow in ASP.NET Core, you would typically make an HTTP request to the relevant Ory Kratos endpoint (e.g., 
/self-service/registration/api
or 
/self-service/login/api
) and parse the response to get the flow ID [Registration for API clients](https://www.ory.sh/docs/kratos/self-service/flows/user-registration#registration-for-api-clients-and-clients-without-browsers).
w
@chilly-king-10285 tell me how right to use privileged_session_max_age param
Copy code
settings:
      ui_url: <https://local.alx.tech/settings>
      privileged_session_max=0
Or without privileged_session_max_age
Copy code
settings:
      ui_url: <https://local.alx.tech/settings>
      privileged_session_max=0
I ma interested in avoiding session check
b
A message from kapa.ai
To control privileged session checks in Ory Kratos, you use the 
privileged_session_max_age
parameter under the 
settings
flow in your configuration. This parameter defines how long (after authentication) a session is considered "privileged" and can perform sensitive actions (like changing email or password) without requiring re-authentication. How to use it:
Copy code
yaml settings:   ui_url: <https://local.alx.tech/settings>   privileged_session_max_age: 0
- Setting 
privileged_session_max_age: 0
means the privileged session check is effectively **disabled**—users will not be required to re-authenticate to access privileged settings, regardless of how much time has passed since their last authentication. - If you omit the 
privileged_session_max_age
parameter, the default behavior applies (which is typically a set duration, such as 5 minutes or as defined by Ory's defaults). Important: - The parameter name must be 
privileged_session_max_age
, not 
privileged_session_max
. - Setting it to 
0
disables the privileged session check, allowing users to access sensitive settings at any time during their session without re-authentication [Privileged sessions](https://www.ory.sh/docs/kratos/session-management/session-lifespan#privileged-sessions). Example:
Copy code
yaml selfservice:   flows:     settings:       ui_url: <https://local.alx.tech/settings>       privileged_session_max_age: 0
This configuration will avoid privileged session checks for the settings flow. If you do not set 
privileged_session_max_age
at all, the default privileged session duration will be used [Privileged sessions](https://www.ory.sh/docs/kratos/session-management/session-lifespan#privileged-sessions). --- Summary: - Use 
privileged_session_max_age: 0
to disable privileged session checks. - Do not use 
privileged_session_max
(it is not a valid parameter). - Omitting the parameter uses the default privileged session duration.
w
@chilly-king-10285 oryd/kratos:v1.1.0 8 The configuration contains values or keys which are invalid: 2025-06-12 105648 selfservice.flows.settings.privileged_session_max_age: 0 2025-06-12 105648 ^-- expected string, but got number
b
A message from kapa.ai
The error message you are seeing:
Copy code
selfservice.flows.settings.privileged_session_max_age: 0 ^-- expected string, but got number
means that the value for 
privileged_session_max_age
must be a string, not a number. In Ory Kratos configuration, durations should be specified as strings (e.g., 
"0s"
, 
"15m"
, 
"1h"
), not as plain numbers. How to fix: Change your configuration from:
Copy code
yaml selfservice:   flows:     settings:       ui_url: <https://local.alx.tech/settings>       privileged_session_max_age: 0
to:
Copy code
yaml selfservice:   flows:     settings:       ui_url: <https://local.alx.tech/settings>       privileged_session_max_age: "0s"
This will set the privileged session max age to zero seconds, which effectively disables the privileged session check, allowing users to access sensitive settings at any time during their session without re-authentication [Privileged sessions](https://www.ory.sh/docs/kratos/session-management/session-lifespan#privileged-sessions). If you omit the parameter, the default value will be used. Summary: - Use a string value for durations, e.g., 
"0s"
instead of 
0
. - This matches the expected format in Ory Kratos configuration files.
w
@chilly-king-10285 what is lifespan: 1h in
Copy code
settings:
      ui_url: <https://my-app.com/user/settings>
      lifespan: 1h
      privileged_session_max_age: 1h
      required_aal: aal1
b
A message from kapa.ai
In the context of the Ory Kratos configuration, the 
lifespan: 1h
parameter under the 
settings
flow defines how long a settings flow is valid after it is initiated. This means that once a user starts a settings flow (for example, to update their profile or credentials), they have 1 hour to complete the process before the flow expires and they would need to start a new one. This is separate from 
privileged_session_max_age
, which controls how long after authentication a session is considered privileged for sensitive actions, and from 
required_aal
, which sets the required Authenticator Assurance Level for the flow [Settings and profile updates](https://www.ory.sh/docs/kratos/self-service/flows/user-settings). If the user does not complete the settings flow within the specified 
lifespan
, the flow will expire and they will need to re-initiate it.
w
@chilly-king-10285 what if lifespan is not set ?
b
A message from kapa.ai
If 
lifespan
is not set for the settings flow in your Ory Kratos configuration, the system will use the default value defined by Ory Kratos. However, the exact default value is not explicitly stated in the provided knowledge sources. The documentation only mentions that you can set the 
lifespan
to control how long the user has to complete the flow, but does not specify what happens if it is omitted or what the default duration is [Settings and profile updates](https://www.ory.sh/docs/kratos/self-service/flows/user-settings). Summary: If you do not set 
lifespan
, Ory Kratos will use its internal default, but the knowledge sources do not specify what that default is.
w
@chilly-king-10285 I am having an issue with "session_inactive" returned when linking OIDC provider via settings flow We're encountering a 
401 Unauthorized
with 
id: session_inactive
when calling the 
/self-service/settings
flow (browser) to link a Google account, even though the user has a valid active session(
whoami
returns 200) Reproduction Steps: User logs in (browser flow), session is active, cookie 
ory_kratos_session=...
is present in all requests. User opens the settings flow: 
GET /self-service/settings/browser
Kratos serves the settings form as expected. User submits OIDC link request (via POST) using the 
flow.ui.action
and 
method=oidc
& 
link=google
Kratos responds with (after user selected his account on google page):
Copy code
{
  "error": {
    "id": "session_inactive",
    "code": 401,
    "status": "Unauthorized",
    "reason": "No active session was found in this request."
  }
}
Really interesting issue that I don't know how to overcome (OIDC works perfectly for the login flow). We are using self-hosted Ory Kratos v1.1.0. (edited)
b
A message from kapa.ai
Your issue—receiving a 
401 Unauthorized
with 
id: session_inactive
when attempting to link an OIDC provider via the settings flow, despite having an active session—can be caused by several factors according to the Ory Kratos documentation and related issues. ### Key Points from Knowledge Sources 1. Session Requirement for Settings Flow The 
/self-service/settings
flow requires a valid, active session. If the session is missing, invalid, or not sent with the request (e.g., missing ory_kratos_session cookie), you will receive a 
session_inactive
error. The documentation states: > If this endpoint is called via an AJAX request, the response contains the flow without a redirect. In the case of an error, the 
error.id
of the JSON response body can be one of: > `session_inactive`: No Ory Session was found - sign in a user first. [Kratos API Reference – getSettingsFlow](https://www.ory.sh/docs/kratos/reference/api) 2. Browser Flow and Cookies For browser flows, the session cookie must be present and valid in all requests, including redirects and form submissions. If the session cookie is lost or not forwarded (for example, due to cross-origin issues, incorrect domain, or SameSite cookie settings), Kratos will not recognize the session. 3. OIDC Linking and Redirects When linking an OIDC provider, the flow involves a redirect to the provider (e.g., Google) and then back to Kratos. If the session cookie is not preserved throughout this process, Kratos will treat the request as unauthenticated and return 
session_inactive
. 4. Version Limitations You are using Ory Kratos v1.1.0. The knowledge sources indicate that OIDC and settings flows have seen improvements and bug fixes in later versions. Some issues with session handling during OIDC linking may be version-specific and resolved in newer releases [Settings flow does not have 
link
option with OIDC & Password methods enabled](https://github.com/ory/kratos/issues/4185). ### Troubleshooting Steps - Ensure the session cookie (
ory_kratos_session
) is present and valid in all requests, including after the OIDC provider redirects back to your app. - Check your cookie settings: Make sure the domain, path, and SameSite attributes are set correctly so the cookie is sent on all relevant requests. - Review your Ory Kratos version: There may be bugs or missing features in v1.1.0 related to OIDC linking in the settings flow. Upgrading to a newer version may resolve the issue, as several improvements have been made in this area in later releases. - Check for cross-origin issues: If your app and Kratos are on different domains or ports, browser security policies may block cookies. ### Summary The 
session_inactive
error during OIDC linking in the settings flow is most likely due to the session cookie not being present or recognized after the OIDC redirect, or due to limitations/bugs in your current Kratos version. Double-check your cookie handling and consider upgrading Kratos if possible. The knowledge sources do not provide a specific workaround for v1.1.0, but these are the most relevant factors based on the documentation and known issues [Kratos API Reference – getSettingsFlow](https://www.ory.sh/docs/kratos/reference/api) [Settings flow does not have 
link
option with OIDC & Password methods enabled](https://github.com/ory/kratos/issues/4185).
w
Ok, let's do this flow step by step and i will tel you what disctingusies do we have
@chilly-king-10285 Ok, let's do this flow step by step and i will tel you what disctingusies do we have
b
A message from kapa.ai
Absolutely! Let's walk through the OIDC linking flow step by step. After each step, please let me know what you observe or if anything differs from the expected behavior. --- ### Step 1: User is Authenticated - The user logs in using the browser flow. - You confirm the session is active (e.g., by calling 
/sessions/whoami
and receiving a 200 response). --- ### Step 2: Initialize the Settings Flow - The user opens the settings page, which triggers a GET request to:
Copy code
/self-service/settings/browser
- Kratos responds with the settings flow, including the available methods and UI nodes (such as OIDC link/unlink options if configured). --- ### Step 3: User Initiates OIDC Linking - The user clicks the "link" button for the desired OIDC provider (e.g., Google). - Your frontend submits a POST request to the 
ui.action
URL from the flow, with: - 
method=oidc
- 
link=google
- Kratos redirects the user to the OIDC provider for authentication. --- ### Step 4: OIDC Provider Authentication - The user authenticates with the OIDC provider (e.g., selects their Google account). - The OIDC provider redirects the user back to Kratos (to the callback endpoint). --- ### Step 5: Kratos Completes the Linking - Kratos should process the callback, link the OIDC provider to the user's account, and redirect the user back to the settings UI (or show a success message). --- At each step, let me know: - What request you make - What response you get - If you see any errors or unexpected behavior This will help pinpoint where the flow diverges from the expected process described in the documentation [Link and unlink from Google, Facebook, GitHub, ..., OpenID Connect / OAuth 2.0](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#link-and-unlink-from-google-facebook-github--openid-connect--oauth-20). Ready for step 1? Please confirm the user is authenticated and has a valid session.
7 Views
Open in Slack
PreviousNext
Powered by