177 lines
No EOL
12 KiB
Markdown
177 lines
No EOL
12 KiB
Markdown
### SSO 客户端登录/认证
|
||
|
||
单点登录（Single Sign-On, SSO）是一个通用术语，指的是允许用户通过单一的基于 Web 的认证门户登录应用程序的协议。例如 OpenID Connect、“中央认证服务”（CAS）以及 SAML。
|
||
|
||
本模块允许 Matrix 主服务器将用户认证委托给支持这些协议之一的外部认证服务器。在此过程中，涉及三个系统：
|
||
|
||
- 一个使用本规范定义的 API 的 Matrix 客户端，它试图将用户认证至 Matrix 主服务器。
|
||
- 一个实现了本规范所定义 API 的 Matrix 主服务器，但其用户认证委托给了认证服务器。
|
||
- 一个“认证服务器”，负责对用户进行认证。
|
||
|
||
本规范只关注 Matrix 客户端与主服务器之间的通信，与用于与认证服务器通信的 SSO 协议无关。不同的 Matrix 主服务器实现可能支持不同的 SSO 协议。
|
||
|
||
实现 SSO 流程的客户端和主服务器需要同时考虑 [登录](#login) 和 [用户交互式认证](#user-interactive-authentication-api)。两个过程类似，但存在细微差异。
|
||
|
||
通常，SSO 系统要求在认证服务器上配置一个“回调”URI。用户完成认证后，浏览器会被重定向到该 URI。Matrix 主服务器的实现需提供合适的端点。例如，对于 CAS 认证，主服务器应为管理员提供配置 CAS 服务器及消费票据的 REST 端点的方法。
|
||
|
||
主服务器可以选择性地向用户显示多个可选的 SSO 选项，通常以多个“使用 $provider 登录”按钮的形式展示。这些被称为“身份提供者”（IdPs）。
|
||
|
||
#### 客户端通过 SSO 登录
|
||
|
||
流程概述如下：
|
||
|
||
1. Matrix 客户端调用 [`GET /login`](/client-server-api/#get_matrixclientv3login)，以查询支持的登录类型，主服务器在响应中包含带有 `"type": "m.login.sso"` 的流程。
|
||
2. 为发起 `m.login.sso` 登录类型，Matrix 客户端引导用户浏览器跳转至用户主服务器上的 [`/login/sso/redirect`](/client-server-api/#get_matrixclientv3loginssoredirect) 端点。若用户选择了某个 `identity_providers`，则可能是该端点的 IdP 版本。
|
||
3. 主服务器以 HTTP 重定向响应至 SSO 用户界面，浏览器跟随重定向。
|
||
4. 认证服务器与主服务器交互，验证用户身份及其他认证信息，过程中可能涉及多次重定向。
|
||
5. 浏览器被引导至客户端提供的 `redirectUrl`，并带有 `loginToken` 查询参数，供客户端登录使用。
|
||
6. 客户端通过携带 `type` 为 `m.login.token` 的 [`/login`](/client-server-api/#post_matrixclientv3login) 端点调用，用登录令牌换取访问令牌。
|
||
|
||
对于原生应用，1 至 4 步通常通过打开嵌入式 Web 视图实现。
|
||
|
||
流程如下图所示：
|
||
|
||
```
|
||
Matrix 客户端 Matrix 主服务器 认证服务器
|
||
| | |
|
||
|-------------(0) GET /login------->| |
|
||
|<-------------登录类型--------------| |
|
||
| | |
|
||
| Webview | |
|
||
| | | |
|
||
|----->| | |
|
||
| |--(1) GET /login/sso/redirect-->| |
|
||
| |<---------(2) 302----------------| |
|
||
| | | |
|
||
| |<========(3) 认证流程==============>| |
|
||
| | | |
|
||
| |<--(4) 重定向到 redirectUrl--| |
|
||
|<-----| | |
|
||
| | |
|
||
|---(5) POST /login (携 login token)->| |
|
||
|<-------------访问令牌---------------| |
|
||
```
|
||
|
||
{{% boxes/note %}}
|
||
在此规范的旧版 [r0.4.0
|
||
版本](https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login) 中，如果主服务器提供 `m.login.cas` 登录流程，则可以通过 CAS 认证。本规范废弃了 `m.login.cas` 的使用，转而推荐使用 `m.login.sso`，其过程相同，仅区别在于重定向端点：对于 `m.login.cas`，使用 `/cas/redirect`，对于 `m.login.sso`，使用 `/sso/redirect`（见下文）。其他端点保持一致。
|
||
{{% /boxes/note %}}
|
||
|
||
{{% definition path="api/client-server/definitions/sso_login_flow" %}}
|
||
|
||
##### 客户端行为
|
||
|
||
客户端通过引导浏览器跳转至 [`/login/sso/redirect`](/client-server-api/#get_matrixclientv3loginssoredirect)
|
||
（或使用某个 `identity_providers` 时跳转至 [`/login/sso/redirect/{idpId}`](/client-server-api/#get_matrixclientv3loginssoredirectidpid)）
|
||
并携带适当的 `redirectUrl` 启动流程。认证成功后，浏览器将被重定向至该 `redirectUrl`。
|
||
|
||
{{% http-api spec="client-server" api="sso_login_redirect" %}}
|
||
|
||
###### 安全注意事项
|
||
|
||
1. 通过操控 `redirectUrl` 参数进行的 CSRF 攻击
|
||
|
||
客户端应校验对 `redirectUrl` 的任何请求。攻击者可能伪造查询参数，导致跨站请求伪造（CSRF）攻击。
|
||
|
||
例如，假设一个 Web 客户端托管于
|
||
`https://client.example.com`，希望在主服务器 [服务器名称](/appendices/#server-name) 为 `server.example.org` 上发起 SSO 登录，其通过在 `redirectUrl` 查询参数中存储服务器名实现重定向：
|
||
`https://server.example.org/login/sso/redirect?redirectUrl=https://client.example.com?hs=server.example.org`。
|
||
|
||
攻击者可能诱导受害者访问
|
||
`https://server.example.org/login/sso/redirect?redirectUrl=https://client.example.com?hs=evil.com`，导致客户端将登录令牌发送到攻击者控制的 `evil.com`。
|
||
|
||
为防范此类风险，客户端不得将状态（如登录主服务器的地址）存储于任何可能被外部进程修改的位置。
|
||
|
||
状态应存储在 [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) 或 Cookie 中。
|
||
|
||
2. 为进一步安全，客户端应在 `redirectUrl` 中携带唯一标识符，并拒绝不含已知标识符的回调，以防未授权登录尝试和重放攻击。
|
||
|
||
##### 服务器行为
|
||
|
||
服务器应注意，`identity_providers` 是可选的，较老的客户端可能无法正确解析该值。在这些情况下，客户端将使用通用的 `/redirect` 端点，而不是 `/redirect/{idpId}` 端点。
|
||
|
||
###### 重定向到认证服务器
|
||
|
||
服务器应如下处理 `/_matrix/client/v3/login/sso/redirect`：
|
||
|
||
1. 构建适合 SSO 系统的请求。
|
||
2. 存储足够的状态信息，以便在 SSO 流程完成后能够安全恢复流程。可通过为用户浏览器设置 Cookie 的方式完成，即在响应头中添加 `Set-Cookie`。
|
||
3. 将用户浏览器重定向到 SSO 登录页，并带上合适参数。
|
||
|
||
另请参见下方“安全注意事项”。
|
||
|
||
###### 处理认证服务器回调
|
||
|
||
通常，会有一个回调 URI 同时用于登录与用户交互式认证，由主服务器实现区分当前流程。
|
||
|
||
主服务器应验证来自 SSO 系统的响应：这可能需要对认证服务器发起附加调用，和/或验证响应中的签名。
|
||
|
||
主服务器后续操作如下：
|
||
|
||
1. 主服务器必须将认证服务器收到的用户详细信息映射为合法的 [Matrix 用户标识符](/appendices#user-identifiers)。可参见 [其他字符集的映射](/appendices#mapping-from-other-character-sets) 指南。
|
||
2. 若生成的用户标识符为新用户，则应注册为新用户。
|
||
3. 主服务器应生成一个短期登录令牌（login token）。这是一个不透明令牌，可用于以 `m.login.token` 类型调用 [`/login`](/client-server-api/#post_matrixclientv3login) API。令牌有效期建议限制在五秒左右。
|
||
4. 主服务器在最初的 `/_matrix/client/v3/login/sso/redirect` 请求所带的 `redirectUrl` 上，添加名为 `loginToken` 的查询参数，值为生成的登录令牌。（注意：`redirectURL` 可能含有已有的查询参数。若已存在一个或多个 `loginToken` 参数，应先移除后再添加新的。）
|
||
5. 主服务器将浏览器重定向到构建完成的 URI。
|
||
|
||
##### 安全注意事项
|
||
|
||
1. 主服务器应确保登录令牌不会发送给恶意客户端。
|
||
|
||
例如，假设主服务器为 `server.example.org`。攻击者诱导受害者点击
|
||
`https://server.example.org/login/sso/redirect?redirectUrl=https://evil.com`，结果导致登录令牌发送至攻击者控制的 `evil.com`，这属于 CSRF 攻击。
|
||
|
||
为缓解风险，主服务器在处理 `/_matrix/client/v3/login/sso/redirect` 端点时，重定向到 SSO 登录页前或在认证服务器回调后，应征得用户同意，将 Matrix 账号的访问权限授予 `redirectUrl` 指定的站点。
|
||
|
||
可以设置信任白名单，仅允许已知受信任的客户端 URL。主服务器自身的 [登录回退](#login-fallback) 实现可排除在外。
|
||
|
||
2. 为进一步安全，主服务器可追踪待处理请求，防止未授权认证。可通过在处理 `/_matrix/client/v3/login/sso/redirect` 时设置 Cookie，并在从认证服务器回调时校验并清除该 Cookie 实现。
|
||
|
||
#### 用户交互式认证中的 SSO
|
||
|
||
[用户交互式认证](#user-interactive-authentication-api) 适用于客户端-服务器端点，需要对用户身份进行额外确认（超出持有访问令牌以外）。通常情况下用户需要重新输入密码，但对于将认证委托给 SSO 服务器的主服务器，这意味着在用户交互式认证过程中重定向到认证服务器。
|
||
|
||
该实现基于用户交互式认证的 [回退](#fallback) 机制。
|
||
|
||
#### 客户端行为
|
||
|
||
客户端除确保实现回退机制，并将 `m.login.sso` 类型认作任意未知类型外，无需额外操作，即应为
|
||
`/_matrix/client/v3/auth/m.login.sso/fallback/web?session=<session_id>`
|
||
打开浏览器窗口。流程完成后，客户端仅携带 session 重新尝试请求。
|
||
|
||
#### 服务器行为
|
||
|
||
##### 重定向至认证服务器
|
||
|
||
服务器应以类似于 `/_matrix/client/v3/login/sso/redirect` 的方式处理
|
||
`/_matrix/client/v3/auth/m.login.sso/fallback/web`：
|
||
|
||
1. 构建适合 SSO 系统的请求。
|
||
2. 存储足够的状态信息，以便在 SSO 流程完成后能够安全恢复流程。可通过为用户浏览器设置 Cookie 的方式实现，即在响应头设置 `Set-Cookie`。
|
||
3. 将用户浏览器重定向到 SSO 登录页，并携带适当参数。
|
||
|
||
另请参阅下方“安全注意事项”。
|
||
|
||
###### 处理来自认证服务器的回调
|
||
|
||
通常，会有单一回调 URI 同时用于登录和用户交互式认证，由主服务器确定当前流程。
|
||
|
||
主服务器应对来自 SSO 系统的响应进行验证：这可能需要对认证服务器进行额外调用，和/或验证响应的签名。
|
||
|
||
随后主服务器向用户浏览器返回[用户交互式认证回退完成](#fallback)页面。
|
||
|
||
###### 安全注意事项
|
||
|
||
1. 操作确认
|
||
|
||
主服务器应确认用户同意继续操作。用户交互式认证的目标是防止被盗用的 `access_token` 用于接管用户账号。仅重定向到 SSO 系统远远不够，因为用户可能尚未意识到正在进行的操作，或 SSO 系统可能会自动确认认证。
|
||
|
||
例如，主服务器可向用户展示类似如下内容的页面：
|
||
|
||
> 某客户端正在尝试从您的账户移除设备。请通过单点登录重新认证以确认此操作。如果此操作并非您本人发起，请警惕您的账户可能被盗用！
|
||
|
||
此操作确认可发生在重定向到 SSO 认证页前（处理 `/_matrix/client/v3/auth/m.login.sso/fallback/web` 端点时）、或认证服务器回调后。如果在认证前确认，尤其要防范下述未授权认证尝试。
|
||
|
||
2. 为进一步安全，主服务器应追踪待处理请求，防止未授权认证。例如可在处理
|
||
`/_matrix/client/v3/auth/m.login.sso/fallback/web`
|
||
时设置 Cookie，并在认证服务器回调时校验并清除该 Cookie。 |