锦中MaxId统一身份认证系统接入手册
工程师接入手册
对接前系统信息添加
系统导入
接口文档
对接文档（需要的接口和对接出现的问题的设置）
锦集网-锦中集团文档分享与下载平台，提供产品操作手册、产品资料、知识文档、技术集锦等在线学习。
-
+
首页
对接文档（需要的接口和对接出现的问题的设置）
**身份认证对接手册** # **系统应用信息添加** 首先在身份认证系统系统添加对接的应用系统的相关信息，具体的操作如下（可联系管理员进行添加） 1. 创建领域 建议创建一个新的领域，进行其他应用的对接  1. 创建客户端  客户端类型：OpenIDConnect 客户端Id： 系统代码 名称：系统名称 描述： 始终显示在UI中： - 1. 创建客户端  客户端认证 true 授权 (按需） 认证流程 标准流程 + 直接访问授权  根网站： 网站地址 首页URL： 网站首页地址 有效的重定向URI：网站地址+/\* 有效的注销后重定向URI: 网站地址+/\* 网络根源  1. 注销设置  1. 凭证 对应的就是对接的客户端密钥  1. 客户端作用域 获取用户信息时包含的内容，按需调整  添加的是客户端作用域的中定义的参数  # **对接需要用到的相关接口** 1. ## **登录跳转接口** GET /realms/{realmName}/protocol/openid-connect/auth realmName: HCAEDU 请求参数（Query 参数） |**参数名**|**是否必填**|**说明**|**示例**| | :-: | :-: | :-: | :-: | |client\_id|✅|客户端ID|rsxt| |response\_type|✅|响应类型（授权码模式固定为 code）|code| |scope|✅|请求范围（包含 openid 才会返回 id\_token）|openid profile email| |redirect\_uri|✅|登录后回调地址|https://hr.artcollegehb.cn/epxing-frame/sso/login| |state|⚙️ 可选|防CSRF的随机字符串|xyz123| 1. ## **授权码模式(token获取)** POST /realms/{realmName}/protocol/openid-connect/token realmName: HCAEDU **请求头**（Headers） Content-Type: application/x-www-form-urlencoded **请求体（Body，表单提交）** |**参数名**|**是否必填**|**说明**| | :-: | :-: | :-: | |grant\_type|✅|固定为 authorization\_code| |code|✅|登录回调时收到的授权码| |client\_id|✅|客户端 ID| |client\_secret|✅|客户端密钥（机密客户端才需要）| |redirect\_uri|✅|必须与授权时一致| |scope|⚙️ 可选，但建议带 openid|| 1. ## **用户凭证模式，需要知道当前领域的用户的账号和密码，获取用户的token** POST /realms/{realmName}/protocol/openid-connect/token realmName: HCAEDU **请求头** Content-Type: application/x-www-form-urlencoded **请求体** |**参数名**|**是否必填**|**说明**| | :-: | :-: | :-: | |grant\_type|✅|固定为 password| |client\_id|✅|客户端 ID| |client\_secret|✅|客户端密钥| |username|✅|用户账号| |password|✅|用户密码| |scope|⚙️ 可选，openid 可返回 id\_token|| 1. ## **通Access Token获取用户信息** GET /realms/{realm-name}/protocol/openid-connect/userinfo realmName: HCAEDU (原本展示的name,后面对接修改为了username) 请求头 |**Header**|**示例值**|**说明**| | :-: | :-: | :-: | |Authorization|Bearer token|Access Token（从 token 接口获取）| |Content-Type|application/json|可选，一般 GET 不需要指定| 提示：使用userinfo 接口需要在获取token的请求参数中添加“scope=openid”。然后在客户端作用域中添加新的作用域“openid”(如下图)，协议选择OIDC，在映射中选择我们想要获取的值。  提示：如果出现“Offline tokens not allowed for the user or client？”，需要在用户的角色映射中添加如下图中的offline\_access.,或者在默认的领域角色中添加“[offline_access](https://authserver.artcollegehb.cn/admin/master/console/#/HCAEDU/roles/955297a6-926d-47e4-a879-91ea828c732d/details)”,这个角色是每个用户都有的。    返回参数 |<p>{</p><p>` `"sub": "f5f9e9b8-xxxx-xxxx-xxxx-xxxxxxxxxxxx",</p><p>` `"email\_verified": true,</p><p>` `"preferred\_username": "admin",</p><p>` `"username": "管理员",</p><p>` `"email": "admin@example.com"</p><p>}</p>| | - | |字段|说明| | :-: | :-: | |sub|用户唯一 ID| |preferred\_username|用户名（默认）| |username|显示名称| |email|邮箱| |email\_verified|邮箱是否已验证| |其他自定义字段|客户端作用域添加| ## **部分接口（可能需要）：** 请求头说明 |参数名|是否必须|示例值|说明| | :-: | :-: | :-: | :- | |Authorization|是|Bearer {access\_token}|用于认证的访问令牌| |Content-Type|是|application/json|请求体的格式为 JSON| |Accept|否|application/json|返回数据期望格式为 JSON（可选）| 1. ## **用户需要在token中解析 或者通过userinfo 接口获取用户的组织信息的时候，需要在客户端领域添加如下参数** 点击客户端作用域，名称自定义，用处是在获取token中的scope 添加自定义的值   具体的映射类型的选择如图，注意令牌声明名称必填，是获取参数时候对应的键值，下面通过userinfo 获取的参数示例，对token解析也是相同的。    ### **用户** #### **用户列表** 请求方式: GET 请求地址: /admin/realms/{realm}/users 接口说明: 获取 realm 中所有用户，可分页查询。 参数说明： {realm} 是领域的名称 • 请求参数: first: 起始索引（可选） max: 最大返回数量（可选） username: 按用户名过滤（可选） • 返回参数: [{id, username, email, attributes}]: 返回用户列表 |<p>1. [</p><p>2. {</p><p>3. "id": "48e04677-3d74-49f0-9c40-e3a480682f7d",</p><p>4. "createdTimestamp": 1744871075538,</p><p>5. "username": "admin",</p><p>6. "enabled": true,</p><p>7. "totp": false,</p><p>8. "emailVerified": false,</p><p>9. "firstName": "张",</p><p>10. "lastName": "无极",</p><p>11. "disableableCredentialTypes": [],</p><p>12. "requiredActions": [],</p><p>13. "notBefore": 0,</p><p>14. "access": {</p><p>15. "manageGroupMembership": true,</p><p>16. "view": true,</p><p>17. "mapRoles": true,</p><p>18. "impersonate": true,</p><p>19. "manage": true</p><p>20. }</p><p>21. },</p><p>22. {</p><p>23. "id": "d343e923-e81d-4745-8104-9de4ebcfb023",</p><p>24. "createdTimestamp": 1745559222223,</p><p>25. "username": "qwerty",</p><p>26. "enabled": true,</p><p>27. "totp": false,</p><p>28. "emailVerified": false,</p><p>29. "firstName": "简",</p><p>30. "lastName": "单",</p><p>31. "email": "1928300760@163.com",</p><p>32. "disableableCredentialTypes": [],</p><p>33. "requiredActions": [],</p><p>34. "notBefore": 0,</p><p>35. "access": {</p><p>36. "manageGroupMembership": true,</p><p>37. "view": true,</p><p>38. "mapRoles": true,</p><p>39. "impersonate": true,</p><p>40. "manage": true</p><p>41. }</p><p>42. }</p><p>43. ]</p><p></p>| | :- | #### **用户新增** 请求方式: POST 请求地址: /admin/realms/{realm}/users 接口说明: 在指定 realm 中创建用户。 • 请求参数: username: 用户名 enabled: 是否启用用户（true/false） firstName: 名字 lastName: 姓氏 email: 邮箱 attributes: {‘department’: ‘部门’, ‘position’: ‘岗位’} • 返回参数: status: 201 表示创建成功；409 表示用户名冲突用户删除 -------------------------------------------------- 请求参数： |<p>1. {</p><p>2. "username": "user3",</p><p>3. "email": "user3@example.com",</p><p>4. "enabled": true,</p><p>5. "emailVerified": false, //</p><p>6. "firstName": "John", //姓</p><p>7. "lastName": "Doe", //名</p><p>8. "credentials": [</p><p>9. {</p><p>10. "type": "password",</p><p>11. "value": "TempPass123", //密码</p><p>12. "temporary": true // 导入后需首次登录修改密码</p><p>13. }</p><p>14. ],</p><p>15. "groups": [ // 用户所属群组路径</p><p>16. "/群组1/群组3"</p><p>17. ],</p><p>18. "attributes": { // 自定义属性</p><p>19. "department": "IT",</p><p>20. "phone": "123-456-7890"</p><p>21. }</p><p>22. }</p><p></p>| | :- | #### **用户删除** 请求方式: DELETE 请求地址: /admin/realms/{realm}/users/{user-id} 接口说明: 根据用户 ID 删除用户。 • 请求参数: user-id: 用户的 ID（可通过获取用户接口获取） realm: 领域名称 • 返回参数: status: 204 表示删除成功 #### **用户信息更新** 请求方式 PUT 请求地址：/admin/realms/{realm}/users/{user-id} 接口说明： 根据用户的 ID 更新用户信息 • 请求参数 realms：领域名称 user-id: 用户的 ID（可通过获取用户接口获取) • 返回参数: status: 204 表示更新成功 ### **组织** #### **组织列表** 请求方式 GET 请求地址 /admin/realms/{realm}/groups 接口说明： 查询当前领域的组织信息 • 请求参数 search: 按名称模糊搜索 first: 分页起始索引 max: 返回最大条目数 #### **组织下对应用户** 请求方式：GET 请求地址：/admin/realms/{realm}/groups/{group-id}/members 接口说明： 根据组织的id,查询组织下对应的用户 • 请求参数 realm: 领域名称 group-id: 组织对应的id(可通过列表进行查询) Authorization: Bearer {token} 返回参数 |<p>1. [{</p><p>2. "id": "",</p><p>3. "createdTimestamp": 1745282804407,</p><p>4. "username": "",</p><p>5. "enabled": true,</p><p>6. "totp": false,</p><p>7. "emailVerified": false,</p><p>8. "firstName": "",</p><p>9. "lastName": "",</p><p>10. "attributes": {</p><p></p><p>12. },</p><p>13. "disableableCredentialTypes": [],</p><p>14. "requiredActions": [</p><p>15. "D"</p><p>16. ],</p><p>17. "notBefore": 0</p><p>18. }]</p><p></p>| | :- | ### **角色** #### **领域角色列表** 请求方式 GET 请求地址 /admin/realms/{realm}/roles 接口说明： 查询当前领域的角色信息 • 请求参数 search: 按名称模糊搜索 first: 分页起始索引 max: 返回最大条目数 返回参数 #### **用户角色** 请求方式 GET /admin/realms/{realm}/users/{user-id}/role-mappings/realm 路径参数 Realm : HCAEDU user-id：用户的UUId 请求头中传参： Authorization： Bearer token Content-Type: application/json 字段说明 |**字段名**|**类型**|**说明**| | :-: | :-: | :-: | |id|String|角色 ID（UUID）| |name|String|角色名称（学生，教职工）| |description|String|角色描述| |composite|Boolean|是否为组合角色（composite role）| |clientRole|Boolean|是否为客户端角色（此处为 false，说明是领域角色）| （补充： 学生和教师的角色是领域角色，因此此处获取的是“composite”为false 的信息，） #### **特定领域角色的用户列表** 请求方式 GET /admin/realms/{realm}/roles/{role-name}/users 请求头 |**Header 名称**|**是否必填**|**值**| | :-: | :-: | :-: | |Authorization|是|Bearer {access\_token}| |Content-Type|否|application/json| 路径参数 |**参数名**|**是否必填**|**类型**|**说明**| | :-: | :-: | :-: | :-: | |realm|是|String|领域名称，如：HCAEDU| |role-name|是|String|角色名称，例如：学生、教职工| 查询参数 Query Parameters（可选） |**参数名**|**类型**|**说明**| | :-: | :-: | :-: | |first|int|起始索引，分页使用| |max|int|返回数量，默认无限制| 响应示例: |<p>[</p><p>` `{</p><p>` `"id": "d3928190-0af3-4f29-8f34-9d5bcbaf1c44",</p><p>` `"username": "teacher001",</p><p>` `"enabled": true,</p><p>` `"emailVerified": false,</p><p>` `"firstName": "王",</p><p>` `"lastName": "老师",</p><p>` `},</p><p>` `{</p><p>` `"id": "f19d8871-cf6d-47fb-9538-96232aefbc06",</p><p>` `"username": "teacher002",</p><p>` `"enabled": true,</p><p>` `"emailVerified": true,</p><p>` `"firstName": "李",</p><p>` `"lastName": "老师",</p><p>` `}</p><p>]</p>| | - | （此处的角色是中文，因此路径URL 中需要进行编码) # **修改密码** ## **接口** PUT /admin/realms/{realm}/users/{id}/reset-password 路径参数 realm：用户所属领域 id：用户 ID（不是用户名，可以通过/admin/realms/{realm}/users?username=<name> 查询） 请求头中传参： Authorization： Bearer token Content-Type: application/json 请求体： |<p>{</p><p>` `"type": "password",</p><p>` `"value": "NewPassword123!",</p><p>` `"temporary": false</p><p>}</p>| | :- | ## **页面** 普通用户跳转修改密码页面 路径：<https://authserver.artcollegehb.cn/realms/HCAEDU/account/#/security/signingin> 这是具体的url, 普通用户进入他的页面也是可以看到他的修改密码的按钮的 # **退出登录** 1. 用户主动退出 接口：GET /realms/{realm-name}/protocol/openid-connect/logout 参数说明： |**参数**|**是否必须**|**说明**| | :-: | :-: | :-: | |id\_token\_hint|✅|用户登录返回的 ID Token，身份认证 用它识别用户会话| |post\_logout\_redirect\_uri|可选|退出后跳转地址，需在客户端配置 **有效的注销后重定向 URI**| |state|可选|自定义状态，身份认证会原样带回，可用于防 CSRF 或前端标记| 1. 后端通道注销 需要再客户端配置后端通道注销地址，假设地址如下： “<https://example.com/api/auth/backchannel-logout”> 系统将会调用这个接口，实现退出（把对应的jwt令牌写入黑名单） 请求方式: POST 请求头：Content-Type: application/x-www-form-urlencoded 请求参数;logout\_token 应用的处理逻辑： 1. 验证 logout\_token 签名。 1. 根据 sid 或 sub 找到本地用户会话并清理。 1. 返回 200 表示处理成功。
简彬
2025年12月25日 15:52
分享文档
收藏文档
上一篇
下一篇
微信扫一扫
复制链接
手机扫一扫进行分享
复制链接
Markdown文件
PDF文档
PDF文档（打印）
分享
链接
类型
密码
更新密码