docs: api-key scopes management usage, sso user mfa by JimMoen · Pull Request #3451 · emqx/emqx-docs

JimMoen · 2026-04-20T01:44:26Z

Remove peerport docs release 5.10

Meggielqk · 2026-04-21T07:28:26Z

Dashboard UI screenshots to be added

Copilot

Pull request overview

Updates the EMQX 5.10 documentation to describe newly added security/authorization capabilities in the Dashboard and REST API usage docs (SSO forced MFA + API key scopes), and reduces duplication by consolidating API key instructions into the REST API guide.

Changes:

Document forced MFA (force_mfa) for SSO users (CN/EN), and cross-link it from SSO backend docs (LDAP/SAML/OIDC) and SSO overview pages.
Expand REST API docs (CN/EN) with Dashboard + bootstrap API key creation steps and introduce API key scopes (concepts, built-in scopes, default behavior).
Simplify Dashboard “System -> API Keys” docs (CN/EN) to reference the REST API doc section instead of duplicating UI instructions.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
zh_CN/multi-factor-authn/multi-factor-authentication.md	Adds “forced MFA for SSO users” feature description, config example, and FAQ.
zh_CN/dashboard/system.md	Replaces detailed API key UI steps with a link to REST API docs.
zh_CN/dashboard/sso.md	Adds OIDC mention, `force_mfa` note in flow, and link to SSO MFA section.
zh_CN/dashboard/sso-saml.md	Adds Force MFA UI option note and link to SSO MFA docs.
zh_CN/dashboard/sso-oidc.md	Adds Force MFA UI option note and link to SSO MFA docs.
zh_CN/dashboard/sso-ldap.md	Adds Force MFA option description and link to SSO MFA docs.
zh_CN/admin/api.md	Adds API key UI creation steps and introduces API scopes + bootstrap scopes format.
en_US/multi-factor-authn/multi-factor-authentication.md	Adds “forced MFA for SSO users” feature description, config example, and FAQ.
en_US/dashboard/system.md	Replaces detailed API key UI steps with a link to REST API docs.
en_US/dashboard/sso.md	Adds OIDC section, `force_mfa` note in flow, and link to SSO MFA docs.
en_US/dashboard/sso-saml.md	Adds Force MFA UI option note and link to SSO MFA docs.
en_US/dashboard/sso-oidc.md	Adds Force MFA UI option note and link to SSO MFA docs.
en_US/dashboard/sso-ldap.md	Improves wording and adds Force MFA option mention + link to SSO MFA docs.
en_US/admin/api.md	Adds API key UI creation steps and introduces API scopes + bootstrap scopes format.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-24T09:03:48Z

+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.


The field label "Is Enable" is ungrammatical and doesn’t match common UI wording. Consider renaming it to something like "Enabled" / "Enable" (or whatever the Dashboard actually shows) and keep the navigation label consistent with the rest of the docs (System -> API Keys vs API Key).

Suggested change

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.

You can manually create API keys on the Dashboard by navigating to **System** -> **API Keys**:

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.

- **Enabled**: Defaults to enabled.

Copilot · 2026-04-24T09:03:48Z

+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.


This sentence is misleading: /login is an unauthenticated endpoint in the published OpenAPI spec (it has security: []), so it is "reachable" regardless of API keys. If the intent is that API-key authentication is not accepted for Dashboard-login / API-key management endpoints, please rephrase accordingly and avoid using /login as an example of an endpoint that is blocked by API keys.

Suggested change

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.

Dashboard login, SSO callbacks, and API key self-management endpoints (for example `/api_key`) do not accept API-key authentication, regardless of the key's `scopes` configuration. This is a built-in Dashboard security boundary, unrelated to the scope model.

Copilot · 2026-04-24T09:03:48Z

+Scope 是稳定标识符，不会随 EMQX 版本升级而改名；即便某个 API 的 OpenAPI tag 发生变化，只要您使用的是同一个 Scope，密钥行为保持不变。
+:::
+
+Dashboard 自身的登录、SSO 回调以及 API 密钥自身的管理接口（例如 `/login`、`/api_key`）永远**不**允许被 API 密钥访问，无论密钥的 `scopes` 如何配置。这与密钥的业务范围无关，属于 Dashboard 的内置安全边界。


文档中提到 Dashboard 登录/SSO 回调/API Key 管理接口（例如 /login、/api_key）"永远不允许被 API 密钥访问" 的表述不够准确：在本仓库的 OpenAPI 规范中 /login 是不需要认证的（security: []），因此从“可访问性”角度它并不会被 API Key 阻断。建议改成“这些端点不支持使用 API Key 进行认证/授权（例如 API Key 管理仅允许 bearer token）”，并避免把 /login 作为被阻断端点的例子。

Suggested change

Dashboard 自身的登录、SSO 回调以及 API 密钥自身的管理接口（例如 `/login`、`/api_key`）永远**不**允许被 API 密钥访问，无论密钥的 `scopes` 如何配置。这与密钥的业务范围无关，属于 Dashboard 的内置安全边界。

Dashboard 自身的登录、SSO 回调以及 API 密钥自身的管理接口不支持使用 API 密钥进行认证/授权；例如，API 密钥管理接口 `/api_key` 仅允许使用 bearer token。这与密钥的业务范围无关，属于 Dashboard 的内置安全边界。

Copilot · 2026-04-24T09:03:49Z

+#### API 范围（Scope）
+
+**Scope（范围）** 是 EMQX 5.10 引入的 API 密钥权限控制维度，用来声明一个密钥可以访问哪些业务领域的 API。它与[角色与权限](#角色与权限)相互独立、共同生效，形成两层权限控制：
+


这里新增了 Scopes 机制与相关字段/端点说明，但本仓库附带的 OpenAPI 规范（redocly/ee-zh.json）里目前 api_key 的 schema（api_key.app）没有 scopes 字段，paths 里也没有 /api_key/scopes。建议同步更新 OpenAPI 规范或在文档中注明该能力的接口/字段来源，避免读者按文档调用却在 API 文档里找不到。

Suggested change

::: tip 说明

当前仓库附带的 OpenAPI 规范与 Swagger UI 可能尚未完整展示 Scope 相关定义，例如 `api_key.app` 中的 `scopes` 字段或 `/api_key/scopes` 端点。阅读本节时，如在 API 文档中未找到对应字段/接口，请以所使用 EMQX 版本的实际产品能力与运行实例暴露的接口为准。

:::

JimMoen added 2 commits April 20, 2026 09:43

docs: api-key scopes management usage

eea6032

docs: feat of dashboard sso user mfa

115978f

JimMoen added this to the 5.10.4 milestone Apr 20, 2026

Editorial updates

87c98ea

Meggielqk added 3 commits April 21, 2026 16:34

Update SSO docs to add "Force MFA" option

0764d20

Add cross references in MFA doc

b0071ad

Add "Scope" option to "Create API Keys"

1e8574a

Meggielqk requested a review from Copilot April 24, 2026 08:58

Copilot started reviewing on behalf of Meggielqk April 24, 2026 08:59 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

docs: api-key scopes management usage, sso user mfa#3451
JimMoen wants to merge 6 commits intorelease-5.10from
docs/apikey-scopes-sso-mfa

JimMoen commented Apr 20, 2026

Uh oh!

Meggielqk commented Apr 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	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.
	Dashboard login, SSO callbacks, and API key self-management endpoints (for example `/api_key`) do not accept API-key authentication, regardless of the key's `scopes` configuration. This is a built-in Dashboard security boundary, unrelated to the scope model.

	Dashboard 自身的登录、SSO 回调以及 API 密钥自身的管理接口（例如 `/login`、`/api_key`）永远不允许被 API 密钥访问，无论密钥的 `scopes` 如何配置。这与密钥的业务范围无关，属于 Dashboard 的内置安全边界。
	Dashboard 自身的登录、SSO 回调以及 API 密钥自身的管理接口不支持使用 API 密钥进行认证/授权；例如，API 密钥管理接口 `/api_key` 仅允许使用 bearer token。这与密钥的业务范围无关，属于 Dashboard 的内置安全边界。

		#### API 范围（Scope）

		Scope（范围）是 EMQX 5.10 引入的 API 密钥权限控制维度，用来声明一个密钥可以访问哪些业务领域的 API。它与[角色与权限](#角色与权限)相互独立、共同生效，形成两层权限控制：

+::: tip 说明
+当前仓库附带的 OpenAPI 规范与 Swagger UI 可能尚未完整展示 Scope 相关定义，例如 `api_key.app` 中的 `scopes` 字段或 `/api_key/scopes` 端点。阅读本节时，如在 API 文档中未找到对应字段/接口，请以所使用 EMQX 版本的实际产品能力与运行实例暴露的接口为准。
+:::

Conversation

JimMoen commented Apr 20, 2026

Uh oh!

Meggielqk commented Apr 21, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants