1. 概述
2. 术语说明
4. 应用集成帐号登录
4.1 集成总体时序
5. 应用集成智慧教育云平台
5.1 集成总体时序
6. 开放平台帐号中心接口定义
默认约定
6.1 获取授权码页面
请求URL:
请求方式：
请求参数：
关于scope
6.2 获取访问令牌
请求URL:
请求方式：
请求参数：
请求示例[ticket方式，code类似]（body）
返回参数：
6.3令牌续约
请求URL:
请求方式：
请求参数：
返回参数：
请求URL:
请求方式：
请求参数：
返回参数：
请求方式：
请求参数：
7. 接入地址
{api-gateway-host}
{unified_domain}
8. 授权范围的说明(scope)

1. 概述

本文档主要面向智慧教育云平台的第三方应用开发者，旨在通过接入准备，集成时序，接口定义等内容指导开发者实现第三方应用与智慧教育云平台就用户认证授权的集成对接。

2. 术语说明

名词	含义
open_id	开放平台帐号中心给应用的授权用户的唯一标识，用来标记一个具体的用户
access_token	开放平台帐号中心颁发给应用的用于调用资源接口的访问令牌
code	授权码
oauth2	一种标准授权协议 https://oauth.net/2/
# 3. 接入准备
第三方应用接入本开放平台需要先提交申请,提交的信息包括应用名称、应用介绍、应用域名、应用 LOGO、应用负责人等信息（提交途径另行沟通），

　　开放平台审核通过后颁发Access Key ID(AK)与Secret Access Key(SK)，其中应用秘钥要求保存在应用的服务端。

4. 应用集成帐号登录

指第三方应用把智慧教育云平台帐号作为应用的第三方登录来对接，应用需要做的步骤如下
　　（1）在第三方登录(如微信、微博等)页面集成智慧教育云平台帐号的登录链接
　　（2）采用授权码模式与智慧教育云平台开放平台帐号中心对接，即先向开放平台帐号中心![]获取授权码
　　（3）通过授权码获取访问令牌
　　（4）通过访问令牌获取资源信息，如用户信息。

4.1 集成总体时序

　　上述时序需要使用 6.1，6.2，6.3，6.4 接口

5. 应用集成智慧教育云平台

　　指第三方应用通过开放平台帐号中心的能力实现与智慧教育云平台单点登录，即用户通过智慧教育云平台登录后，访问第三方应用均无需二次认证,第三方应用需要支持的能力如下

　　（1）接收智慧教育云平台跳转第三方应用时 URL 传递的临时会话票据 ticket
　　（2）通过 ticket 向开放平台帐号换取访问令牌 access_token
　　（3）通过 access_token 请求资源 API，如获取用户信息等
　　（4）通过令牌续约来延续 access_token 有效期

5.1 集成总体时序

上述时序需要使用 6.2，6.3，6.4 接口

6. 开放平台帐号中心接口定义

默认约定

没有特殊说明的情况下，POST方法提交的请求默认：http header Content-Type: application/json; 数据以json格式提交

例：

HTTP HEADER :

 Accept: application/json
 Content-Type: application/json

BODY DATA:

{
  "access_key_id": "9xxxad82-XXXX-0000-XXXX-02d26bc31db6",
  "secret_access_key": "XX56aab7c3d642458f2af8067XXXXXXX",
  "ticket": "XXXXAAAA-XXXX-4e7e-0000-0b9a92ca2b3d",
  "grant_type": "ticket"
}

所有接口请求都需要HMac签名详见【认证】开放平台API的认证说明

6.1 获取授权码页面

请求URL:

http://{unified_domain}/openplatform/connect?sdp-app-id={sdp-app-id}response_type={response_type}&access_key_id={access_key_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}&type={type}

请求方式：

请求参数：

参数名	是否必须	类型	说明
sdp-app-id	是	string	开放平台租户标识（获取方式如下）
access_key_id	是	string	应用唯一标识,应用注册时由开放平台分配
redirect_uri	是	string	授权成功的回调地址,其中域名必须符合应用注册时填写的安全域名
response_type	是	string	响应类型，目前仅支持传code
scope	是	string	scope_base（获取你的公开信息）与scope_userinfo（获取你的详细信息）
state	是	string	第三方应用自行产生，可以使用随机字符串
type	否	string	h5 页面，不传为web页面，传‘h5’为h5页面
#### 返回参数：
- 授权成功开放平台帐号中心会返回302 重定向到应用提供的{redirect_uri}页面并且带上code和state参数
{redirect_uri}?code={code}&state={state}
- 若用户禁止授权，则重定向后不会带上code参数，仅会带上state参数{redirect_uri}?state={state}

关于scope

scope标识应用授权作用域，拥有多个作用域用空格分隔，目前可组合的项有
scope_base: 该作用域需显式地向用户询问是否允许某某应用访问您的基本信息(昵称，头像，性别）

6.2 获取访问令牌

请求URL:

http://{api-gateway-host}/oauth/access_token

请求方式：

POST

请求参数：

参数名	是否必须	类型	说明
access_key_id	是	string	应用唯一标识,应用注册时由开放平台分配
secret_access_key	是	string	应用密钥,应用注册时由开放平台分配
ticket	二选一	string	填写智慧教育云平台跳转到第三方应用目标页时传递的ticket
code	二选一	string	授权码，grant_type 传 authorization_code 时必填
grant_type	是	string	授权类型，固定传 authorization_code 或 ticket

请求示例[ticket方式，code类似]（body）

HTTP HEADER

Accept: application/json
Content-Type: application/json

HTTP BODY

{
  "access_key_id": "9xxxad82-0000-4b83-aca7-02d26bc31db6",
  "secret_access_key": "XX56aab7c3d642458f2af8067ab0869e",
  "ticket": "191fc3b5-DDDD-XXXX-OOOO-0b9a92ca2b3d",
  "grant_type": "ticket"
}

返回参数：

参数	含义
access_token	访问令牌，接口调用凭证，有效期 7 天
expires_at	access_token 的过期时间
refresh_token	用于刷新 access_token，有效期 60 天
open_id	授权用户唯一标识
server_time	服务器时间

6.3令牌续约

请求URL:

http://{api-gateway-host}/oauth/refresh_token

请求方式：

POST

请求参数：

{
    "access_key_id":"1d1fbd2d-8d12-4c89-9979-7418fb41b362",
    "refresh_token":"28f705cd-ba7e-467b-a596-507fcd452eeb",
    "grant_type":"refresh_token"
}

参数名	是否必须	类型	说明
access_key_id	是	string	应用唯一标识,应用注册时由开放平台分配
refresh_token	是	string	填写通过 access_token 获取到的 refresh_token 参数
grant_type	是	string	固定填 refresh_token 这个字符串

返回参数：

参数	含义
access_token	访问令牌，接口调用凭证，有效期 7 天
expires_at	access_token 的过期时间
refresh_token	用于刷新 access_token，有效期 60 天
open_id	授权用户唯一标识
server_time	服务器时间
### 6.4 获取用户公开信息

请求URL:

http://{api-gateway-host}/base/get_user_info

请求方式：

POST

请求参数：

{
    "open_id":"66d37f73-be4b-4225-a1e5-aea24c4035ab",
    "access_token":"28f705cd-ba7e-467b-a596-507fcd452eeb"
}

参数名	是否必须	类型	说明
open_id	是	string	授权用户唯一标识
access_token	是	string	访问令牌，接口调用凭证

返回参数：

参数	含义
open_id	开放平台帐号中心颁发给应用的授权用户的唯一标识，用来标记一个具体的用户
nick_name	昵称
avatar_url	头像
gender	性别 1：男，2：女，0：未知
### 6.5 获取ticket页面
#### 请求URL:

http://{unified_domain}/openplatform/ticket?redirect_url={redirect_url}&mac={mac}

请求方式：

请求参数：

参数名	是否必须	类型	说明
__mac	是	string	ND内部认证协议
redirect_url	是	string	第三方应用的完整http 地址
#### 返回参数：
- 授权成功开放平台帐号中心会返回302 重定向到应用提供的{redirect_url}页面并且带上ticket参数
{redirect_uri}?ticket={ticket}
####示例
- http://new.hbeducloud.com/openplatform/ticket?redirect_url=http://阳光评价/course/&__mac={__mac}

http 302 跳转至阳光评价应用并携带真实ticket信息
http://阳光评价/course/?ticket={real-ticket}

7. 接入地址
{api-gateway-host}
获取方式：

{unified_domain}
统一域名，即开放平台前台页面的域名
如：
湖北网教通：http://new.hbeducloud.com
获取方式：

8. 授权范围的说明(scope)

开放平台帐号中心可提供的授权范围分为scope_base（获取你的公开信息）与scope_userinfo（获取你的详细信息），其中scope_base为默认授权范围

属性	属性2	scope	备注
昵称	-	scope_base
头像	-	scope_base
性别	-	scope_base
姓名	-	scope_userinfo
身份类型	-	scope_userinfo	如老师，学生等，真实反映用户在客观组织中承担的身份，并非指用户在软件系统(如UC，RBAC，DAC)里所承担的角色;即用户身份类型不同于UC的组织管理员，机构管理员也不同于RBAC或DAC中定义的角色
组织	统一社会信用代码	scope_userinfo
组织	组织名称	scope_userinfo
组织	所在区域（省市区县）	scope_userinfo
组织	组织类型（学校、企业、主管机构）	scope_userinfo
所在节点路径	节点名称	scope_userinfo
所在节点路径	节点类型（如班级，年级）	scope_userinfo
所在节点路径	节点路径（格式如：父节点名称/祖先节点名称/…/根组织名称）	scope_userinfo	.
# 9.sdp-app-id查看位置：开放平台-开发文档-接口调用，如图：

作者：wangtc 创建时间：2023-10-08 10:41
最后编辑：hcx 更新时间：2023-11-21 03:10

【授权】第三方登录（oauth）接入指南

1. 概述

2. 术语说明

4. 应用集成 帐号登录

4.1 集成总体时序

5. 应用集成 智慧教育云平台

5.1 集成总体时序

6. 开放平台帐号中心 接口定义

默认约定

6.1 获取授权码页面

请求URL:

请求方式：

请求参数：

关于scope

6.2 获取访问令牌

请求URL:

请求方式：

请求参数：

请求示例[ticket方式，code类似]（body）

返回参数：

6.3令牌续约

请求URL:

请求方式：

请求参数：

返回参数：

请求URL:

请求方式：

请求参数：

返回参数：

请求方式：

请求参数：

7. 接入地址

{api-gateway-host}

{unified_domain}

8. 授权范围的说明(scope)

4. 应用集成帐号登录

5. 应用集成智慧教育云平台

6. 开放平台帐号中心接口定义