diff --git a/统一认证平台_OAuth2应用接入手册新.docx b/统一认证平台_OAuth2应用接入手册新.docx new file mode 100644 index 0000000..116fd46 --- /dev/null +++ b/统一认证平台_OAuth2应用接入手册新.docx @@ -0,0 +1,376 @@ + 统一身份认证平台 + -- -- OAuth应用接入指南 + + +文件名称：OAuth应用接入指南 +文件编号： +作　　者：王新 +版　　本：V2.0 +修订日期：2023-05-23 +审 批 人： +生效日期：2023-05-23 +审批日期： + + + + + + 北 京 吉 大 正 元 信 息 技 术 有 限 公 司 + Jilin University Information Technologies Co., Ltd. + + 更新记录 + 版本 + 编制/修改人 + 修改日期 + 修改对象 + 备注（原因、进一步的说明等） +V1.0 +樊东冬 +2022-03-03 +1. 创建文档 + +V2.0 +王新 +2023-05-23 +不使用秘钥对接 + + + + + + + + + 目录 +1 概述 4 +1.1 编写目的 4 +1.2 术语与缩写解释 4 +2 OAuth2.0协议 4 +2.1 协议介绍 4 +2.2 流程图 6 +2.3 时序图 7 +3 接口说明 7 +3.1 获取授权码接口 7 +3.2 获取访问令牌接口 9 +3.3 获取用户信息接口 10 +4 应用接入 13 +4.1 应用注册 13 +4.2 应用增加OAuth接入入口（按钮或链接） 13 +4.3 应用增加接收授权码接口 14 +4.4 应用后台获取访问令牌 15 +4.5 应用根据令牌获取用户信息 15 +5 附录 15 +5.1 错误码 15 +5.2 常见问题 16 +5.3 附件 16 + + +概述 +编写目的 + 本文档描述了OAuth2.0协议内容，接口说明以及对接流程，用于指导应用方通过OAuth2.0协议接入统一认证平台。 + 本文档阅读对象为详细设计人员、开发、测试人员。 +术语与缩写解释 + 缩写、术语 + 解 释 +UAP +统一认证平台 +code +授权码 +token +令牌 + + + + +... + + +OAuth2.0协议 +协议介绍 + OAuth2.0（Open Authorization）是一个关于授权（authorization）的开放网络标准，允许用户授权第三方应用访问他们存储在另外的服务提供者上的信息，而不需要将用户名和密码提供给第三方移动应用或分享他们数据的所有内容。 +协议特点： + * 简单：不管是OAuth服务提供者还是应用开发者，都很易于理解与使用； + * 安全：没有涉及到用户密钥等信息，更安全更灵活； + * 开放：任何服务提供商都可以实现OAuth，任何软件开发商都可以使用OAuth； +应用场景 + * 原生app授权：app登录请求后台接口，为了安全认证，所有请求都带token信息，如果登录验证、请求后台数据。 + * 前后端分离单页面应用：前后端分离框架，前端请求后台数据，需要进行oauth2安全认证，比如使用vue、react后者h5开发的app + * 第三方应用授权登录，比如QQ，微博，微信的授权登录。 + +基本概念 + * Third-party application：第三方应用程序，又称"客户端"（client），即上一节例子中的"云冲印"。 + * HTTP service：HTTP服务提供商，简称"服务提供商"，即上一节例子中的Google。 + * Resource Owner：资源所有者，又称"用户"（user）。 + * User Agent：用户代理，比如浏览器。 + * Authorization server：授权服务器，即服务提供商专门用来处理授权的服务器。 + * Resource server：资源服务器，即服务提供商存放用户生成的资源的服务器。它与认证服务器， 可以是同一台服务器，也可以是不同的服务器。 + +流程图 + + 图 2-1 +抽象的OAuth2.0流程如图所示： + (A) 客户端向资源所有者请求其授权 + (B) 客户端收到资源所有者的授权许可，这个授权许可是一个代表资源所有者授权的凭据 + (C) 客户端向授权服务器请求访问令牌，并出示授权许可 + (D) 授权服务器对客户端身份进行认证，并校验授权许可，如果都是有效的，则发放访问令牌 + (E) 客户端向资源服务器请求受保护的资源，并出示访问令牌 + (F) 资源服务器校验访问令牌，如果令牌有效，则提供服务 + +时序图 +false + 图 2-2 +接口说明 +获取授权码接口 +服务描述 +获取授权码，若已登录则返回授权码，若未登录，跳转到认证页。 +服务地址 +http(s)://【认证地址】/authcenter/getOauth2Authorize +服务方法 +GET +请求参数说明(* 为必填项) + 参数标识 + 说明 + 必填项 +response_type +固定值 'code' +* +client_id +在认证中注册的应用编码 +* +redirect_uri +应用的回调地址，应用自定义，需要与注册时提供的回调地址相同 +* +state +一个随机值, 将原样返回,用于检测是否为跨站请求(CSRF)等，客户端自定义，32位UUID +* +响应的参数说明 + + + + + + + + + +样例说明： +> 请求格式 +GET /authcenter/getOauth2Authorize?response_type=code&redirect_uri=https%3A%2F%2F172.16.22.181%3A8800%2Fsac&state=1234567891234567&client_id=SAC + + +> 应答Body格式 +HTTP/1.1 302 +https://172.16.22.181:8800/sac?code=ebc550c6-ca65-4c3d-97e8-38714c6e58ec&state=1234567891234567 + +获取访问令牌接口 +服务描述 +通过授权码换取应用令牌。 +服务地址 +http(s)://【认证地址】/authcenter/getOauth2Token +服务方法 +GET/POST +请求参数说明(* 为必填项) + 参数标识 + 说明 + 必填项 +grant_type +授权类型，固定值 'authorization_code' +* +client_id +客户端在统一认证平台上注册时的应用代码，统一认证提供 +* +client_secret +客户端在统一认证平台上注册时的应用秘钥，统一认证平台提供。 +* +code +通过第二步，从统一认证平台获取code参数值 +* +redirect_uri +应用的回调函数 +* +响应的参数说明 +access_token +令牌，用户唯一标识。 +* +expires_in +令牌的有效时间。默认为12小时。使用后会刷新。 +* +样例说明： +> 请求格式 +POST /authcenter/getOauth2Token HTTP/1.0 +Host: localhost6:11000 +Connection: close +Content-Length: 192 +Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1 +User-Agent: Apache-HttpClient/4.3.1 (java 1.5) +Accept-Encoding: gzip,deflate + +code=f44c7815-14c4-4a73-80aa-01404e3a90d3&grant_type=authorization_code&client_secret=uiasDemo&redirect_uri=http%3A%2F%2F172.16.7.227%3A8080%2FUIASClientDemo%2FuiasClient.do&client_id=uiasDemo + +> 应答Body格式 +HTTP/1.1 200 +Content-Type: text/plain;charset=UTF-8 +Content-Length: 117 +Date: Thu, 10 Sep 2020 06:00:42 GMT +Connection: close + +{"access_token":"858ef5d2-82e6-4915-b178-8bb02fb60c23","expires_in":43200} + +> 应答Body格式（错误示例，原样提示就可以） +HTTP/1.1 200 +Content-Type: text/plain;charset=UTF-8 +Content-Length: 117 +Date: Thu, 10 Sep 2020 06:00:42 GMT +Connection: close + +{" error":" A0000001"," error_description":"系统内部错误，出现运行时错误"} + +获取用户信息接口 + +服务描述 +使用应用令牌获取用户信息。 +服务地址 +http(s)://【认证地址】/authcenter/getOauth2UserInfo +服务方法 +GET/POST +请求参数说明(* 为必填项) + 参数标识 + 说明 + 必填项 +access_token +用户令牌 +* +client_id +应用编码 +* +响应的参数说明 + +根据信息传递参数模板进行数据返回，JSON格式 +* +样例说明： +> 请求格式 +GET /authcenter/getOauth2UserInfo?access_token=858ef5d2-82e6-4915-b178-8bb02fb60c23&client_id=SAC HTTP/1.0 +Host: localhost6:11000 +Connection: close +User-Agent: Apache-HttpClient/4.3.1 (java 1.5) +Accept-Encoding: gzip,deflate + +> 应答Body格式 +HTTP/1.1 200 +X-Frame-Options: DENY +Content-Type: text/plain;charset=UTF-8 +Content-Length: 4130 +Date: Thu, 10 Sep 2020 06:00:42 GMT +Connection: close + +{"userId":xxx} + +> 应答Body格式（错误示例，原样提示就可以） +HTTP/1.1 200 +Content-Type: text/plain;charset=UTF-8 +Content-Length: 117 +Date: Thu, 10 Sep 2020 06:00:42 GMT +Connection: close + +{" error":" A0000001"," error_description":"系统内部错误，出现运行时错误"} + +单点登出接口 +服务描述 +应用向认证服务发起请求单点登出的操作，认证服务会清除当前登录会话信息。如有切换用户登录的应用系统需要先调用该接口，再进行登录页的跳转。 +服务地址 +http(s)://【认证地址】/authcenter/userLogout +服务方法 +GET/POST（application/x-www-form-urlencoded） +请求参数说明(* 为必填项) + 参数标识 + 说明 + 必填项 +access_token +【令牌】有效的身份令牌信息。 +* +client_id +【应用标识】应用注册时的唯一标识。 +* +响应的参数说明（返回数据为JSON格式） +code +错误码 + +message +错误描述 + +样例说明 +> 请求格式 + +> 应答Body格式 +{ + "code": "0", + "message": "success" +} + +验证Token的有效性 +服务描述 +应用服务向认证服务校验Token的有效性 +服务地址 +http(s)://【认证地址】/authcenter/checkTAValid +服务方法 +POST（application/json） +请求参数说明(* 为必填项) + 参数标识 + 说明 + 必填项 +access_token +【令牌信息】上一步返回的access token令牌。 +* +client_id +【应用标识】应用注册时的唯一标识。 +* +响应的参数说明（返回数据为JSON格式） +code +错误码 + +message +错误描述 + +data +数据节点 + +样例说明： +> 请求格式 + +> 应答Body格式 +{ + "code": "0", + "data": "", + "message": "success" +} + + +应用接入 +应用注册 + 应用需要提供访问地址及重定向地址，用于统一认证的应用注册，注册后，统一认证提供应用标识(client_id)、应用安全口令(client_secret)和应用密钥。 +注： +1) 访问地址：即如访问该应用的主地址。 + 样例： http(s)://192.168.1.100:8080/oa或http(s)://192.168.1.100:8080/。 +2) 重定向地址：在oauth认证过程成，统一认证通过该地址返回授权码(code)信息。 + 样例：http(s)://192.168.1.100:8080/oa/oauthCode。 +应用增加OAuth接入入口（按钮或链接） +两种实现方式 + 1）在需要接入的应用界面上增加JIT IAM按钮图标，该按钮能实现跳转到统一认证登录页实现认证， +如图： + + + 2）应用访问过程不需要再显示应用的登录界面，直接显示统一认证的登录页，此过程需要应用将登录页的跳转行为修改为指向统一认证登录页。（推荐） +应用增加接收授权码接口 + 应用系统中提供一个服务接口（URL），即重定向地址对应接口，用于接收统一认证返回的授权码，URL参数形式接收授权码 + 用户成功登录后，则会跳转（http 302）到指定重定向地址。并在地址后附带两个参数authorization code（授权码）和原始的state值，如：http://重定向地址?code=授权码&state=test。 + 样例： + http(s)://192.168.1.100:8080/oa/oauthCode? code=f44c7815-14c4-4a73-80aa-01404e3a90d3&state=68f7b6bd-fedb-4f9d-9617-b4cbf57b2c1b + + 用户登录页或获取授权码出错时，会跳转到统一认证平台错误页。显示错误码与错误描述。 +应用后台获取访问令牌 + 应用后台收到授权码code后到统一认证平台调用 / authcenter/getOauth2Token接口获取访问令牌。 +应用根据令牌获取用户信息 + 应用获取访问令牌成功后，使用访问令牌到统一认证平台调用/authcenter/getOauth2UserInfo接口获取用户信息。。 + 获取到用户信息，即可根据用户返回响应，为用户提供服务。从而完成单点登录过程。 + +常见问题