docs: api-key scopes management usage, sso user mfa

en_US/admin/api.md

@@ -46,7 +46,31 @@ For security reasons, starting from EMQX 5.0.0, you cannot use Dashboard user cr
 
 #### Create API Keys
 
-You can manually create API keys for authentication on the Dashboard by navigating to **System** -> **API Key**. For instructions, see [System - API Keys](../dashboard/system.md#api-keys).
+##### Dashboard
+
+You can manually create API keys on the Dashboard by navigating to **System** -> **API Key**:
+
+1. Click the **+ Create** button in the top right corner to open the Create dialog.
+2. Configure the API key details:
+   - **Name** (required): Enter a name for the API key.
+   - **Expire At**: Leave empty for the key to never expire.
+   - **Is Enable**: Defaults to enabled.
+   - **Role**: Select a role (optional). See [Roles and Permissions](#roles-and-permissions).
+   - **Scopes**: Select the scopes to grant (optional). Defaults to all scope permissions. See [API Scopes](#api-scopes).
+   - **Note**: Optionally enter a description for the key.
+3. Click **Confirm**. The API key and secret key are displayed in the **Created Successfully** dialog.
+
+   ::: warning Important Notice
+
+   Save the API key and secret key immediately. The secret key will not be shown again.
+
+   :::
+
+4. Click **Close** to dismiss the dialog.
+
+You can view key details by clicking its name, edit its expiration, status, or note via the **Edit** button, or remove it with the **Delete** button.
+
+##### Bootstrap File
 
 You can also create API keys using the bootstrap file method. Add the following configuration file to specify the file location:
 
@@ -56,23 +80,26 @@ api_key = {
 }
 ```
 
-In the specified file, add multiple API keys in the format `{API Key}:{Secret Key}:{?Role}`, separated by new lines:
+In the specified file, add multiple API keys in the format `{API Key}:{Secret Key}:{?Role}:{?Scopes}`, separated by new lines:
 
 - **API Key**: Any string as the key identifier.
 - **Secret Key**: Use a random string as the secret key.
 - **Role (optional)**: Specify the key's [role](#roles-and-permissions).
+- **Scopes (optional)**: Specify the [API Scopes](#api-scopes) the key is allowed to access, as a comma-separated list. When omitted, the key receives all user-visible scopes by default (administrative all-allow, for backward compatibility with earlier releases).
 
 For example:
 
 ```bash
 my-app:AAA4A275-BEEC-4AF8-B70B-DAAC0341F8EB
 ec3907f865805db0:Ee3taYltUKtoBVD9C3XjQl9C6NXheip8Z9B69BpUv5JxVHL:viewer
 foo:3CA92E5F-30AB-41F5-B3E6-8D7E213BE97E:publisher
+integration-svc:6f1a9f2d09c84e6b:viewer:monitoring,cluster_operations
+rules-mgr:2b8e4a1c9d7e4f3b:administrator:data_integration,access_control
 ```
 
 API keys created this way are valid indefinitely.
 
-Each time EMQX starts, it will add the data set in the file to the API key list. If an API key already exists, its Secret Key and Role will be updated.
+Each time EMQX starts, it will add the data set in the file to the API key list. If an API key already exists, its Secret Key, Role, and Scopes will be updated.
 
 #### Roles and Permissions
 
@@ -82,6 +109,80 @@ The REST API implements role-based access control. When creating an API key, you
 - **Viewer**: This role can only view resources and data, corresponding to all GET requests in the REST API. The corresponding role identifier is `viewer`.
 - **Publisher**: Designed specifically for MQTT message publishing, this role is limited to accessing APIs related to message publishing. The corresponding role identifier is `publisher`.
 
+#### API Scopes
+
+Scopes are a per-key permission dimension introduced in EMQX 5.10 that declare which business areas of the REST API a key is allowed to reach. Scopes and [Roles and Permissions](#roles-and-permissions) are independent of each other and enforced together, forming two separate layers of access control:
+
+| Dimension | Purpose | Granularity |
+| --------- | ------- | ----------- |
+| **Role** | Limits HTTP verbs (read-only vs. writes, publish-only, etc.) | Request action |
+| **Scope** | Limits the API domain (clients, rules, monitoring, ...) | Resource area |
+
+Every request is checked against both dimensions: the role check and the scope check. A request is accepted only when both checks pass.
+
+##### Why Scopes
+
+In microservice and integration scenarios, external systems typically need access to only a subset of EMQX's management surface:
+
+- A monitoring platform only needs the `monitoring` scope (`/metrics`, `/stats`, `/prometheus`, ...);
+- A rules-publishing service only needs `data_integration` (`/rules`, `/connectors`, `/actions`, ...);
+- A cluster operator tool only needs `cluster_operations` (`/cluster`, `/nodes`, `/load_rebalance`, ...).
+
+With only `administrator` / `viewer` / `publisher` available, granularity is coarse: the only way to grant a service write access to rules is to hand it `administrator`, which effectively gives it full control over the whole system.
+
+Scopes let you assign keys using the principle of least privilege: grant only the scopes required for the task, and minimize the blast radius if a key is ever leaked.
+
+##### Built-in Scopes
+
+EMQX 5.10 ships with 10 scopes that you can combine freely when creating a key:
+
+| Scope | Name | Typical API areas |
+| --- | --- | --- |
+| `connections` | Connection management | `/clients`, `/subscriptions`, `/topics`, `/banned`, `/retainer`, `/file_transfer`, `/mqtt/delayed`, `/mqtt/topic_rewrite`, ... |
+| `publish` | Message publishing | `/publish`, `/publish/bulk` |
+| `data_integration` | Data integration | `/rules`, `/connectors`, `/actions`, `/schema_registry`, `/schema_validations`, `/message_transformations`, `/exhooks`, `/ai/*` |
+| `access_control` | Access control | `/authentication`, `/authorization/*` |
+| `gateways` | Protocol gateways | `/gateways`, `/coap/*`, `/lwm2m/*`, `/gcp_devices`, ... |
+| `monitoring` | Monitoring data | `/metrics`, `/stats`, `/monitor*`, `/alarms`, `/trace`, `/slow_subscriptions`, `/telemetry`, `/prometheus/{auth,stats,data_integration,...}`, ... |
+| `cluster_operations` | Cluster operations | `/cluster*`, `/nodes`, `/load_rebalance`, `/node_eviction`, `/mt/*`, ... |
+| `system` | System configuration | `/configs*`, `/listeners*`, `/plugins*`, `/ds/*`, `/data/*`, `/status`, `/relup`, `/opentelemetry*`, `/prometheus`, ... |
+| `audit` | Audit log | `/audit` |
+| `license` | License | `/license*` |
+
+::: tip
+Scope names are stable identifiers that do not change across EMQX upgrades. Even if a route's OpenAPI tag is renamed, a key configured with the same scope keeps working.
+:::
+
+Dashboard login, SSO callbacks and the API key self-management endpoints (for example `/login` and `/api_key`) can **never** be reached via API keys, regardless of the key's `scopes` configuration. This is a built-in Dashboard security boundary, unrelated to the scope model.
+
+##### Default Behaviour of `scopes`
+
+The `scopes` field on an API key follows these rules:
+
+| Value of `scopes` | Meaning |
+| --- | --- |
+| **Absent** (field missing) | All business endpoints are allowed. This is the backward-compatible default for keys created before the scopes feature existed. |
+| **Empty list** `[]` | Every business endpoint is denied. Useful as a soft disable without removing the key. |
+| **Explicit list** (e.g. `["monitoring", "cluster_operations"]`) | Only requests under those scopes are allowed. |
+
+When a bootstrap file entry omits the scopes segment, the key is explicitly written with all user-visible scopes (administrative all-allow), so upgrades don't silently strip privileges from existing bootstrap-provisioned keys.
+
+##### List Available Scopes
+
+EMQX exposes `GET /api/v5/api_key/scopes` to return the current version's user-visible scope catalogue with descriptions. Use it to populate a scope-picker UI or validate automation scripts:
+
+```bash
+curl -u "$API_KEY:$API_SECRET" http://localhost:18083/api/v5/api_key/scopes
+```
+
+##### Assign Scopes
+
+Scopes can be set from any of the following entry points:
+
+- **Dashboard**: When creating or editing a key under **System** -> **API Key**, tick the scopes to grant.
+- **REST API**: Include `"scopes": ["monitoring", "cluster_operations"]` in the create/update request body.
+- **Bootstrap file**: Provide a comma-separated scope list as the 4th segment of each line, e.g. `my-app:my-secret:administrator:monitoring,cluster_operations`.
+
 #### Authentication Method Using API Keys
 
 Once you have your API key and secret key, you can use them to authenticate your requests. The API key is used as the username and the secret key as the password for Basic Authentication.

en_US/dashboard/sso-ldap.md

@@ -15,7 +15,7 @@ Be familiar with the basic concepts of [Single Sign-On (SSO)](./sso.md).
 
 ## Configure OpenLDAP SSO
 
-This section guides you on how to enable and configure the OpenLDAP SSO in the EMQX Dashboard.
+This section guides you through enabling and configuring OpenLDAP SSO in the EMQX Dashboard.
 
 1. Go to Dashboard, and click **System Settings** -> **Single Sign-On** from the left navigation menu.
 
@@ -25,6 +25,7 @@ This section guides you on how to enable and configure the OpenLDAP SSO in the E
 
    | Option             | Description                                                  |
    | ------------------ | ------------------------------------------------------------ |
+   | Force MFA          | When enabled, all users from this LDAP backend are required to set up and verify MFA at login. Disabled by default. For details, see [Forced MFA for SSO Users](../multi-factor-authn/multi-factor-authentication.md#forced-mfa-for-sso-users). |
    | Server             | The address of the OpenLDAP server, for example, `localhost:389`. |
    | Username           | The Bind DN to access the OpenLDAP server.                   |
    | Password           | The user password to access the OpenLDAP server.             |
@@ -89,6 +90,8 @@ Before you configure the Microsoft Extra ID SSO in the Dashboard, you need to fo
 
    - Here, you are using IP address + secure LDAP direct access, so you need to click **Enable TLS** and disable **Verify Server Certificate**.
 
+   - **Force MFA**: Optionally enable this to require all users from this backend to complete TOTP verification at login. Disabled by default.
+
      <img src="./assets/sso-ad-dashboard.png" alt="sso-ad-dashboard" style="zoom:67%;" />
 
 4. Click the **Update** button to save the configuration. 
@@ -103,7 +106,7 @@ After enabling LDAP-based SSO, the EMQX Dashboard will display the LDAP SSO opti
 
 <img src="./assets/ldap_login.png" alt="ldap_login" style="zoom:67%;" />
 
-After successfully authenticating with LDAP, EMQX will automatically add a Dashboard user, which you can manage in [Users](./system.md#users), such as assigning roles and permissions.
+After successfully authenticating with LDAP, EMQX will automatically add a Dashboard user, which you can manage in [Users](./system.md#users), such as assigning roles and permissions. To require LDAP users to complete a TOTP second factor at login, see [Forced MFA for SSO Users](../multi-factor-authn/multi-factor-authentication.md#forced-mfa-for-sso-users).
 
 ## Logout
 

en_US/dashboard/sso-oidc.md

@@ -40,6 +40,7 @@ For more detailed instructions, refer to the [Okta documentation](https://help.o
 1. In the EMQX Dashboard, navigate to **System** -> **SSO**.
 2. Click the **Enable** button on the **OIDC** card.
 3. On the configuration page, enter the following information:
+   - **Force MFA**: Optionally enable this to require all users from this backend to complete TOTP verification at login. Disabled by default. For details, see [Forced MFA for SSO Users](../multi-factor-authn/multi-factor-authentication.md#forced-mfa-for-sso-users).
    - **Provider**: Choose `Okta` or select `Generic` for other providers.
    - **Issuer URL**: This is the URL of your Okta authorization server, e.g., `https://example-org.okta.com`.
    - **Client ID**: Copy it from the application created in **Step 1**.
@@ -56,7 +57,7 @@ After enabling OIDC SSO, the EMQX Dashboard will display the SSO option on the l
 
 <img src="./assets/okta_login.png" alt="okta_login" style="zoom:67%;" />
 
-After successful authentication, EMQX will automatically add a Dashboard user, which you can manage in [Users](./system.md#users), such as assigning roles and permissions.
+After successful authentication, EMQX will automatically add a Dashboard user, which you can manage in [Users](./system.md#users), such as assigning roles and permissions. To require OIDC users to complete a TOTP second factor at login, see [Forced MFA for SSO Users](../multi-factor-authn/multi-factor-authentication.md#forced-mfa-for-sso-users).
 
 ## Logout
 

en_US/dashboard/sso-saml.md

@@ -26,6 +26,7 @@ This section guides you on how to use Okta as an Identity Provider (IdP) and con
 1. Go to **System** -> **SSO** in the Dashboard.
 2. Click the **Enable** button on the **SAML 2.0** card.
 3. On the configuration page, enter the following information:
+   - **Force MFA**: Optionally enable this to require all users from this backend to complete TOTP verification at login. Disabled by default. For details, see [Forced MFA for SSO Users](../multi-factor-authn/multi-factor-authentication.md#forced-mfa-for-sso-users).
    - **Dashboard Address**: Ensure users can access the actual access address of the Dashboard, without specifying a specific path. For example, `http://localhost:18083`. This address will be automatically concatenated to generate the **SSO Address** and **Metadata Address** for IdP-side configuration.
    - **SAML Metadata URL**: Leave it temporarily blank and wait for Step 2 configuration.
 4. Click **Update** to finish the configuration.
@@ -65,7 +66,7 @@ After enabling SAML Single Sign-On, the EMQX Dashboard will display the SSO opti
 
 <img src="./assets/okta_login.png" alt="okta_login" style="zoom:67%;" />
 
-After successful SAML authentication, EMQX will automatically add a Dashboard user, which you can manage in [Users](./system.md#users), such as assigning roles and permissions.
+After successful SAML authentication, EMQX will automatically add a Dashboard user, which you can manage in [Users](./system.md#users), such as assigning roles and permissions. To require SAML users to complete a TOTP second factor at login, see [Forced MFA for SSO Users](../multi-factor-authn/multi-factor-authentication.md#forced-mfa-for-sso-users).
 
 ## Logout
 

en_US/dashboard/sso.md

@@ -2,7 +2,7 @@
 
 Single Sign-On (SSO) is an authentication mechanism that allows users to log in to multiple applications or systems using a single set of credentials, such as a username and password, without the need for separate authentication in each application. When EMQX Dashboard enables the SSO feature, users can conveniently log in to the EMQX Dashboard using their enterprise account credentials. Organizations can centrally manage user identities and permissions and simplify their user management processes. This feature enhances the security of enterprise data and systems while ensuring user convenience.
 
-EMQX implements SSO functionality based on Lightweight Directory Access Protocol (LDAP) and the Security Assertion Markup Language (SAML) 2.0 standard, supporting integration with mainstream identity services such as [OpenLDAP](https://www.openldap.org/), [Azure AD (Microsoft Entra ID](https://azure.microsoft.com/en-in/products/active-directory), [Okta](https://www.okta.com/), [OneLogin](https://www.onelogin.com/), and more. 
+EMQX implements SSO functionality based on Lightweight Directory Access Protocol (LDAP), the Security Assertion Markup Language (SAML) 2.0 standard, and OpenID Connect (OIDC), supporting integration with mainstream identity services such as [OpenLDAP](https://www.openldap.org/), [Azure AD (Microsoft Entra ID)](https://azure.microsoft.com/en-in/products/active-directory), [Okta](https://www.okta.com/), [OneLogin](https://www.onelogin.com/), and more.
 
 ## LDAP-Based SSO
 
@@ -16,17 +16,28 @@ EMQX Dashboard allows you to integrate Identity Provider (IdP) services that sup
 
 With SAML SSO, users only need to authenticate themselves once with the Identity Provider. The Identity Provider generates a SAML assertion containing user information and sends it to the EMQX Dashboard. Upon receiving and successfully verifying the SAML assertion, EMQX Dashboard creates user session information and logs the user into the Dashboard. SAML provides the capability for cross-domain authentication and authorization, supporting seamless integration between multiple applications. Enterprises can easily incorporate EMQX into their existing SAML identity systems, enabling users to access EMQX services conveniently and securely.
 
+## OIDC-Based SSO
+
+EMQX Dashboard allows you to integrate Identity Provider (IdP) services that support OIDC for SSO. OIDC is an identity layer built on top of the OAuth 2.0 protocol, providing a standardized way to verify user identity and obtain user information.
+
+With OIDC SSO, users authenticate with the Identity Provider, which returns an ID token containing user information to the EMQX Dashboard. Upon receiving and successfully validating the ID token, EMQX Dashboard creates user session information and logs the user into the Dashboard. OIDC provides a modern, RESTful approach to authentication, making it easy to integrate with contemporary identity services.
+
 ## Configuration and Usage Workflow
 
 1. Administrators configure and enable SSO in the Dashboard. Once configured, the EMQX Dashboard displays an SSO entry point on the login page.
 2. User information is configured on the Identity Provider (IdP) side.
 3. Users are guided to choose different Single Sign-On methods on the Dashboard login page.
-4. After a successful login, EMQX Dashboard creates a session based on user information, allowing users to access the Dashboard.
+4. After a successful login, EMQX Dashboard creates a session based on user information, allowing users to access the Dashboard. If `force_mfa` is enabled for the backend, users are also required to complete TOTP verification before the session is issued.
 5. Administrators assign roles and permissions to different users. Users can access corresponding resources after refreshing their login.
 
+## MFA for SSO Users
+
+Starting from EMQX 5.10, you can require SSO users to complete a TOTP second factor at login by enabling `force_mfa` on each SSO backend. For details, see [Forced MFA for SSO Users](../multi-factor-authn/multi-factor-authentication.md#forced-mfa-for-sso-users).
+
 ## Configuration Examples
 
-Below are configuration examples for SSO based on LDAP and SAML 2.0:
+Below are configuration examples for each SSO method:
 
 - [Configure LDAP Single Sign-On](./sso-ldap.md)
 - [Configure SAML Single Sign-On](./sso-saml.md)
+- [Configure OIDC Single Sign-On](./sso-oidc.md)