famous-jackal-2829
05/31/2025, 8:22 AMbrief-egg-61061
05/31/2025, 8:22 AMbrief-egg-61061
05/31/2025, 8:22 AMsh ory list workspaces ory list projects --workspace <workspace-id> ory get identity-config --project <project-id> --workspace <workspace-id> --format yaml > identity-config.yaml
2. Edit the configuration file to enable TOTP and set the issuer: yaml selfservice: methods: totp: config: issuer: <http://ExampleIssuer.com|ExampleIssuer.com> enabled: true
3. Update your configuration: sh ory update identity-config --project <project-id> --workspace <workspace-id> --file identity-config.yaml
[Time-based one-time passwords (TOTP)](https://www.ory.sh/docs/kratos/mfa/totp) ### 2. User Enrollment After TOTP is enabled for your project, each user must pair their account with a TOTP app (like Google Authenticator or FreeOTP). In the Ory Account Experience, users do this by: - Signing in to their account. - Navigating to the Authenticator App section in Account Settings. - Following the instructions to pair their TOTP app. Users are not automatically prompted to enable TOTP; they must opt in via their account settings [Time-based one-time passwords (TOTP)](https://www.ory.sh/docs/kratos/mfa/totp). ### 3. (Optional) Custom Identity Schema If you use a custom identity schema and want to display a specific trait (like email) in the TOTP app, add a totp
section to the relevant trait in your schema: json "email": { "type": "string", "format": "email", "<http://ory.sh/kratos|ory.sh/kratos>": { "credentials": { "totp": { "account_name": true } } } }
[Custom identity schema](https://www.ory.sh/docs/kratos/mfa/totp#custom-identity-schema) --- This will enable TOTP as a second factor for your users, increasing the security of your authentication flows.famous-jackal-2829
05/31/2025, 8:25 AMbrief-egg-61061
05/31/2025, 8:26 AMbrief-egg-61061
05/31/2025, 8:26 AMtotp
section under the email
trait. Here’s how to proceed: --- ### 1. Update your Kratos configuration (kratos.yml
) Add the totp
method under selfservice.methods
and set it to enabled. You can also specify the issuer name that will appear in users’ authenticator apps. yaml selfservice: methods: password: enabled: true config: min_password_length: 6 identifier_similarity_check_enabled: false haveibeenpwned_enabled: false totp: enabled: true config: issuer: <http://ExampleIssuerForSelfHosted.com|ExampleIssuerForSelfHosted.com> flows: # ... (rest of your config)
Note: Place the totp
block at the same level as password
under selfservice.methods
in your kratos.yml
file. [Reference: Configure multi-factor authentication in Ory Kratos](https://www.ory.sh/docs/kratos/self-hosted/mfa) --- ### 2. Restart Kratos After updating the configuration, restart your Kratos service to apply the changes. --- ### 3. User Enrollment Users can now enroll TOTP as a second factor via the settings flow in your UI. When they do, Kratos will generate a TOTP secret and provide a QR code for pairing with an authenticator app (like Google Authenticator). The QR code and secret are managed by Kratos and exposed via the settings flow API. [Reference: Time-based one-time passwords (TOTP)](https://www.ory.sh/docs/kratos/mfa/totp) --- ### 4. (Optional) Adjust Enforcement You already have required_aal: highest_available
under selfservice.flows.settings
, which means users with a second factor configured will be required to complete the TOTP challenge for sensitive operations. [Reference: Configure multi-factor authentication in Ory Kratos](https://www.ory.sh/docs/kratos/self-hosted/mfa) --- Summary: - Add the totp
method to your kratos.yml
under selfservice.methods
. - Restart Kratos. - Users can now enroll TOTP via the settings UI. If you need to customize the identity schema further for TOTP, your current schema already includes the recommended configuration for the email
trait, so no changes are needed there. If you have any issues with the QR code or TOTP pairing, ensure your UI is correctly handling the settings flow and displaying the QR code provided by Kratos. The TOTP URL is included in the flow response as described in the [official answer here](https://github.com/ory/kratos/discussions/4311).famous-jackal-2829
05/31/2025, 8:30 AMbrief-egg-61061
05/31/2025, 8:30 AMbrief-egg-61061
05/31/2025, 8:30 AMyaml selfservice: methods: totp: enabled: true config: issuer: ExampleApp
The documentation states: > The "issuer" is the name in the TOTP application users see when getting a one-time password. [Configure multi-factor authentication in Ory Kratos](https://www.ory.sh/docs/kratos/self-hosted/mfa) Choose a value that clearly identifies your service to your users.famous-jackal-2829
05/31/2025, 8:35 AMbrief-egg-61061
05/31/2025, 8:35 AMbrief-egg-61061
05/31/2025, 8:35 AMkratos.yml
as described, but it is not appearing as an option for your users, here are some things to check based on the official Ory documentation: 1. Configuration Placement: Ensure that the totp
method is placed under selfservice.methods
in your kratos.yml
, at the same level as `password`: yaml selfservice: methods: password: enabled: true # ... totp: enabled: true config: issuer: ExampleApp
2. Restart Kratos: After making changes to your configuration, you must restart the Kratos service for the changes to take effect. 3. User Enrollment Flow: TOTP is not automatically enabled for users. Each user must go to the Account Settings page and pair their account with a TOTP app. In the Ory Account Experience, users are not automatically prompted to enable TOTP; they must opt in via their account settings. If your UI does not expose this flow, users will not see the option to add TOTP [Time-based one-time passwords (TOTP)](https://www.ory.sh/docs/kratos/mfa/totp). 4. Identity Schema: Your identity schema already includes the recommended configuration for TOTP under the email
trait, so this should not be the issue. 5. UI Integration: If you are using a custom UI, ensure you are correctly handling the settings flow and displaying the TOTP setup option. The QR code and secret are provided by Kratos in the settings flow response. 6. Logs and Errors: Check the Kratos logs for any errors or warnings related to TOTP or the settings flow. Sometimes, misconfiguration or missing fields can cause the method not to appear. If you have checked all of the above and TOTP still does not appear, the knowledge sources do not provide further troubleshooting steps for this specific issue. You may want to review your UI integration or consult the [official documentation](https://www.ory.sh/docs/kratos/mfa/totp) for additional details. If you encounter a specific error message, please provide it for more targeted help.famous-jackal-2829
05/31/2025, 8:37 AMbrief-egg-61061
05/31/2025, 8:37 AMbrief-egg-61061
05/31/2025, 8:37 AMoryd/kratos-selfservice-ui-node
). According to the knowledge sources, when TOTP is enabled in your Kratos configuration and your identity schema is set up correctly (which yours is), users should be able to enroll TOTP as a second factor through the Account Settings page in the UI. However, the knowledge sources do not provide explicit details about the TOTP enrollment experience in the kratos-selfservice-ui-node
container. The official documentation and discussions focus on the Ory Account Experience and custom UIs, and they state that users must go to the Authenticator App section of the Account Settings page to pair their TOTP app. If your UI does not expose this flow, users will not see the option to add TOTP, even if it is enabled in Kratos. This is a common issue if the UI is not up-to-date with the latest Kratos features or if the settings flow is not fully implemented for TOTP support in the UI you are using [Time-based one-time passwords (TOTP)](https://www.ory.sh/docs/kratos/mfa/totp). What you can do: - Make sure you are accessing the Settings page in your UI after logging in. - If you do not see the TOTP option, it is likely that the kratos-selfservice-ui-node
does not support TOTP enrollment out of the box, or your version is outdated. - The knowledge sources do not provide a way to enable TOTP in the UI if it is not already present. If this is the case, you may need to implement the TOTP enrollment flow yourself or use a different UI that supports it. Summary: If TOTP is enabled in your Kratos config and your identity schema is correct, but you do not see the TOTP option in the UI, the most likely reason is that the kratos-selfservice-ui-node
does not support TOTP enrollment in its current version. The knowledge sources do not provide a solution for enabling TOTP in this UI if it is missing. You may need to check for updates to the UI or implement the TOTP flow yourself. If you have further questions or encounter specific errors, please provide more details for targeted help.