# 开放授权

# 概述

  • 本文件所述开放授权协议指上海交通大学的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
1
2
3
4
5

参数解释:

  • grant_type:授权模式,应为“refresh_token”;
  • refresh_token:令牌(token)获取时颁发的refresh token

# 授权范围

应用系统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
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
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 APINotification API等多组API的调用,供开发使用和参考下载 (opens new window)