157 lines
7.2 KiB
Markdown
157 lines
7.2 KiB
Markdown
# OpenID Connect (OIDC)
|
||
|
||
GoToSocial 支持 [OpenID Connect](https://openid.net/connect/)，这是一种基于 [OAuth 2.0](https://oauth.net/2/) 构建的身份验证协议，OAuth 2.0 是授权协议的行业标准协议之一。
|
||
|
||
这意味着你可以将 GoToSocial 连接到外部 OIDC 提供商，如 [Gitlab](https://docs.gitlab.com/ee/integration/openid_connect_provider.html)、[Google](https://cloud.google.com/identity-platform/docs/web/oidc)、[Keycloak](https://www.keycloak.org/) 或 [Dex](https://dexidp.io/)，并允许用户使用其凭据登录 GoToSocial。
|
||
|
||
在以下情况下，这非常方便：
|
||
|
||
- 你在一个平台上运行多个服务（Matrix、Peertube、GoToSocial），并希望用户可以使用相同的登录页面登录所有服务。
|
||
- 你希望将用户、账户、密码等的管理委托给外部服务，以简化管理。
|
||
- 你已经在外部系统中有很多用户，不想在 GoToSocial 中手动重新创建他们。
|
||
|
||
!!! tip
|
||
如果用户尚不存在，且你的 IdP 没有返回非空的 `email` 作为 claims 的一部分，登录将会失败。这个 email 需要在此实例中是唯一的。尽管我们使用 `sub` claim 将外部身份与 GtS 用户关联，但创建用户时需要一个与之关联的 email。
|
||
|
||
## 设置
|
||
|
||
GoToSocial 为 OIDC 提供以下配置设置，以下显示的是其默认值。
|
||
|
||
```yaml
|
||
#######################
|
||
##### OIDC CONFIG #####
|
||
#######################
|
||
|
||
# 配置与外部 OIDC 提供商（如 Dex、Google、Auth0 等）的身份验证。
|
||
|
||
# 布尔值。启用与外部 OIDC 提供商的身份验证。如果设置为 true，则其他 OIDC 选项也必须设置。
|
||
# 如果设置为 false，则使用标准的内部 OAuth 流程，用户使用用户名/密码登录 GtS。
|
||
# 选项: [true, false]
|
||
# 默认值: false
|
||
oidc-enabled: false
|
||
|
||
# 字符串。oidc idp（身份提供商）的名称。这将在用户登录时显示。
|
||
# 示例: ["Google", "Dex", "Auth0"]
|
||
# 默认值: ""
|
||
oidc-idp-name: ""
|
||
|
||
# 布尔值。跳过对从 OIDC 提供商返回的令牌的正常验证流程，即不检查过期或签名。
|
||
# 这应仅用于调试或测试，绝对不要在生产环境中使用，因为这极其不安全！
|
||
# 选项: [true, false]
|
||
# 默认值: false
|
||
oidc-skip-verification: false
|
||
|
||
# 字符串。OIDC 提供商 URI。这是 GtS 将用户重定向到的登录地址。
|
||
# 通常这看起来像是一个标准的网页 URL。
|
||
# 示例: ["https://auth.example.org", "https://example.org/auth"]
|
||
# 默认值: ""
|
||
oidc-issuer: ""
|
||
|
||
# 字符串。在 OIDC 提供商处注册的此客户端的 ID。
|
||
# 示例: ["some-client-id", "fda3772a-ad35-41c9-9a59-f1943ad18f54"]
|
||
# 默认值: ""
|
||
oidc-client-id: ""
|
||
|
||
# 字符串。在 OIDC 提供商处注册的此客户端的密钥。
|
||
# 示例: ["super-secret-business", "79379cf5-8057-426d-bb83-af504d98a7b0"]
|
||
# 默认值: ""
|
||
oidc-client-secret: ""
|
||
|
||
# 字符串数组。向 OIDC 提供商请求的范围。返回的值将用于填充在 GtS 中创建的用户。
|
||
# 'openid' 和 'email' 是必需的。
|
||
# 'profile' 用于提取新创建用户的用户名。
|
||
# 'groups' 是可选的，可以用于根据 oidc-admin-groups 确定用户是否为管理员。
|
||
# 示例: 见 eg., https://auth0.com/docs/scopes/openid-connect-scopes
|
||
# 默认值: ["openid", "email", "profile", "groups"]
|
||
oidc-scopes:
|
||
- "openid"
|
||
- "email"
|
||
- "profile"
|
||
- "groups"
|
||
|
||
# 布尔值。将通过 OIDC 进行身份验证的用户与现有用户基于其电子邮件地址进行关联。
|
||
# 这主要用于迁移目的，即从使用不稳定 `email` claim 进行唯一用户标识的旧版 GtS 迁移。对于大多数用例，应设置为 false。
|
||
# 选项: [true, false]
|
||
# 默认值: false
|
||
oidc-link-existing: false
|
||
|
||
# 字符串数组。如果返回的 ID 令牌包含与 oidc-allowed-groups 中的某个组匹配的 'groups' claim，则该用户将在 GtS 实例上被授予访问权限。
|
||
# 如果数组为空，则授予所有组权限。
|
||
# 默认值: []
|
||
oidc-allowed-groups: []
|
||
|
||
# 字符串数组。如果返回的 ID 令牌包含与 oidc-admin-groups 中的某个组匹配的 'groups' claim，则该用户将在 GtS 实例上被授予管理员权限。
|
||
# 默认值: []
|
||
oidc-admin-groups: []
|
||
```
|
||
|
||
## 行为
|
||
|
||
在 GoToSocial 上启用 OIDC 后，默认登录页面会自动重定向到 OIDC 提供商的登录页面。
|
||
|
||
这意味着 OIDC 本质上 *替代* 了正常的 GtS 邮箱/密码登录流程。
|
||
|
||
由于 ActivityPub 标准的工作方式，你 _不能_ 在设置用户名后更改它。这与 OIDC 规范冲突，该规范不保证 `preferred_username` 字段是稳定的。
|
||
|
||
为了解决这个问题，我们要求用户在首次登录尝试时提供用户名。此字段预先填入 `preferred_username` claim 的值。
|
||
|
||
在认证后，GtS 存储由 OIDC 提供商提供的 `sub` claim。在后续的身份验证尝试中，这个 claim 被用作唯一的用户查找方式。
|
||
|
||
这使你可以在提供商级别更改用户名而不丢失对 GtS 账户的访问。
|
||
|
||
### 群组成员身份
|
||
|
||
大多数 OIDC 提供商允许在返回的 claims 中包含群组和群组成员身份的概念。GoToSocial 可以使用群组成员身份来确定从 OIDC 流中返回的用户是否应创建为管理员账户。
|
||
|
||
如果返回的 OIDC 群组信息中包含配置在 `oidc-admin-groups` 中的群组成员身份，则该用户将被创建/登录为管理员。
|
||
|
||
## 从旧版本迁移
|
||
|
||
如果你从使用不稳定 `email` claim 进行唯一用户标识的旧版 GtS 迁移过来，可以将 `oidc-link-existing` 配置设置为 `true`。如果无法为提供商返回的 ID 找到用户，则会根据 `email` claim 进行查找。如果成功，稳定 ID 将被添加到匹配的用户数据库中。
|
||
|
||
你应仅在有限时间内使用此功能，以避免恶意账户盗取。
|
||
|
||
## 提供商示例
|
||
|
||
### Dex
|
||
|
||
[Dex](https://dexidp.io/) 是一个可以自行托管的开源 OIDC 提供商。安装 Dex 的过程不在本文档范围内，你可以在 [这里](https://dexidp.io/docs/) 查看 Dex 文档。
|
||
|
||
Dex 的优势在于它也用 Go 编写，像 GoToSocial 一样，这意味着它体积小、运行快，在低功耗系统上也能很好地运行。
|
||
|
||
要配置 Dex 和 GoToSocial 一起工作，在 Dex 配置的 `staticClients` 部分创建以下客户端：
|
||
|
||
```yaml
|
||
staticClients:
|
||
- id: 'gotosocial_client'
|
||
redirectURIs:
|
||
- 'https://gotosocial.example.org/auth/callback'
|
||
name: 'GoToSocial'
|
||
secret: 'some-client-secret'
|
||
```
|
||
|
||
确保将 `gotosocial_client` 替换为你想要的客户端 ID，并将 `secret` 替换为一个合理长且安全的密钥（例如 UUID）。你还应该将 `gotosocial.example.org` 替换为 GtS 实例的 `host`，但保留 `/auth/callback` 不变。
|
||
|
||
然后，编辑 GoToSocial config.yaml 中的 `oidc` 部分如下：
|
||
|
||
```yaml
|
||
oidc:
|
||
enabled: true
|
||
idpName: "Dex"
|
||
skipVerification: false
|
||
issuer: "https://auth.example.org"
|
||
clientID: "gotosocial_client"
|
||
clientSecret: "some-client-secret"
|
||
scopes:
|
||
- "openid"
|
||
- "email"
|
||
- "profile"
|
||
- "groups"
|
||
```
|
||
|
||
确保将 `issuer` 变量替换为你的 Dex 提供商设置。这应该是你的 Dex 实例的可访问到的确切 URI。
|
||
|
||
现在，重启 GoToSocial 和 Dex，以便新设置生效。
|
||
|
||
当你下次登录 GtS 时，你应该会被重定向到 Dex 的登录页面。登录成功后，你将返回到 GoToSocial。
|