配置 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. 在配置页面中，输入以下信息：
   • 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 用户，您可以在用户中进行管理，例如为其分配角色与权限。

退出登录

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