上海交通大学开发者平台

# 开放授权

# 概述

  • 本文件所述开放授权协议指上海交通大学的OAuth认证服务，遵守RFC6749（OAuth 2.0） (opens new window)。
  • OAuth协议为用户资源的授权提供了一个安全的、开放而又简易的标准，为桌面、手机或web应用提供了一种简单的、标准的方式去访问需要用户授权的API服务。
  • 本校建立了基于OAuth2.0协议的开放平台体系，以REST APIs方式提供各类基础服务和数据服务，第三方应用可申请使用开放平台资源。开放API在OAuth的保护下提供服务，第三方应用在访问任何一个本校开放应用程序编程接口（API）时，应先从OAuth服务端获取相应的访问令牌（Access Token）。
  • 上海交通大学OAuth遵循国际标准，可以使用各种公开的开发包，请参考http://oauth.net/2/ (opens new window) 。

# OAuth2地址

# API授权框架

# 概述

上海交通大学网络信息中心提供各类APIs，采用基于OAuth2.0授权体系的安全策略。 本校能支持如下三种API授权方式：

  • 授权码（Authorization Code）模式
  • 客户端凭据授予（Client Credentials Grant）模式
  • 资源拥有者密码凭据许可（Resource Owner Password Credentials）模式

# 授权方式

# 授权码（Authorization Code）模式

该授权过程需要资源所有者登录进行授权，是APIs的scope中最常用授权方式。主要授权过程和示例参见使用授权码（Authorization Code）过程的 OIDC 认证模式

# 客户端凭据授予（Client Credentials Grant）模式

采用客户端凭据授予方式，即应用id、密钥方式获取访问令牌（Access Token），通过它所获取的访问令牌应仅可访问与用户无关的开放API。如果对应的API支持，也可以任意指定用户以确定要访问的资源，但此类授权方式下的API一般不予申请。

示例 客户端凭据授予适用的一个应用场景

获取App首页最新闻列表（如微信公众平台授权）。由于这个数据与用户无关，所以不涉及用户登录与授权,但又希望任何人都可以调用这个WebAPI。
客户端凭据授予的基本流程见RFC6749 Figure 6 (opens new window)，主要授权过程是：

  • a）客户端向认证服务器提供客户身份标识号（client_id）和客户密钥（client_secret）请求访问令牌；
  • b）认证服务器对客户端进行验证，如果访问合法，则发放访问令牌，客户端根据此访问令牌获取资源。

示例 以客户端凭据方式请求访问令牌
POST /oauth2/token HTTP/1.1
Host: jaccount.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=write_apps&client_id=s6BhdRkqt3&client_secret=sexxsdded
1
2
3
4
5

参数解释

  • grant_type：授权模式，应为“client_credentials”；
  • scope：请求令牌的权限范围，可选填。默认获取应用所拥有的所有客户端模式授权权限；
  • client_id：客户身份标识号。宜使用基本认证方式通过 Authorization 头传递；
  • client_secret：客户密钥。宜使用基本认证方式通过 Authorization 头传递。

示例 授权服务器返回访问令牌
{
    "expires_in": 1800,
    "token_type": "Bearer",
    "refresh_token": "a34ec63782a223dcab7aff689e6589f7",
    "access_token": "bb96645b969a9b2632157a2058f35a37"
}
1
2
3
4
5
6

参数解释

  • expires_in：请求令牌有效期，单位秒；
  • token_type：令牌类型；
  • access_token：请求令牌；
  • refresh_token：刷新令牌，当请求令牌过期后可以使用刷新令牌刷新请求令牌有效期。

# 资源拥有者密码凭据许可（Resource Owner Password Credentials）

采用资源拥有者密码凭据许可方式，用户须向客户端提供自己的用户名和密码。客户端使用这些信息，向“服务提供者”索要授权。在这种模式中，用户应向客户端提供自己的密码。 资源拥有者密码凭据许可方式的基本流程见RFC6749 Figure 5 (opens new window)，主要授权过程是：
a) 资源所有者向应用客户端提供其用户名和密码。基于安全考虑，应用方还需要用户提供一个安全令牌作为用户的第三个输入。
b) 交换访问令牌。客户端请求从授权服务器的令牌端点获取一个访问令牌（包括从资源所有者收到的凭据）。在发出请求时，客户端与授权服务器进行身份验证。
c) 授权服务器对客户端进行身份验证并验证资源所有者凭据，如果有效，则发出访问令牌和更新令牌（refresh token）。

备注

  • access token是有过期时间的，到了过期时间这个 access token 就失效，需要更新。
  • access stoken关联一定的用户权限，如果用户授权更改了，access token需要被更新以关联新的权限。
  • 为什么要专门用一个refresh token去更新access token 呢？如果没有refresh token，也可以刷新access token，但每次刷新都要用户输入登录用户名与密码，客户端直接用refresh token去更新access token，无需用户进行额外的操作。

示例 以资源拥有者密码凭据许可方式请求访问令牌
POST /oauth2/token HTTP/1.1
Host: jaccount.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

grant_type=password&scope=send_notification&client_id=testclientid&client_secret=testclientsecret&username=xxxx&password=yyyy
1
2
3
4
5

参数解释：

  • grant_type：授权模式，应为“password”；
  • scope：请求令牌的权限范围，可选填。默认获取应用所拥有的所有客户端模式授权权限；
  • client_id：客户身份标识号。宜使用基本认证方式通过 Authorization 头传递；
  • client_secret：客户密钥。宜使用基本认证方式通过 Authorization 头传递；
  • username：资源拥有者 jAccount 账号名；
  • password：资源拥有者 jAccount 账号密码。

授权服务器返回访问令牌的示例同上

# 令牌刷新（Refreshing an Access Token）

支持用户使用refresh token 刷新相应的令牌（token）。

  • a）客户端向认证服务器提供refresh token 请求刷新对应token；
  • b）认证服务器对refresh token进行验证，如果有匹配令牌（token），则对token进行延期。
示例 刷新令牌
POST /oauth2/token HTTP/1.1
Host: jaccount.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&client_id=s6BhdRkqt3&client_secret=sexxsdded
1
2
3
4
5

参数解释：

  • grant_type：授权模式，应为“refresh_token”；
  • refresh_token：令牌（token）获取时颁发的refresh token
  • client_id：客户身份标识号。宜使用基本认证方式通过 Authorization 头传递；
  • client_secret：客户密钥。宜使用基本认证方式通过 Authorization 头传递。

# 授权范围

应用系统API使用权限申请的控制粒度是scope+授权方式，因此具体使用哪种API授权方式，一要应依据申请的scope、二要获得批准。
能提供的所有APIs授权范围（scope）参见以下授权范围列表。
获取多个scope的Access Token方法有二：

  • scope值是scope字符名称空格分隔
  • scope值相加。
示例 多scope请求

如需要获取basic+essential， 则scope值为：scope=basic essential 或 scope=3。

# 授权范围列表

Scope有两种标识方式：scope码，scope值。

Scope代码 值 描述 支持的授权方式
basic 1<<0 读取用户标识(包含系统 id 和 jAccount 账号名),姓名 A，C
essential 1<<1 读取用户的基本标识和姓名，以及账号绑定的身份的信息（包括身份 id，身份类型和身份所属部门院系） A，C
profile 1<<2 读取用户更详细的信息，包括用户基本标识、姓名、账号信息，手机号码、常用邮箱地址等 A，C
unicode 1<<3 开通、获取思源码，或校验思源码 A，C
tasks 1<<5 读取可办、待办、在办、已办列表；读取或统计可管理的工作流、实例或任务信息 A，C
messages 1<<6 读取用户的消息 C
notifications 1<<7 读取用户的系统通知 A
privacy 1<<8 读取用户的详尽信息，并包括个人证件信息和生日信息等 A
introspect 1<<9 获取 oauth token 的详细信息。仅限 API 开发使用 C
read_apps 1<<10 获取应用信息 C
write_apps 1<<11 创建、修改应用信息 C
exchange_data 1<<12 数据交换 C
signature 1<<17 获取数字签名 A，C
manage_card 1<<20 校园卡管理，如开户 A
send_app_notification 1<<23 向用户发送交我办通知 C
send_notification 1<<25 向用户发送通知 P
read_mails 1<<26 读取用户的邮件 A
send_mail 1<<27 替用户发送邮件，或改变邮件的阅读状态 A，P
storage 1<<29 完全控制该应用的非结构化存储 C，P
modify_notification 1<<30 修改自己的通知状态 A
lessons 1<<34 获取用户的课程信息。 A
classes 1<<35 获取用户的课表信息（含课程）。 A
exams 1<<36 获取用户的考试信息 A
scores 1<<37 获取用户的考试成绩 A
students_list 1<<38 获取上课学生名单（教师） A
card_info 1<<39 读取用户一卡通的信息 A，C
card_transactions 1<<40 读取用户一卡通交易记录 A
write_card_info 1<<41 校园卡更新操作，如修改查询密码，挂失，从绑定银行卡充值等 A
income 1<<42 查询用户收入信息 A，C
create_jaccount 1<<43 创建jaccount账号 C
edit_jaccount 1<<44 修改jaccount账号 A
net_service_info 1<<45 获取指定用户个人所有网络服务信息 A
connect_wechat 1<<46 jaccount绑定微信账号 A
connect_shmec 1<<47 jaccount绑定上海市教委账号 A
print 1<<48 自助打印服务 A，C
connect_finance 1<<49 对接财务预约系统 C
student_affairs 1<<50 学生事务信息获取 C
bus 1<<51 获取校园巴士、校区间通勤班车的时刻表与实时信息 C
calendar 1<<52 同步日程信息 A，C

备注 "支持的授权方式"用单字母表示授权方式：

  • A表示 Authorization Code
  • C表示 Client Credentials Grant
  • P表示 Resource Owner Password Credentials

# 开发支持

# java支持

jar包sjtu-api.jar实现了OAuth2除Code授权模式以外其他授权模式和Profile API，Notification API等多组API的调用，供开发使用和参考下载 (opens new window)

← jAccount认证接入方法 →