To implement a custom view for connecting TOTP (Time-based One-Time Password) to a user profile in Ory, you'll need to create a custom UI that interacts with Ory's settings flow API. Here's how you can do this: ## Implementation Steps 1. Create a Settings Flow: First, you need to initiate a settings flow which will allow users to manage their TOTP settings. 2. Render Custom UI: Use the flow data to render your custom TOTP setup UI. 3. Handle TOTP Registration: When a user wants to add TOTP to their account, you'll need to: - Display the QR code for the user to scan with their authenticator app - Verify the TOTP code entered by the user 4. Submit the Settings Flow: Send the TOTP code to verify and complete the setup. ## Integration Details For browser-based applications, you should use the

/self-service/settings/browser

endpoint, while for native applications, use the

/self-service/settings/api

endpoint. This is important because browser applications require CSRF protection that native apps don't need [Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration). When implementing the TOTP method in the settings flow, you'll need to: 1. Set the

method

parameter to

"totp"

when trying to add, update, or remove a TOTP pairing 2. Include the

totp_code

parameter with a valid TOTP code when verifying 3. Use

totp_unlink: true

if you want to remove an existing TOTP pairing [Ory Identities API](https://www.ory.sh/docs/kratos/reference/api) ## Example Implementation For end-to-end testing of your TOTP implementation, you can reference the Cypress tests used in Ory Identities as a guide: [Writing E2E tests](https://www.ory.sh/docs/kratos/mfa/totp#writing-e2e-tests). ## Custom Identity Schema Configuration If you're using a custom identity schema, make sure it's properly configured to work with TOTP. To help users distinguish which identity the registered TOTP code belongs to, add a

totp

section to 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               }             }           }         }       }     }   } }

This configuration will display the user's email address when requesting the TOTP code [Custom identity schema](https://www.ory.sh/docs/kratos/mfa/totp#custom-identity-schema). When the user successfully enables TOTP, Ory will add entries to the

credentials

object of the associated Identity, including the TOTP URL which contains the pre-shared key [Identity credentials](https://www.ory.sh/docs/kratos/mfa/totp#identity-credentials). For more advanced integration details, you may want to check the documentation on [Advanced integration](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-advanced-integration) which covers topics like two-factor authentication integration.

When implementing TOTP (Time-based One-Time Password) in Ory, you don't need to manually generate the authenticator app secret. Ory Kratos handles this for you as part of the settings flow when a user sets up TOTP authentication. ## How TOTP Secret Generation Works in Ory When a user initiates the TOTP setup process through the settings flow, Ory automatically: 1. Generates a secure random secret 2. Creates a TOTP URL that includes this secret 3. Returns this information as part of the settings flow response The TOTP secret appears in two forms in the response: - As a QR code (in base64 format) that users can scan with their authenticator app - As a text secret that users can manually enter into their authenticator app if they can't scan the QR code ## Accessing the TOTP Secret To access the generated TOTP secret in your custom UI: 1. Create a settings flow 2. Look for the

totp_secret_key

node in the response, which contains the secret in text form 3. Look for the

totp_qr

node, which contains the QR code in base64 format Here's an example of what the TOTP secret node looks like in the UI response:

json {   "type": "text",   "group": "totp",   "attributes": {     "text": {       "id": 1050006,       "text": "GLAS5YHAJ6V5LT3N7AU2R4AWU6SYOCHS",       "type": "info",       "context": {         "secret": "GLAS5YHAJ6V5LT3N7AU2R4AWU6SYOCHS"       }     },     "id": "totp_secret_key",     "node_type": "text"   },   "messages": [],   "meta": {     "label": {       "id": 1050006,       "text": "This is your authenticator app secret. Use it if you can not scan the QR code.",       "type": "info"     }   } }

This text node includes a message with ID 1050017, which indicates "This is your authenticator app secret. Use it if you can not scan the QR code." [Understanding UI nodes and error messages](https://www.ory.sh/docs/kratos/concepts/ui-user-interface#ui-text-nodes). ## Verifying the TOTP Code After the user has scanned the QR code or entered the secret manually in their authenticator app, they need to verify it by entering a generated code. To verify this code, you should: 1. Submit the settings flow with: -

method

set to "totp" -

totp_code

containing the code from the user's authenticator app If the verification is successful, Ory will add the TOTP credentials to the user's identity:

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:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example>

[Identity credentials](https://www.ory.sh/docs/kratos/mfa/totp#identity-credentials) If you're building a custom implementation, you can reference the official Ory discussion which confirms that "the TOTP QR code is returned as part of the GetSettingsFlow response in base64 format" [TOTP - Generate QR code and verify users provided code .NET Core](https://github.com/ory/kratos/discussions/4311).