From c8607809eaa5281e5ae57688493d342900152169 Mon Sep 17 00:00:00 2001 From: wangsijie Date: Tue, 15 Jul 2025 09:57:58 +0800 Subject: [PATCH] feat: add new mfa for account api --- .../account-settings/by-account-api.mdx | 156 +++++++++++++++++- 1 file changed, 154 insertions(+), 2 deletions(-) diff --git a/docs/end-user-flows/account-settings/by-account-api.mdx b/docs/end-user-flows/account-settings/by-account-api.mdx index 47745dfa6bb..bca8048f073 100644 --- a/docs/end-user-flows/account-settings/by-account-api.mdx +++ b/docs/end-user-flows/account-settings/by-account-api.mdx @@ -51,7 +51,9 @@ Some frequent use cases are listed below: To learn more about the available APIs, please visit [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) and [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications). :::note -Dedicated Account APIs for the following settings are coming soon: MFA, SSO, Custom data (user), and Account deletion. In the meantime, you can implement these features using the Logto Management APIs. See [Account settings by Management API](/end-user-flows/account-settings/by-management-api) for more details. +Dedicated Account APIs for the following settings are coming soon: SSO, Custom data (user), and Account deletion. In the meantime, you can implement these features using the Logto Management APIs. See [Account settings by Management API](/end-user-flows/account-settings/by-management-api) for more details. + +MFA management APIs (TOTP and backup codes) are currently under development and only available when the `isDevFeaturesEnabled` flag is set to `true`. WebAuthn passkey management is fully available. ::: ## How to enable Account API \{#how-to-enable-account-api} @@ -256,7 +258,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v After verifying the code, you can now update the user's email, set the `verificationId` to the request body as `newIdentifierVerificationRecordId`. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ +curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ @@ -460,3 +462,153 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' ``` + +### Link a new TOTP \{#link-a-new-totp} + +:::note +Remember to [enable MFA and TOTP](/end-user-flows/mfa) first. +::: + +:::note +To use this method, you need to enable the `mfa` field in the account center settings. +::: + +**Step 1: Generate a TOTP secret.** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +The response body would be like: + +```json +{ + "secret": "..." +} +``` + +**Step 2: Display the TOTP secret to the user.** + +Use the secret to generate a QR code or display it directly to the user. The user should add it to their authenticator app (such as Google Authenticator, Microsoft Authenticator, or Authy). + +The URI format for the QR code should be: + +``` +otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] +``` + +Example: + +``` +otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp +``` + +**Step 3: Bind the TOTP factor.** + +After the user has added the secret to their authenticator app, they need to verify it and bind it to their account: + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"Totp","secret":"..."}' +``` + +- `verification_record_id`: a valid verification record ID, granted by verifying the user's existing factor. You can refer to the [Get a verification record ID](#get-a-verification-record-id) section for more details. +- `type`: must be `Totp`. +- `secret`: the TOTP secret generated in step 1. + +:::note +A user can only have one TOTP factor at a time. If the user already has a TOTP factor, attempting to add another one will result in a 422 error. +::: + +### Manage backup codes \{#manage-backup-codes} + +:::note +Remember to [enable MFA and backup codes](/end-user-flows/mfa) first. +::: + +:::note +To use this method, you need to enable the `mfa` field in the account center settings. +::: + +**Step 1: Generate new backup codes:** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +The response body would be like: + +```json +{ + "codes": ["...", "...", "..."] +} +``` + +**Step 2: Display backup codes to the user:** + +:::important +Before binding the backup codes to the user's account, you must display them to the user and instruct them to: + +- Download or write down these codes immediately +- Store them in a secure location +- Understand that each code can only be used once +- Know that these codes are their last resort if they lose access to their primary MFA methods + +You should display the codes in a clear, easy-to-copy format and consider providing a download option (e.g., as a text file or PDF). +::: + +**Step 3: Bind backup codes to the user account:** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' +``` + +- `verification_record_id`: a valid verification record ID, granted by verifying the user's existing factor. You can refer to the [Get a verification record ID](#get-a-verification-record-id) section for more details. +- `type`: must be `BackupCode`. +- `codes`: the array of backup codes generated in the previous step. + +:::note + +- A user can only have one set of backup codes at a time. If all codes have been used, the user needs to generate and bind new codes. +- Backup codes cannot be the only MFA factor. The user must have at least one other MFA factor (such as WebAuthn or TOTP) enabled. +- Each backup code can only be used once. + +::: + +**View existing backup codes:** + +```bash +curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ + -H 'authorization: Bearer ' +``` + +The response body would be like: + +```json +{ + "codes": [ + { + "code": "...", + "usedAt": null + }, + { + "code": "...", + "usedAt": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +- `code`: the backup code. +- `usedAt`: the timestamp when the code was used, `null` if not used yet.