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..50128664fbb 100644 --- a/docs/security/blocklist.md +++ b/docs/security/blocklist.md @@ -28,10 +28,10 @@ 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 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. ::: diff --git a/docs/security/password-policy.mdx b/docs/security/password-policy.mdx index 3f52ee1d14e..0c3cbb12dbc 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. @@ -25,8 +31,11 @@ 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} +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..4c83cd9ccba 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 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). + ### 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.