工程师接入手册

## 单点登录协议
OpenID 连接
SAML断言

### OpenID 连接：使用jwt(json  web令牌）是一个签名的json文档

![](/media/202312/2023-12-04_162453_324308.png)
- 授权码许可
它是通过授权码 code 获取用户级别的访问令牌。这是很常见的授权许可类型，在各种社交登录的场合会遇见。比如对接微信登录，在浏览器的跳转过程中，你就会见到 code 以 url 参数形式传递。
流程：
	1. 用户使用浏览器连接到应用程序。应用程序检测到用户未登录该应用程序。

3. 应用程序将浏览器重定向到 MaxId 进行身份验证。

4. 应用程序将回调 URL 作为浏览器重定向中的查询参数传递。MaxId 在身份验证成功后使用该参数。

5. MaxId 对用户进行身份验证并创建一次性、短暂的临时代码。

6. MaxId 使用回调 URL 重定向到应用程序，并将临时代码作为查询参数添加到回调 URL 中。

11. 应用程序提取临时代码并对系统进行后台 REST 调用，以将代码交换为身份以及访问和刷新令牌。为了防止重放攻击，临时代码不能多次使用。

- 客户端凭据许可
它通过第三方软件的 app_id 和 app_secret 获取客户端的访问令牌。注意，这里拿到的访问令牌是客户端级别的，而不是授权码许可类型中的用户级访问令牌，因此相当于该客户端的访问令牌权限更广，不如授权码许可类型的粒度细致。也就是说，一旦授权服务器给了客户端这样一个客户端级别的访问令牌，那么，该客户端在令牌有效期内就可以获取任何用户的信息，不像授权码许可类型拿到的只是某个用户的访问令牌，只能获取该用户的信息。而且，在获取这个粗粒度令牌的过程中，是不需要用户参与的，也不需要用户授权。本质上，客户端凭据许可，就像普通的用户名密码登录一样，只是在这里，app_id 和 app_secret 是事先注册（备案）好的，只用在第一次换取访问令牌的过程中，后续操作（接口请求）全部使用访问令牌来决定是否有权限。这样的好处是将 app_id 和 app_secret 的暴露降至最低，从而减小攻击面。但是授权服务器仍然需要监控第三方软件（客户端）的行为，确保它不滥用访问令牌，如果发现滥用，可以吊销其 app_id 和 app_secret（黑名单）。

- 隐式流程
一个基于浏览器的协议。隐式流程的工作方式与授权代码流程类似，但不返回授权代码，而是返回访问令牌和 ID 令牌。
***根据当前的OAuth 2.0 安全最佳当前实践，不应使用此流程。此流程将从未来的OAuth 2.1 规范中删除。***
**原因**：
	1. 此方法减少了将授权代码交换为访问令牌的额外调用的需要。
	2. 通过重定向 URI 传输令牌时，访问令牌可能会在浏览器历史记录中泄漏（见下文）。
	3. 此流程不向客户端提供刷新令牌。因此，访问令牌必须是长期存在的，或者用户在过期时必须重新进行身份验证。
**流程**：

- 资源所有者密码凭据授予（直接访问授予）
它是通过资源拥有者（即用户）的用户名和密码来获取用户级别的访问令牌。这相当于用户把自己的用户名和密码存储在了第三方软件（客户端）那里，所以这个第三方软件（客户端）必须是相当可靠的，不滥用用户的安全凭据信息。

- 客户凭证授予
客户端凭据授予根据与客户端关联的服务帐户的元数据和权限创建令牌，而不是获取代表外部用户工作的令牌。客户端凭证授予由 REST 客户端使用。
本文重要介绍授权码许可和资源用拥有者凭证许可

- Auth 2.0 设备授权授予

这是由在输入功能有限或缺乏合适的浏览器的互联网连接设备上运行的客户端使用的。以下是该协议的简要摘要：

应用程序向 MaxId 请求设备代码和用户代码。MaxId 创建设备代码和用户代码。MaxId 将包括设备代码和用户代码的响应返回给应用程序。

应用程序向用户提供用户代码和验证 URI。用户通过其他浏览器访问验证URI进行认证。您可以定义一个简短的verification_uri，它将被重定向到 MaxId 外部的 MaxId 验证URI（/realms/realm_name/device） - fe在代理中。

应用程序反复轮询 MaxId 以查明用户是否完成了用户授权。如果用户身份验证完成，应用程序将设备代码交换为身份、访问和刷新令牌。

- OIDC CIBA 补助金（客户端发起的反向通道身份验证授权）
此功能供希望通过直接与 OpenID 提供商通信来启动身份验证流程的客户端使用，而不需要像 OAuth 2.0 的授权代码授予那样通过用户浏览器进行重定向。以下是该协议的简要摘要：

客户端向 MaxId 请求一个 auth_req_id，用于标识客户端发出的身份验证请求。MaxId 创建 auth_req_id。

收到这个auth_req_id后，该客户端需要反复轮询MaxId以从MaxId获取Access Token、Refresh Token和ID Token以换取auth_req_id，直到用户通过身份验证。

管理员可以根据CIBA Policy领域配置客户端启动的反向通道身份验证 (CIBA) 相关操作。

**代码示例：**
#### 1.授权码许可
- 用户使用浏览器连接到应用程序。应用程序检测到用户未登录该应用程序。
- 应用程序将浏览器重定向到MaxId进行身份验证。

- 应用程序将回调 URL 作为浏览器重定向中的查询参数传递。MaxId 在身份验证成功后使用该参数。

- MaxId 对用户进行身份验证并创建一次性、短暂的临时代码。

- MaxId 使用回调 URL 重定向到应用程序，并将临时代码作为查询参数添加到回调 URL 中。

- 应用程序提取临时代码并对 MaxId 进行后台 REST 调用，以将代码交换为身份以及访问和刷新令牌。为了防止重放攻击，临时代码不能多次使用。
（系统在令牌的生命周期内很容易受到令牌被盗的影响。出于安全性和可扩展性的原因，访问令牌通常设置为快速过期，因此后续令牌请求会失败。如果令牌过期，应用程序可以使用登录协议发送的附加刷新令牌来获取新的访问令牌。）
![](/media/202312/2023-12-03_144558_262475.png)

首先在客户端中添加相应的客户端信息

首先我们需要获得授权码 code 获取用户级别的访问令牌，调用auth接口破拼接上我们重定向的路径，重定向的路径就是我们自己所写的接口的路径，需要我们提供客户端的ID(CLIENT_ID),领域名称（realmName），以及我们自己的接口（http://localhost:8080//enhance_plugins/callback）
ps:示范中realmName=master client_ID=Enhance
`
http://maxid2.demo.jzkg.cn/realms/｛realmName｝/protocol/openid-connect/auth?response_type=code&client_id=｛CLIENT_ID｝ &redirect_uri=http://localhost:8080/enhance_plugins/callback
`
用户对接auth之后，会跳转到登录页面
登录成功后，MaxId会根据你的回调地址，重定向到你的系统中，并带着code和redirect_uri及session等信息。
http://localhost:8080/callback?redirect_uri=http://localhost:8080/hello&session_state=45691669-f290-4991-8f43-d6c411a91b7c&code=b3921500-f6a6-494d-ad23-41b75c436fe7.45691669-f290-4991-8f43-d6c411a91b7c.02bb9b29-2c53-45c7-b009-43e3c78c6aff

三方应用系统的回调地址：redirect_uri
授权码：code
会话标识：session_state
通过这个api获得返回的code，在通过这个code,调用token接口
，我们即可以获得token中acces_stoken。client_secret是客户端对应的客户端密码。
http://maxid2.demo.jzkg.cn/realms/master/protocol/openid-connect/token

- grant_type = client_credentials
POST:
{
"code":"code",
"grant_type": "client_credentials",
"Content-Type", "application/x-www-form-urlencoded"
"client_secret":"XXXX",//在系统中获取
"client_id":"XXXXX"
"redirect_uri" :"http://localhost:8080/enhance_plugins/callback"
}
`

或者

- grant_type=authorization_code
POST:
{
"code":"code",
"grant_type": "authorization_code",
"Content-Type", "application/x-www-form-urlencoded"
"client_secret":"XXXX",//在系统中获取
"client_id":"XXXXX"
"redirect_uri" :"http://localhost:8080/enhance_plugins/callback"
}

获取token如下
`
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ6ZEtJaXN1SGVveGxycVpFZVE4ZUhOc2ZLM01Bclp3VkVZelVyTXNzMjFVIn0.eyJleHAiOjE3MDE1ODI5NzUsImlhdCI6MTcwMTU4MjkxNSwianRpIjoiOWMxOGJiMDQtNzZiOS00MTcwLWE2ZDAtOTQxYzRhYzdiYjY0IiwiaXNzIjoiaHR0cDovL21heGlkMi5kZW1vLmp6a2cuY24vcmVhbG1zL21hc3RlciIsInN1YiI6IjA4YTAxZmY4LWYzOTgtNDIwYy05Yjc5LWIzYjU4NDMwMjIyNyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFkbWluLWNsaSIsInNlc3Npb25fc3RhdGUiOiJkZTBlOTk5NS00ODFiLTRlNzgtYWMxYy1lZjQ4YWY5NjYxMTIiLCJhY3IiOiIxIiwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwic2lkIjoiZGUwZTk5OTUtNDgxYi00ZTc4LWFjMWMtZWY0OGFmOTY2MTEyIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhZG1pbiJ9.a96pZYRB3ZM0blG4EF8UgCsBPBzz9w-spbWDQ3oYHg1cB1aIcEBlTy48-BvS_DAXhYNHheOUjhgxkyGo6d9aRR1WjwSj4ESWDwuTn_qbzq56WB3WIEy8Tm_Kjij14tz7r7v0Wyxuh0ODQemtoxCAUYizVrp-ESrOOakknFUJslB0YsMN4v8dE_s0Wd9nPdnFNsP-xrlMtZziQocgrdcXVLRGA7QcBe9y2rTzGOiqzTBsq3vCJwqbFmTyhEvUYJ_ZrSPAhatX4cdFVs4FAG4Re9Dk5Bqqb3cS6TujYE0TVAOH0fazfkXZvG1vcz3Gy9HCLlVsiM0rlOuDOPTJaEIM2Q",
    "expires_in": 60,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiMmZkZjMyZC1hMDY0LTRjZDktYTJkYS0yZTk1MTJlZGFiMzUifQ.eyJleHAiOjE3MDE1ODQ3MTUsImlhdCI6MTcwMTU4MjkxNSwianRpIjoiZTYyMjYyNWQtZTgwOC00N2NmLTg1NDItMWYxNjgzN2I0NmIyIiwiaXNzIjoiaHR0cDovL21heGlkMi5kZW1vLmp6a2cuY24vcmVhbG1zL21hc3RlciIsImF1ZCI6Imh0dHA6Ly9tYXhpZDIuZGVtby5qemtnLmNuL3JlYWxtcy9tYXN0ZXIiLCJzdWIiOiIwOGEwMWZmOC1mMzk4LTQyMGMtOWI3OS1iM2I1ODQzMDIyMjciLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYWRtaW4tY2xpIiwic2Vzc2lvbl9zdGF0ZSI6ImRlMGU5OTk1LTQ4MWItNGU3OC1hYzFjLWVmNDhhZjk2NjExMiIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsInNpZCI6ImRlMGU5OTk1LTQ4MWItNGU3OC1hYzFjLWVmNDhhZjk2NjExMiJ9.EDDPkFoHpBcWNaSaerk_AXuOI3aDXaG35QGKDBLFNLY",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "de0e9995-481b-4e78-ac1c-ef48af966112",
    "scope": "profile email"
}
`
将access_token经过jwt解析可以获取用户的信息，也可以将assess_token带入获得其他的接口。

以获取用户中的attribute属性为例，调用器接口传入相关参数

![](/media/202312/2023-12-03_152053_879216.png)
![](/media/202312/2023-12-03_151731_302503.png)

![](/media/202505/2025-05-14_100022_993643.png)

#### 2.资源拥有者凭证许可
这个模式只需要用户名和密码即可获得用户的token信息

http://maxid2.demo.jzkg.cn/realms/DemoRelam/protocol/openid-connect/token

POST:
{
"grant_type": "password",
"username": "",
"password": "",
"client_secret":"",
"client_id":"DemoClient"
}

![](/media/202312/2023-12-03_151348_040574.png)

## SAML断言：一种基于XML的开放标准，用于在服务之间交换身份信息，

![](/media/202312/2023-12-04_162244_110711.png)
1.访问应用程序如谷歌邮箱
2.Gmail服务检测到用户来自工作域，向浏览器返回SAML身份认证请求
3.浏览器将用户重定向到SAML身份验证请求中指定的公司的身份提供商。
4.身份提供商显示登录页面，用户在其中输入登录凭据
5.用户通过验证后，
6.身份提供商会生成SAML响应，并将其返回浏览器（这称为SAML断言）
SAML断言是经过加密的XML文档，其中包含用户信息以及用户可以通过服务提供商访问的内容
7.浏览器讲签名的SAML断言转发给服务提供商
8.服务提供商验证断言是否由身份提供商签署，此验证通常通过公钥加密完成
9.服务提供商根据SAML断言中指定的允许的用户访问的内容讲受保护的资源返回浏览器
另外一个客户端
1.和上述Gmail一样，访问github服务器。
2.服务器会检测工作域并将SAML身份认证请求发送回浏览器
3.浏览器再次将用户重定向到身份提供商
4.由于用户已经使用身份提供商，所以跳过登录，为github生成SAML断言,详细说明用户可以在那里访问的内容
5.SAml断言将返回浏览器
6.并将其转发到github，gb会验证签名的断言，并相应的授予访问权限