When a user enables Time-based One-Time Password (TOTP) in Ory Kratos, the system adds specific entries to the

credentials

object of the associated identity. Here is an example of how the

credentials

object might look:

json credentials:     password:       id: totp       identifiers:         - 802471b9-06f5-49d4-a88d-5e7d6bcfed22       config:         # This is the TOTP URL which contains the pre-shared key and some additional meta-information.         totp_url: <otpauth://totp/Example:[[email> protected]](<https://www.ory.sh/cdn-cgi/l/email-protection>)?secret=JBSWY3DPEHPK3PXP&issuer=Example

In this example, the

id

field under

password

is set to

totp

, indicating that TOTP is enabled. The

identifiers

field contains a unique identifier for the user. The

config

field contains a

totp_url

, which is a URL that includes the pre-shared key and some additional meta-information for TOTP. This information is stored in the identity schema for the user, allowing Ory Kratos to handle TOTP authentication for that user. For more details, you can refer to the [Ory Kratos documentation](https://www.ory.sh/docs/kratos/mfa/totp#identity-credentials).

Yes, when you are self-hosting Ory Kratos and a user enables Multi-Factor Authentication (MFA), you need to update the identity schema to support these added credentials. For example, if a user enables Time-based One-Time Password (TOTP), you need to add a

totp

section to the identity schema section of the trait you want to show up in the TOTP app. Here is an example of how you might update the identity schema:

json {     "$schema": "<http://json-schema.org/draft-07/schema#>",     "type": "object",     "properties": {       "traits": {         "type": "object",         "properties": {           "email": {             "type": "string",             "format": "email",             "title": "Your E-Mail",             "minLength": 3,             "<http://ory.sh/kratos|ory.sh/kratos>": {               "credentials": {                 // ...                 "totp": {                   "account_name": true                 }               }               // ...             }           }           // ...         }         // ...       }     }   }

In this example, the

totp

section is added under

credentials

in the

<http://ory.sh/kratos|ory.sh/kratos>

section of the

email

trait. The

account_name

field is set to

true

, indicating that the user's email address should be used as the identifier for TOTP. For more details, you can refer to the [Ory Kratos documentation](https://www.ory.sh/docs/kratos/mfa/totp#custom-identity-schema).

To support Lookup Secrets (recovery codes) in your identity schema when self-hosting Ory Kratos, you need to add the

lookup_secret

method to

selfservice/methods

in the configuration file. Here is an example of how you might update the configuration:

yaml selfservice:     methods:       lookup_secret:         enabled: true

In this example, the

lookup_secret

method is added under

selfservice/methods

and

enabled

is set to

true

, indicating that Lookup Secrets are enabled. For more details, you can refer to the [Ory Kratos documentation](https://www.ory.sh/docs/kratos/self-hosted/mfa#lookup-secrets-recovery-codes).

To configure the lifespan of the recovery link in a self-hosted Ory Kratos setup, you need to update the

lifespan

property under

selfservice.flows.recovery

in the configuration file. Here is an example of how you might update the configuration:

yaml selfservice:     flows:       recovery:         lifespan: 15m

In this example, the

lifespan

property under

selfservice.flows.recovery

is set to

15m

, indicating that the recovery link is valid for 15 minutes after it's sent to the user's email. You can express the lifespan in hours, minutes, and seconds. Use a combination of these units to define the desired lifespan. For example:

72h

,

10m

,

12s

,

1h13m3s

. For more details, you can refer to the [Ory Kratos documentation](https://www.ory.sh/docs/kratos/self-service/flows/account-recovery-password-reset#configuration).

In the Ory Kratos configuration file,

selfservice/methods

and

selfservice/flows

have different purposes: - `selfservice/methods`: This section is used to enable or disable specific methods for self-service operations. For example, you can enable or disable the

password

or

oidc

methods for user login, registration, and settings updates. Each method corresponds to a specific way of performing a self-service operation. For instance, the

password

method allows users to use a username and password for authentication, while the

oidc

method allows users to use OpenID Connect providers for authentication. - `selfservice/flows`: This section is used to configure the behavior of different self-service flows. A flow corresponds to a specific self-service operation, such as login, registration, or settings update. You can configure various aspects of each flow, such as its lifespan (how long the flow is valid for), the URL to redirect to after the flow is completed, and more. Here are examples of how you might use these sections in the configuration file:

yaml selfservice:     methods:       password:         enabled: true       oidc:         enabled: true      flows:       login:         lifespan: 10m       registration:         lifespan: 1h

In this example, the

password

and

oidc

methods are enabled, the login flow has a lifespan of 10 minutes, and the registration flow has a lifespan of 1 hour. For more details, you can refer to the [Ory Kratos documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-login).

When a user enables Time-based One-Time Password (TOTP), WebAuthn, and Lookup codes in a self-hosted Ory Kratos setup, the system adds specific entries to the

credentials

object of the associated identity. Here is an example of how the

credentials

object might look:

json credentials:     password:       id: totp       identifiers:         - 802471b9-06f5-49d4-a88d-5e7d6bcfed22       config:         # This is the TOTP URL which contains the pre-shared key and some additional meta-information.         totp_url: <otpauth://totp/Example:[[email> protected]](<https://www.ory.sh/cdn-cgi/l/email-protection>)?secret=JBSWY3DPEHPK3PXP&issuer=Example      password:       id: webauthn       identifiers:         - [[email protected]](<https://www.ory.sh/cdn-cgi/l/email-protection>)       config:         credentials:           - display_name: my-key             added_at: "2022-03-06T09:45:18Z"             # If 'true', WebAuthn is used for passwordless flows.             is_passwordless: false             # WebAuth2-specific values.             id: P/psShpG+SOCxBqslynuxMors6oexs7RS09bSA/F9EI=             public_key: pQECAyYgASFYIJ0RRsaHJ2IQ6Eh11BPpHkdOl2DkICXg3rJVxSHQAsklIlgga0Tt2PqLlg/baAl20Y64JCllE71jDG+XzHfN6FT/S9I=             attestation_type: none             authenticator:               aaguid: AAAAAAAAAAAAAAAAAAAAAA==               sign_count: 1               clone_warning: false         # The user handle will be used in the exchange with the FIDO2 device         # to ensure that the user handle from the key and from Ory match.         user_handle: NDVP4/1nTj2CTFaItp/zXg==

In this example, the

id

field under

password

is set to

totp

and

webauthn

, indicating that TOTP and WebAuthn are enabled. The

identifiers

field contains a unique identifier for the user. The

config

field contains a

totp_url

for TOTP and

credentials

for WebAuthn, which includes the pre-shared key and some additional meta-information for TOTP and WebAuthn respectively. However, the Lookup codes are not stored in the identity schema. They are stored separately and securely in the Ory Kratos system and are not directly associated with the user's identity schema. For more details, you can refer to the [Ory Kratos documentation](https://www.ory.sh/docs/kratos/mfa/totp#identity-credentials) and [Ory Kratos documentation](https://www.ory.sh/docs/kratos/mfa/webauthn-fido-yubikey#identity-credentials).

To enable Time-based One-Time Password (TOTP) for users in a self-hosted Ory Kratos setup, you need to follow these steps: 1. First, you need to enable TOTP in your Kratos configuration file. Add the

totp

method to

selfservice/methods

in your `kratos.config.yml`:

yaml selfservice:     methods:       totp:         config:           issuer: <http://ExampleIssuerForSelfHosted.com|ExampleIssuerForSelfHosted.com>         enabled: true

In this configuration, you set

enabled: true

to activate TOTP, and you can customize the

issuer

name, which users will see in their TOTP application when getting a one-time password [Ory Kratos documentation](https://www.ory.sh/docs/kratos/self-hosted/mfa#time-based-one-time-passwords-totp). 2. After enabling TOTP in the configuration, each user is responsible for enabling TOTP in their own account by pairing their account with a TOTP app. 3. Users are not automatically prompted to enable TOTP for their accounts. To enable TOTP, users must sign in to their accounts and go to the Authenticator App section of the Account Settings page [Ory Kratos documentation](https://www.ory.sh/docs/kratos/mfa/totp#enabling-totp-authentication). 4. When a user enables TOTP, Ory Kratos will add entries to the

credentials

object of the associated Identity, which will look something like this:

json credentials:     password:       id: totp       identifiers:         - 802471b9-06f5-49d4-a88d-5e7d6bcfed22       config:         totp_url: <otpauth://totp/Example:[[email> protected]](<https://www.ory.sh/cdn-cgi/l/email-protection>)?secret=JBSWY3DPEHPK3PXP&issuer=Example

This

totp_url

contains the pre-shared key and additional meta-information for the TOTP setup [Ory Kratos documentation](https://www.ory.sh/docs/kratos/mfa/totp#identity-credentials). Remember, you'll need to implement the user interface for the TOTP setup process, which typically involves displaying a QR code for the user to scan with their TOTP app, and then verifying that they've set it up correctly by asking them to enter a code.

To enable Time-based One-Time Password (TOTP) for a user account via Ory Kratos self-service in a self-hosted setup, the process involves both configuration on the server side and actions from the user. Here's how it works: 1. First, ensure that TOTP is enabled in your Kratos configuration file. Add the following to your `kratos.config.yml`:

yaml selfservice:     methods:       totp:         config:           issuer: <http://ExampleIssuerForSelfHosted.com|ExampleIssuerForSelfHosted.com>         enabled: true

This enables the TOTP method and sets the issuer name [Ory Kratos documentation](https://www.ory.sh/docs/kratos/self-hosted/mfa#time-based-one-time-passwords-totp). 2. Once TOTP is enabled in the configuration, users can enable it for their accounts. However, users are not automatically prompted to enable TOTP. They need to take the following steps: a. Sign in to their account. b. Navigate to the Account Settings page. c. Go to the Authenticator App section. 3. In the Authenticator App section, the user should find an option to enable TOTP. When they choose to enable it, they typically need to: a. Scan a QR code with their TOTP app (like Google Authenticator or FreeOTP). b. Enter the generated one-time code to verify the setup. 4. After the user successfully sets up TOTP, Ory Kratos will add the TOTP credentials to the user's identity [Ory Kratos documentation](https://www.ory.sh/docs/kratos/mfa/totp#enabling-totp-authentication). It's important to note that the exact user interface and flow for enabling TOTP will depend on your specific implementation of the Ory Account Experience. You'll need to ensure that your UI provides the necessary options and interfaces for users to enable and set up TOTP for their accounts. Remember, the security of TOTP relies on keeping the shared secret (encoded in the QR code) confidential. Ensure that your implementation securely handles this sensitive information.

To get the QR code for TOTP setup in a self-hosted Ory Kratos environment, you need to interact with the Ory Kratos API and handle the UI nodes returned by the API. Here's a general outline of the process: 1. First, ensure that TOTP is enabled in your Kratos configuration as mentioned in previous answers. 2. When a user wants to set up TOTP, you need to initiate a settings flow. This is typically done by making a request to the Kratos Admin API's settings flow endpoint. 3. In the response from the settings flow, Kratos will include a UI node of type "img" with the id "totp_qr". This node contains the QR code image data. Here's an example of what this node might look like:

json {   "attributes": {     "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",     "id": "totp_qr",       "width": 256,       "height": 256,       "node_type": "img"     },     "messages": [],     "meta": {       "label": {         "id": 1050005,         "text": "Authenticator app QR code",         "type": "info"       }     } }

The

src

attribute of this node contains the base64-encoded image data for the QR code [Ory Kratos documentation](https://www.ory.sh/docs/kratos/concepts/ui-user-interface#ui-image-nodes). 4. In your UI, you should display this image to the user. They can then scan this QR code with their TOTP app to set up the authenticator. 5. After the user scans the QR code, they typically need to enter a code generated by their TOTP app to verify the setup. You would need to implement this verification step in your UI and send the entered code back to Kratos for verification. Remember, the exact implementation details will depend on your specific setup and the UI framework you're using. You'll need to handle the API requests, parse the responses, and render the appropriate UI elements based on the nodes returned by Kratos. Also, note that the QR code contains sensitive information (the TOTP secret), so it's crucial to handle this data securely and ensure it's only displayed to the authenticated user who is setting up TOTP for their own account.

To initiate a settings flow in self-hosted Ory Kratos to add TOTP to the user's credentials, you need to follow these steps: 1. Initialize the Settings Flow: For server-side browser clients, you can initialize the Settings Flow by pointing the browser to the initialization endpoint:

curl -s -i -X GET \        --cookie $cookieJar --cookie-jar $cookieJar \        -H "Accept: text/html" \        <https://your-kratos-domain.com/self-service/settings/browser>

Replace

<http://your-kratos-domain.com|your-kratos-domain.com>

with your actual Kratos domain. The server will respond with a HTTP 303 redirect to the Settings UI, appending the

?flow=<flow-id>

query parameter to the configured settings URL [Ory Kratos documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#user-and-profile-settings-for-server-side-browser-clients). 2. Configure the Settings UI URL: You can configure which settings URL to use in the Ory Identities config:

yaml    selfservice:      flows:        settings:          ui_url: <http://127.0.0.1:4455/auth/settings>

This will result in a URL like

<http://127.0.0.1:4455/auth/settings?flow=df607aa1-d555-4b2a-b3e4-0f5a1d2fe6f3>

[Ory Kratos documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#user-and-profile-settings-for-server-side-browser-clients). 3. Handle the Settings Flow: Once the settings flow is initialized, you need to handle the flow in your UI. The flow will include UI nodes for setting up TOTP, including the QR code image node as mentioned in the previous answer. 4. Submit TOTP Setup: After the user scans the QR code and enters the verification code, you need to submit this information to complete the TOTP setup. This is typically done by sending a POST request to the settings flow endpoint with the following data:

json    {      "method": "totp",      "totp_code": "123456",      "csrf_token": "abcde"    }

The

totp_code

is the verification code entered by the user, and the

csrf_token

is provided in the settings flow response [Ory Kratos API Reference](https://www.ory.sh/docs/kratos/reference/api#tag/frontend/operation/updateSettingsFlow). Remember, you need to have TOTP enabled in your Kratos configuration for this to work:

yaml selfservice:   methods:     totp:       config:         issuer: YourIssuerName       enabled: true

This process allows a user to add TOTP to their credentials through the Ory Kratos self-service flow. The exact implementation details may vary depending on your specific UI and integration with Kratos.

When a user sets up WebAuthn in Ory Kratos, the

credentials

field of their identity is updated to include specific information about the WebAuthn setup. Here's what the

credentials

field might look like:

json credentials:     password:       id: webauthn       identifiers:         - [[email protected]](<https://www.ory.sh/cdn-cgi/l/email-protection>)       config:         credentials:           - display_name: my-key             added_at: "2022-03-06T09:45:18Z"             is_passwordless: false             id: P/psShpG+SOCxBqslynuxMors6oexs7RS09bSA/F9EI=             public_key: pQECAyYgASFYIJ0RRsaHJ2IQ6Eh11BPpHkdOl2DkICXg3rJVxSHQAsklIlgga0Tt2PqLlg/baAl20Y64JCllE71jDG+XzHfN6FT/S9I=             attestation_type: none             authenticator:               aaguid: AAAAAAAAAAAAAAAAAAAAAA==               sign_count: 1               clone_warning: false         user_handle: NDVP4/1nTj2CTFaItp/zXg==

Let's break down the key components: 1. The

id

field is set to "webauthn", indicating that this is a WebAuthn credential. 2. The

identifiers

field contains the user's email address. 3. The

config

field contains detailed information about the WebAuthn setup: - `credentials`: An array of WebAuthn credentials (there can be multiple). - `display_name`: A user-friendly name for the credential. - `added_at`: Timestamp of when the credential was added. - `is_passwordless`: Indicates if WebAuthn is used for passwordless flows. - `id`: A unique identifier for this specific WebAuthn credential. - `public_key`: The public key associated with this credential. - `attestation_type`: The type of attestation used. - `authenticator`: Contains information about the authenticator device. - `user_handle`: A unique identifier used in the exchange with the FIDO2 device. This structure allows Ory Kratos to manage and validate WebAuthn credentials for the user's identity. [Source: Ory Kratos Documentation](https://www.ory.sh/docs/kratos/mfa/webauthn-fido-yubikey#identity-credentials)

If WebAuthn is enabled in the Ory Kratos configuration but the user has not set it up yet, the

credentials

field of their identity would not contain any WebAuthn-specific information. The

credentials

field would only contain information about the authentication methods that the user has actually set up. For example, if the user has only set up a password, the

credentials

field might look like this:

json credentials:   password:     id: password     identifiers:       - [[email protected]](<https://www.ory.sh/cdn-cgi/l/email-protection>)     config:       hashed_password: $argon2id$v=19$m=65536,t=1,p=1$SOME_HASHED_PASSWORD

The absence of a

webauthn

entry in the

credentials

field indicates that the user has not set up WebAuthn, even if it's enabled in the system. It's important to note that simply enabling WebAuthn in the Kratos configuration does not automatically add it to every user's credentials. The WebAuthn entry is only added to a user's

credentials

field when they actually go through the process of setting it up for their account. [Source: Ory Kratos Documentation](https://www.ory.sh/docs/kratos/mfa/webauthn-fido-yubikey#identity-credentials)

When a user has set up two WebAuthn devices in Ory Kratos, the

credentials

field of their identity would contain information about both devices. Here's what the

credentials

field might look like in this case:

json credentials:   password:     id: webauthn     identifiers:       - [[email protected]](<https://www.ory.sh/cdn-cgi/l/email-protection>)     config:       credentials:         - display_name: my-first-key           added_at: "2022-03-06T09:45:18Z"           is_passwordless: false           id: P/psShpG+SOCxBqslynuxMors6oexs7RS09bSA/F9EI=           public_key: pQECAyYgASFYIJ0RRsaHJ2IQ6Eh11BPpHkdOl2DkICXg3rJVxSHQAsklIlgga0Tt2PqLlg/baAl20Y64JCllE71jDG+XzHfN6FT/S9I=           attestation_type: none           authenticator:             aaguid: AAAAAAAAAAAAAAAAAAAAAA==             sign_count: 1             clone_warning: false         - display_name: my-second-key           added_at: "2022-03-07T14:30:22Z"           is_passwordless: false           id: Q/rtTipH+TODyBrsmznvyNpst7pfyt8ST10cTA/G0FJ=           public_key: qREDAzZhATGZJK1SStbHK3JR7Fi22QPqIkePm3DlJDYh4skmJmhhb1Uu3QrMcBm31Z75KCmmF82kzIfO7GU/T0J=           attestation_type: none           authenticator:             aaguid: BBBBBBBBBBBBBBBBBBBBBB==             sign_count: 1             clone_warning: false       user_handle: NDVP4/1nTj2CTFaItp/zXg==

The key differences when multiple WebAuthn devices are set up are: 1. The

credentials

array under the

config

field contains multiple entries, one for each WebAuthn device. 2. Each entry in the

credentials

array has its own unique

id

,

public_key

, and other device-specific information. 3. The

display_name

for each credential can be different, allowing the user to distinguish between their devices. 4. The

added_at

timestamps will likely be different, reflecting when each device was added. 5. The

authenticator

section for each credential will have its own unique

aaguid

(Authenticator Attestation Global Unique Identifier). The

user_handle

remains the same for all credentials as it's associated with the user, not the individual devices. This structure allows Ory Kratos to manage and validate multiple WebAuthn credentials for a single user's identity, enabling the user to authenticate with any of their registered devices. [Source: Ory Kratos Documentation](https://www.ory.sh/docs/kratos/mfa/webauthn-fido-yubikey#identity-credentials)