Discourse OpenID Connect (OIDC)

[Discourse]

	摘要	Discourse OpenID Connect 允许使用 OpenID Connect 提供商作为 Discourse 的身份验证提供商。
	安装指南	此插件已随 Discourse 核心捆绑。无需单独安装该插件。

由于这是由 Discourse 团队维护的 official 插件，因此可以在 Meta 的相应分类中提出 #contribute:bug、Contribute > UX 和 Contribute > Feature 请求，并打上相应的插件标签。支持服务在 Support > SSO 中提供。点击下方的链接即可开始。: +1:

支持 Bug 用户体验 功能

功能

该插件旨在提供 规范 的最小实现。具体来说，它支持“授权码流程”。要开始使用，请遵循 插件安装说明，或联系您的托管服务提供商。

我们的 oauth2-basic 插件可用于连接某些 OpenID Connect 提供商（OpenID Connect 基于 OAuth2）。但是，此插件需要的手动配置要少得多，并且如果 JSON API 不可用，还可以利用 JWT“ID Token”。

配置将自动使用 OpenID Connect 发现文档 进行。根据规范，该文档应位于 <issuer domain>/.well-known/openid-configuration，但 Discourse 支持任何路径以允许不符合规范的实现（例如 Azure B2C）。发现文档会被缓存 10 分钟，以提高高流量站点的性能。

如果发现文档包含 userinfo_endpoint 参数，则插件将使用它来收集用户元数据。如果没有，插件将从令牌端点提供的 id_token（JWT）中提取元数据。插件不验证 JWT 签名的真实性，因为这会显著增加复杂性。这一决定得到了 规范 的支持：

如果 ID Token 是通过客户端与令牌端点之间的直接通信接收的（在本流程中确实如此），则可以使用 TLS 服务器验证来验证颁发者，而无需检查令牌签名。

对于支持使用 “带有代码交换证明密钥的授权码流程” 进行无密钥授权的身份提供商，应启用 PKCE，并且可以省略 client_secret 配置。

配置

基本配置选项

• openid_connect_enabled: 启用 OpenID Connect 身份验证

• openid_connect_discovery_document: OpenID Connect 发现文档 URL。通常位于 https://your.domain/.well-known/openid-configuration

• openid_connect_client_id: OpenID Connect 客户端 ID

• openid_connect_client_secret: OpenID Connect 客户端密钥

• openid connect rp initiated logout: 注销后将用户重定向到 end_session_endpoint。必须由您的身份提供商支持并包含在发现文档中。

• openid connect rp initiated logout redirect: （可选）将传递给注销端点的 post_logout_redirect_uri。如果提供，必须在身份提供商处注册。

• openid_connect_authorize_scope: 发送到授权端点的作用域。必须包含 ‘openid’

• openid_connect_use_pkce: 为 OpenID Connect 身份验证启用代码交换证明密钥（PKCE）。

• openid_connect_verbose_logging: 将详细的 openid-connect 身份验证信息记录到 /logs。在正常使用期间请保持禁用。

高级配置选项

• openid_connect_token_scope: 请求令牌端点时发送的作用域。官方规范不要求此项。

• openid_connect_error_redirects: 如果回调 error_reason 包含第一个参数，用户将被重定向到第二个参数中的 URL。用于以非标准方式在用户输入响应中发送错误的实现（例如 Azure B2C）。

• openid_connect_allow_association_change: 允许用户断开并重新连接其 Discourse 账户与 OpenID Connect 提供商的关联

• openid_connect_groups_claim: OIDC 响应^[1] 中包含用户组（字符串数组）的声明名称。留空以禁用组同步。参见下方的 组同步。

• openid_connect_user_field_mappings: 将存储在 Discourse 用户字段中的 OIDC 声明^[2] 的映射。用户字段由其数字 ID 标识，该 ID 可在通过管理面板编辑用户字段时的 URL 中找到。

组同步

该插件可以自动将组 memberships 从您的 OpenID Connect 提供商同步到 Discourse 组。每次登录时，插件将从 OIDC 令牌中读取配置的声明，并相应地更新用户的组 memberships。要启用组同步：

1. 配置您的身份提供商以在其中一个声明中返回组数组。这必须是一个字符串数组。

2. 将 openid_connect_groups_claim 设置为 OIDC 令牌中包含用户组的声明名称（例如 cognito:groups）。设置后，这将开始将信息同步到 Discourse 的“关联组”系统。

3. 找到您想要链接的 Discourse 组。进入“设置” → “成员资格” → “自动”，然后选择要链接的关联组。此下拉列表由身份提供商的信息填充，因此至少需要一名组成员登录才能出现选项。

示例设置

在此，我们将设置 openid-connect 插件以连接到 Google 的 OpenID Connect 提供商。这复制了 Discourse 核心中已存在的功能，但作为一个易于理解的示例。

1. 访问 OpenID Connect  |  Sign in with Google  |  Google for Developers 并按照说明获取 OAuth 凭据。

2. 在同一页面上，按照说明添加重定向 URI。这应该是 https://<your_forum>/auth/oidc/callback（不带尾部斜杠）

3. 进入您的 Discourse 站点设置并搜索“openid_connect”

   • openid connect enabled: [x]

   • openid connect discovery document: https://accounts.google.com/.well-known/openid-configuration

   • openid connect client id: <client-id>

   • openid connect client secret: <client-secret>

   • openid connect authorize scope: openid email（中间有空格）

4. 您已完成。现在，“使用 OpenID Connect 登录”按钮将使用 Google 登录 。这些相同的步骤可以应用于其他提供商，只需进行极小的更改。

调试

除了上面描述的 verbose_logging 设置外，您还可以使用 data-explorer 插件访问有关 OIDC 关联的数据：

SELECT user_id, provider_name, provider_uid
FROM user_associated_accounts
WHERE provider_name = 'oidc'

或在 rails 控制台中：

User.find_by_username("david").user_associated_accounts.where(provider_name: 'oidc')

特定提供商说明

如果您发现与此集成相关的任何特定于提供商的怪癖，欢迎更新此内容：

Entra ID（前身为 Azure AD）

添加 email 作用域，并确保使用版本 2 端点配置文档。例如：

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration

@andy.czerwonka

• 确保使用 v2.0 配置端点，如上所述。默认的 v1.0 端点不支持 email 或 profile 作用域。
• 如果客户端密钥存在问题，请尝试生成一个新的。我们遇到了一些问题，但生成几个后似乎就正常了。
• 在 Azure AD 中为您的站点创建条目时，请确保将“登录并读取用户配置文件”作为“委托权限”开启。
• 确保添加正确的回调，即 ‘https://your-site/auth/oidc/callback’

Azure B2C

发现文档 URL 的详细信息可在此找到：Web sign in with OpenID Connect - Azure AD B2C | Microsoft Learn

例如，fabrikamb2c.onmicrosoft.com 中 b2c_1_sign_in 用户流的元数据文档位于：

https://fabrikamb2c.b2clogin.com/fabrikamb2c.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=b2c_1_sign_in

要使电子邮件正常工作：

@Umer_Nawab

要在声明中获取电子邮件，您必须使用自定义策略。为此，我使用了此处提到的策略入门包：

Tutorial - Create user flows and custom policies - Azure Active Directory B2C | Microsoft Learn

在实施上述文章中提到的步骤后，当用户注册时，电子邮件声明开始出现，但当现有用户登录时，令牌中缺少电子邮件声明。然后，我不得不按照此帖中提到的步骤在自定义策略 xml 文件中进行一些更改：

https://stackoverflow.com/questions/59669666/email-claims-not-populated-with-custom-policies-in-azure-b2c

进行这些更改后，当用户注册以及登录时，电子邮件声明现在都会出现。

Yahoo

1. 访问 https://developer.yahoo.com/apps 并创建一个新应用

2. 输入应用名称，并将回调域设置为您的论坛域（例如 meta.discourse.org）

3. 在 API 权限下，选择 Profiles: Read/Write Public and Private。这是我知道的获取用户电子邮件地址的唯一方法

4. 保存应用

5. 在 Discourse OIDC 设置中，将发现文档设置为

   https://login.yahoo.com/.well-known/openid-configuration
   

6. 输入来自 Yahoo 的客户端 ID 和密钥

7. 启用 OIDC 插件

AWS Cognito

1. 进入 Cognito 并选择或创建一个新的用户池。
2. 在应用客户端中定义一个应用。
3. 保持所有设置为默认值，但将 Auth Flows Configuration 更改为仅选择 ALLOW_REFRESH_TOKEN_AUTH。
4. 进入应用客户端设置并选择新应用。
5. 将回调 URL 更改为 https://yoursite.example.com/auth/oidc/callback。
6. 在“允许的 OAuth 流程”中仅选中授权码授予流程。
7. 选中所有所需的作用域（我已全部选中）。

Okta

1. 使用您的 Okta 应用客户端 ID 和密钥配置 Discourse

2. 将发现文档 URL 设置为

   https://{your-app}.okta.com/.well-known/openid-configuration
   

3. 在 Discourse 中，将 openid connect authorize scope 设置为 openid email

由我们托管？此插件可在我们的商业版和企业版计划中使用。OAuth 2.0 & OpenID Connect Support | Discourse - Civilized Discussion

需要自动化用户注册？请参阅 Auto-provisioning user accounts when SSO is enabled

---

1. 令牌或用户信息负载 ↩︎

2. 来自令牌或用户信息负载 ↩︎