From f1167ea6b697ce788f43d3e2b039e7a95cf22a76 Mon Sep 17 00:00:00 2001 From: Rany Date: Mon, 10 Nov 2025 16:10:25 +0800 Subject: [PATCH 1/5] chore: add the scope of security policies Account API: Follow password policy and email blocklist --- docs/end-user-flows/account-settings/by-account-api.mdx | 8 ++++++++ docs/security/blocklist.md | 2 +- docs/security/password-policy.mdx | 9 +++++++++ docs/user-management/manage-users.mdx | 6 ++++++ 4 files changed, 24 insertions(+), 1 deletion(-) 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 4c7eea52e33..40c22a51f7f 100644 --- a/docs/end-user-flows/account-settings/by-account-api.mdx +++ b/docs/end-user-flows/account-settings/by-account-api.mdx @@ -219,6 +219,10 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ --data-raw '{"password":"..."}' ``` +:::tip +Just like passwords created during sign-up, passwords set through the Account API must comply with the [password policy](/security/password-policy) you configured in Console > Security > Password policy. Logto returns detailed validation results and error messages if the password fails the policy. +::: + ### Update or link new email \{#update-or-link-new-email} :::note @@ -255,6 +259,10 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}' ``` +:::tip +Just like emails collected during sign-up, any email linked through the Account API must pass the [blocklist](/security/blocklist) verification you configured in Console > Security > Blocklist. Logto will reject the request and return a detailed error if the email violates the policy. +::: + ### Remove the user's email \{#remove-the-users-email} To remove the user's email, you can use the [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) endpoint. diff --git a/docs/security/blocklist.md b/docs/security/blocklist.md index 5042bfe262d..f942131aa8a 100644 --- a/docs/security/blocklist.md +++ b/docs/security/blocklist.md @@ -28,7 +28,7 @@ For instance, adding `@example.com` to the blocklist will block all email addres :::note -Disposable emails, subaddressing, and custom email are restricted during registration and account linking. Existing users with these email addresses can still sign in. +Disposable emails, subaddressing, and custom email are restricted during [new-user registration](/end-user-flows/sign-up-and-sign-in/sign-up), [linking email durding social sign-in](/end-user-flows/sign-up-and-sign-in/social-sign-in#collect-sign-up-identifiers), and updating emails via [Account API](/end-user-flows/account-settings/by-account-api#update-or-link-new-email). Existing users with these email addresses can still sign in. - Admins can "bypass restrictions" by manually adding users in Console > User management, or via [Management API](https://openapi.logto.io/operation/operation-createuser). E.g., Create an user with a subaddress email when subaddressing is blocked. - Block exsiting accounts by deleting or suspending them in Console > User management. diff --git a/docs/security/password-policy.mdx b/docs/security/password-policy.mdx index 3f52ee1d14e..c0a54239d08 100644 --- a/docs/security/password-policy.mdx +++ b/docs/security/password-policy.mdx @@ -6,6 +6,12 @@ sidebar_position: 1 # Password policy +Logto applies the password policy in different ways depending on how the password is created or updated: + +- End-user flows such as [the out-of-the-box sign-in experience](/end-user-flows/sign-up-and-sign-in/sign-up), [the Experience API](/customization/bring-your-ui), and [the Account API](/end-user-flows/account-settings/by-account-api#update-users-password) always enforce the current [password policy](#set-up-password-policy). +- Administrator actions via the Management API [`patch /api/users/{userId}/password`](https://openapi.logto.io/operation/operation-updateuserpassword) are exempt, allowing you to provision or reset credentials without policy checks when needed. +- To audit existing passwords against the current rules, call [`POST /api/sign-in-exp/default/check-password`](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) and act on the returned validation result. Read [Password compliance check](#password-compliance-check) to learn more. + ## Set up password policy \{#set-up-password-policy} For new users or users who are updating their password, you can set a password policy to enforce password strength requirements. Visit the Console > Security > Password policy to configure the password policy settings. @@ -29,4 +35,7 @@ To enforce stronger security, you can use the `POST /api/sign-in-exp/default/che ## Related resources \{#related-resources} +Manage users +Sign-up and sign-in +Account settings by Account API Design your password policy diff --git a/docs/user-management/manage-users.mdx b/docs/user-management/manage-users.mdx index 5313a240fb8..22b3f36643c 100644 --- a/docs/user-management/manage-users.mdx +++ b/docs/user-management/manage-users.mdx @@ -88,6 +88,12 @@ After you reset the password, copy and send it to the end-user. Once the "Reset You cannot set a specific password for users in the Logto Console, but you can use the [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` to specify a password. +## Password compliance check \{#password-compliance-check} + +After you update the [password policy](/security/password-policy) in Logto, existing users can still sign in with their current passwords. Only newly created account will be required to follow the updated password policy. + +To enforce stronger security, you can use the `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) to check whether a user's password meets the current policy defined in the default sign-in experience. If it doesn't, you can prompt the user to update their password with a custom flow using [Account API](/end-user-flows/account-settings/by-management-api#user-password-management). + ### Manage roles of users \{#manage-roles-of-users} In the "Roles" tab of the user details page, you can easily assign or remove roles to meet your desired outcome. Check [Role-based access control](/authorization/role-based-access-control) for details. From b1107d41812cb18019d98b8a5fd0fa70ae3f84a2 Mon Sep 17 00:00:00 2001 From: Rany Date: Mon, 10 Nov 2025 16:15:32 +0800 Subject: [PATCH 2/5] chore: update the link --- docs/security/password-policy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/security/password-policy.mdx b/docs/security/password-policy.mdx index c0a54239d08..0c3cbb12dbc 100644 --- a/docs/security/password-policy.mdx +++ b/docs/security/password-policy.mdx @@ -31,7 +31,7 @@ For new users or users who are updating their password, you can set a password p After you update the password policy in Logto, existing users can still sign in with their current passwords. Only newly created account will be required to follow the updated policy. -To enforce stronger security, you can use the `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) to check whether a user's password meets the current policy defined in the default sign-in experience. If it doesn't, you can prompt the user to update their password with a custom flow using [Account API](/end-user-flows/account-settings/by-management-api#user-password-management). +To enforce stronger security, you can use the `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) to check whether a user's password meets the current policy defined in the default sign-in experience. If it doesn't, you can prompt the user to update their password with a custom flow using [Account API](/end-user-flows/account-settings/by-account-api). ## Related resources \{#related-resources} From 63ebf94aea38890b7a1ddf0d5de77d31a7273a29 Mon Sep 17 00:00:00 2001 From: Rany Date: Mon, 10 Nov 2025 16:35:50 +0800 Subject: [PATCH 3/5] chore: update docs/security/blocklist.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/security/blocklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/security/blocklist.md b/docs/security/blocklist.md index f942131aa8a..df12429b3b8 100644 --- a/docs/security/blocklist.md +++ b/docs/security/blocklist.md @@ -28,7 +28,7 @@ For instance, adding `@example.com` to the blocklist will block all email addres :::note -Disposable emails, subaddressing, and custom email are restricted during [new-user registration](/end-user-flows/sign-up-and-sign-in/sign-up), [linking email durding social sign-in](/end-user-flows/sign-up-and-sign-in/social-sign-in#collect-sign-up-identifiers), and updating emails via [Account API](/end-user-flows/account-settings/by-account-api#update-or-link-new-email). Existing users with these email addresses can still sign in. +Disposable emails, subaddressing, and custom email are restricted during [new-user registration](/end-user-flows/sign-up-and-sign-in/sign-up), [linking email during social sign-in](/end-user-flows/sign-up-and-sign-in/social-sign-in#collect-sign-up-identifiers), and updating emails via [Account API](/end-user-flows/account-settings/by-account-api#update-or-link-new-email). Existing users with these email addresses can still sign in. - Admins can "bypass restrictions" by manually adding users in Console > User management, or via [Management API](https://openapi.logto.io/operation/operation-createuser). E.g., Create an user with a subaddress email when subaddressing is blocked. - Block exsiting accounts by deleting or suspending them in Console > User management. From fe7ca1c7b25a8ed4bde78101c39d6bf1bcd8d7db Mon Sep 17 00:00:00 2001 From: Rany Date: Mon, 10 Nov 2025 16:36:08 +0800 Subject: [PATCH 4/5] chore: update docs/security/blocklist.md 2 Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/security/blocklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/security/blocklist.md b/docs/security/blocklist.md index df12429b3b8..50128664fbb 100644 --- a/docs/security/blocklist.md +++ b/docs/security/blocklist.md @@ -31,7 +31,7 @@ For instance, adding `@example.com` to the blocklist will block all email addres Disposable emails, subaddressing, and custom email are restricted during [new-user registration](/end-user-flows/sign-up-and-sign-in/sign-up), [linking email during social sign-in](/end-user-flows/sign-up-and-sign-in/social-sign-in#collect-sign-up-identifiers), and updating emails via [Account API](/end-user-flows/account-settings/by-account-api#update-or-link-new-email). Existing users with these email addresses can still sign in. - Admins can "bypass restrictions" by manually adding users in Console > User management, or via [Management API](https://openapi.logto.io/operation/operation-createuser). E.g., Create an user with a subaddress email when subaddressing is blocked. -- Block exsiting accounts by deleting or suspending them in Console > User management. +- Block existing accounts by deleting or suspending them in Console > User management. ::: From 4b7fcdb4a0800e65f7af14863cac8367f4a40388 Mon Sep 17 00:00:00 2001 From: Rany Date: Mon, 10 Nov 2025 16:36:39 +0800 Subject: [PATCH 5/5] chore: update docs/user-management/manage-users.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/user-management/manage-users.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-management/manage-users.mdx b/docs/user-management/manage-users.mdx index 22b3f36643c..4c83cd9ccba 100644 --- a/docs/user-management/manage-users.mdx +++ b/docs/user-management/manage-users.mdx @@ -90,7 +90,7 @@ You cannot set a specific password for users in the Logto Console, but you can u ## Password compliance check \{#password-compliance-check} -After you update the [password policy](/security/password-policy) in Logto, existing users can still sign in with their current passwords. Only newly created account will be required to follow the updated password policy. +After you update the [password policy](/security/password-policy) in Logto, existing users can still sign in with their current passwords. Only newly created accounts will be required to follow the updated password policy. To enforce stronger security, you can use the `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) to check whether a user's password meets the current policy defined in the default sign-in experience. If it doesn't, you can prompt the user to update their password with a custom flow using [Account API](/end-user-flows/account-settings/by-management-api#user-password-management).