配置 SAML 单点登录

本页介绍了如何配置和使用基于安全断言标记语言（SAML ）2.0 标准协议实施的单点登录功能。

先决条件

了解单点登录（SSO）的基本概念。

支持的 SAML 服务

EMQX Dashboard 可以与以下支持 SAML 2.0 协议的身份服务集成，实现基于 SAML 的单点登录，例如：

• Microsoft Entra ID

• Okta

• OneLogin

其他身份提供商正在适配中，将在后续版本提供。

通过集成 Microsoft Entra ID 配置 SSO

本节指导你如何使用 Microsoft Entra ID 作为身份提供方（IdP）并配置 SSO。您需要分别完成 IdP 侧与 EMQX Dashboard 侧的配置。

步骤 1：在 EMQX Dashboard 中启用 SAML

1. 在 Dashboard 中进入系统设置 -> 单点登录。
2. 点击 SAML 2.0 卡片上的启用按钮。
3. 在配置页面输入以下信息：
   • Dashboard 地址：确保用户可以访问 Dashboard 的实际访问地址，不需要指定具体路径。例如 http://localhost:18083。此地址将被自动拼接以生成用于 IdP 侧配置的 SSO Address 和 Metadata Address。
   • SAML 元数据 URL：暂时留空，等待步骤 2 的配置。

步骤 2：注册一个应用以集成 Microsoft Entra ID

1. 以管理员身份登录 MS Azure Portal。

2. 进入 Microsoft Entra ID -> 企业应用程序 -> 新建应用程序，并点击 创建你自己的应用程序。

   

3. 输入应用名称，例如 EMQX Dashboard，选择集成未在库中找到的任何其他应用程序(非库)，并点击创建。

   

4. 点击分配用户和组以分配可以访问 EMQX Dashboard 应用的用户和组。

5. 进入单一登录标签页，选择 SAML，并点击基本 SAML 配置区域中的编辑按钮。

6. 使用步骤 1 中 Dashboard 提供的地址配置以下信息：

   • 标识符 (实体 ID)：输入 Dashboard 提供的元数据地址，例如 http://localhost:18083/api/v5/sso/saml/metadata。
   • 回复 URL (断言使用者服务 URL)：输入 Dashboard 提供的单点登录地址，例如 http://localhost:18083/api/v5/sso/saml/acs。

   其他信息为可选项，可根据实际需求进行配置。

7. 点击保存保存配置。

步骤 3：完成 EMQX Dashboard 配置

1. 在 Microsoft Entra ID 中，进入创建的应用的单一登录标签页，并在令牌签名证书区域中复制应用联合元数据 URL。

   

2. 在 Dashboard 中，将复制的 URL 粘贴到步骤 1 的 SAML 元数据 URL 中。

3. 点击更新以完成配置。

集成 Okta 身份服务配置 SSO

本节将指导您如何使用 Okta 作为身份提供商（IdP）并配置单点登录，您需要分别完成身份提供商（IdP）侧与 EMQX Dashboard 侧的配置。

步骤 1：在 EMQX Dashboard 中启用 Okta

1. 转到 Dashboard 系统设置 -> 单点登录页面。
2. 选择 SAML 2.0 选项，点击启用按钮。
3. 在配置页面中，输入以下信息：
   • 强制启用 MFA：可选。开启后，该后端的所有用户在登录时须完成 TOTP 验证。默认关闭。详情参见为 SSO 用户强制启用 MFA。
   • Dashboard 地址：确保用户能够访问 Dashboard 的实际访问地址，不需要带具体路径。例如 http://localhost:18083。该地址将自动拼接生成单点登录地址与元数据地址供 IdP 侧配置使用。
   • SAML 元数据 URL：暂时留空，等待步骤 2 配置生成。

步骤 2：在 Okta 的应用程序目录添加 SAML 2.0 应用程序

1. 以管理员身份登录 Okta，然后转至 Okta 管理控制台。

2. 转到 Applications -> Applications 页面，点击 Create App integration 按钮，在弹出框中选择 Sign-in method 为 SAML 2.0，点击 Next 按钮。

3. 在新打开的 General Settings 页签中，App name 输入您的应用名称，例如 EMQX Dashboard，点击 Next 按钮。

4. 在 Configure SAML 页签中，配置第 1 步中 Dashboard 提供的信息：

   • Single sign-on URL：填写 Dashboard 中提供的单点登录地址，例如 http://localhost:18083/api/v5/sso/saml/acs。

   • Audience URI (SP Entity ID)：填写 Dashboard 中提供的元数据地址，例如 http://localhost:18083/api/v5/sso/saml/metadata。

     其他信息是可选的，根据实际情况配置。

5. 检查设置并点击 Next。

6. 在 Feedback 页签中，选择 I'm an Okta customer adding an internal app，根据实际情况填写其他信息，点击 Finish 按钮完成应用创建。

步骤 3：完成 Dashboard 配置，在 Okta 中为应用分配用户与组

1. 在 Okta 中，转到 Sign On 选项卡，复制 Metadata URL。
2. 在 Dashboard 中，粘贴复制来的 Metadata URL 到第 1 步中的 SAML 元数据 URL 中，点击更新按钮。
3. 在 Okta > Assignments 选项卡中，您现在可以将用户和组分配给 EMQX Dashboard 应用，只有分配进来的用户才能登录此应用。

登录与用户管理

启用 SAML 单点登录后，EMQX Dashboard 会在登录页面展示单点登录选项。点击 SAML 按钮，会进入到 IdP 预设值的登录页面，在新页面中输入为用户分配的凭证进行登录。

登录成功后，将跳转回到 Dashboard，EMQX 会自动添加一个 Dashboard 用户，您可以在用户中进行管理，例如为其分配角色与权限。如需要求 SAML 用户在登录时完成 TOTP 二次验证，请参见为 SSO 用户强制启用 MFA。

退出登录

用户可以在 Dashboard 顶部导航栏中点击用户名，在下拉菜单点击退出登录按钮退出。注意，这只是在 Dashboard 侧退出了登录，SAML 暂不支持单点退出登录。