docs: document email allowlist behavior

Author: charIeszhao

docs/security/README.mdx

@@ -43,7 +43,7 @@ Logto delivers robust secure access management designed to counter these risks h
       label: 'Blocklist',
       href: '/security/blocklist',
       description:
-        'Take control of your user base by blocking disposable or unwanted email domains or addresses.',
+        'Control new sign-ups and newly linked emails with an allowlist and block disposable or unwanted addresses.',
       customProps: {
         icon: <BlockUserIcon />,
       },

docs/security/blocklist.mdx

@@ -8,9 +8,24 @@ sidebar_position: 3
 
 ## Email blocklist \{#email-blocklist}
 
-The email blocklist policy allows customization of email blocklist settings to prevent account sign-up abuse. It monitors email addresses used for sign-up and account settings. If a user attempts to sign up or link an email address that violates any blocklist rules, the system will reject the request, helping to mitigate spam accounts and enhance overall account security.
+Use the email allowlist and blocklist settings to control which email addresses can be used for new account registrations and account linking. Logto rejects email addresses that do not satisfy every enabled rule, helping to mitigate spam accounts and enhance overall account security.
 
-Visit the <CloudLink to="/security/blocklist"> Console > Security > Blocklist</CloudLink> to configure the email blocklist settings.
+Visit the <CloudLink to="/security/blocklist"> Console > Security > Blocklist</CloudLink> to configure the email allowlist and blocklist settings.
+
+### Custom email allowlist \{#custom-email-allowlist}
+
+Use the custom email allowlist to restrict new sign-ups and newly linked emails to approved addresses. The allowlist is disabled when it has no entries. When it contains one or more entries, an email address must match at least one entry:
+
+| Entry type  | Example            | Matches                                                     |
+| ----------- | ------------------ | ----------------------------------------------------------- |
+| Exact email | `foo@example.com`  | Only `foo@example.com`                                      |
+| Domain      | `@example.com`     | Any email address whose domain is exactly `example.com`     |
+| Wildcard    | `foo*@example.com` | Emails such as `foo1@example.com` and `foo.bar@example.com` |
+| Wildcard    | `@*.example.com`   | Emails from subdomains, such as `user@team.example.com`     |
+
+Matching is case-insensitive. A wildcard subdomain entry such as `@*.example.com` does not match the root domain `example.com`; add both `@example.com` and `@*.example.com` to allow the root domain and its subdomains.
+
+The allowlist is not an exception list for the blocklist. An email that matches the allowlist must still pass all enabled blocklist checks, including disposable email, subaddressing, and custom blocklist rules.
 
 ### Block disposable email addresses \{#block-disposable-email-addresses}
 
@@ -30,7 +45,7 @@ You can also use `*` as a wildcard in the local part or domain. For example, `fo
 
 :::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 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.
+Email allowlist and blocklist rules apply 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 linking or updating emails via [Account API](/end-user-flows/account-settings/by-account-api#update-or-link-new-email). Existing users can still sign in with email addresses that are already linked to their accounts.
 
 - Admins can "bypass restrictions" by manually adding users in <CloudLink to="/users">Console > User management</CloudLink>, 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 existing accounts by deleting or suspending them in <CloudLink to="/users">Console > User management</CloudLink>.