极速模式

一、客户端开发文档介绍

欢迎您，TiUP开发者，我们很期待你成为TiUP开放平台的开发者。

客户端开发是TiUP为连接校园办公打造的网络入口，通过该入口您可以轻松通过一个网址链接到TiUP校园平台。

此文档很适合于:

1. 企业的IT部，了解TiUP如何连接你所在企业的办公；
2. 服务提供商（ISV），了解TiUP如果链接校园与众多服务平台。

1.1 功能简介

通过协议接口，学校用户可以实现：

1. 使用TiUP账户登录 可以使用Oauth协议，使用TiUP登录到任何应用，做到多应用的单点登录和登出。
2. 数据共享和同步 提供学校多系统之间的数据安全共享解决方案。

1.2 安全机制

1. 在目前最流行的OAuth 2.0 标准协议上进行多维安全改进。
2. 管理员可随时启用／关闭指定功能或接口。

二、接入流程

接入TiUP开放接口的全流程图如下：

通过这个接入服务器，在学校第三方应用中，无需重复输入用户名和密码，可以通过身份认证获取当前使用学校的用户身份及相关信息，这包含申请管理端，Oauth验证授权，调用API三个步骤，其中

Oauth验证具体流程为：

1. 获取 Authorization Code (授权码)，获取CODE的方式是调用2.2.1.1 所示的地址。
2. 通过返回的 Authorization Code 换取用户Access Token（密钥）
3. 通过用户Access Token获取用户信息。

通过 Authorization Code获取用户身份会有一定的时间开销。对于频繁获取用户身份的场景，建议采用如下方案：

1. 用户跳转到第三方应用页面时，第三方应用校验是否有代表用户身份的cookie，此cookie由第三方应用生成。
2. 如果没有获取到cookie，调用授权流程，获取用户身份后，由企业生成代表用户身份的cookie
3. 根据cookie获取用户身份，进入相应的页面。

2.1 申请管理端

目前管理端申请功能只限内部使用，开发者可联系客服人员获取管理端，如果是针对用户数据授权，例如登录接入，访问用户主页数据等，必须提供以下内容：

1. redirect_uri （必须） 一个用于接收用户授权码的url地址，例如：http://www.exmaple.com/appauth, 用户授权后，会将授权码，返回到该地址。

2. scope （默认为：userinfo） 确定该管理端系统所需的用户数据和用途，例如：获取uid, 姓名，性别，邮箱，学工号，部门等。

申请成功后，用户将获得：

1. Client Id 管理端唯一识别码。
2. Client Secret 管理端密码，为了您的用户安全，你可以随时重置此密码。

备注：根据系统版本的不同，在某些版本中，Client Id 叫做 ApiKey， Client Secret 叫做SecretKey，此文档将以Client Id和Client Secret为准。

2.2 Oauth 验证授权

2.2.1 用户授权

通过用户登录身份进行授权，授权流程图如下：

其中第1步和第4步需要接口实现，第2步和第3步是用户浏览器操作步骤，第1步和第4步的接口如下：

2.2.1.1 客户端调用获取 Authorization Code 的API

系统引导用户从浏览器端链接或重定向到以下接口，接口和参数如下。

• 接口地址: http://accounts.cug.edu.cn/oauth2/authorize

• 返回格式：JSON

• 请求方式：GET

• 请求参数:

  参数	类型	必须	描述
  client_id	text	是	申请的 client id
  response_type	text	是	固定为：code
  scope	text	是	申请token权限，一般填写：userinfo，具体参考对应的API文档
  redirect_uri	text	是	成功授权后的回调地址，必须和申请客户端时的地址一致，用于接收用户授权码
  state	text	是	client端的状态码。用于第三方应用防止CSRF攻击，成功授权后回调时会原样返回。
  theme	text	是	此处固定为schools
  school_code	text	是	此处固定为cug

• 返回结果：HTTP 状态 302，并携带Authorizaion Code跳转到回调地址。

• 示例：例如浏览器中打开以下URL

http://accounts.cug.edu.cn/oauth2/authorize?client_id=<client_id>&response_type=code&scope=userinfo&redirect_uri=http://www.exmaple.com/appauth&state=somestate&theme=schools&school_code=cug

• • 如果用户授权成功后会将Authorization Code返回

http://www.exmaple.com/appauth?code=7afb1c55adb79d657cb47a27&state=somestate

回调返回值参数说明：

• • 如果调用错误或用户拒绝授权后返回到

http://www.exmaple.com/appauth?error=access_denied&error_description=&state=somestate

回调返回值参数说明：

2.2.1.2 服务器端获取 Access Token

• 接口地址: http://accounts.cug.edu.cn/oauth2/token

• 请求方法：POST

• 请求header:

  键	类型	值
  Authorization	text	Basic+ 空格 + (client_id + : + client_secret 组成字符串的base64编码), 详见：Basic Authorization
  Content-Type	text	application/x-www-form-urlencoded

  代码示例：

request.setHeader("Authorization", "Basic " + Base64.encode(clientId + ":" + clientSecret));
request.setHeader("Content-Type", "application/x-www-form-urlencoded");

• 请求参数

  参数	类型	必须	Description
  grant_type	text	是	固定为authorization_code
  code	text	否	上一步获取的Authorization Code

• 返回

• • 返回成功，HTTP状态码为200

  返回字段名	类型	描述
  access_token	string	获取的用户验证TOKEN
  expires_in	int	过期时间（单位：秒）
  scope	string	access_token 作用域
  token_type	string	token类型，常为：Bearer

  示例JSON

    {
        "access_token": "GHUSH-4qIXPScxa_OY0CbPS31W1OM24L",
        "scope":"login",
        "expires_in": 3600,
        "token_type": "Bearer"
    }

• • 错误 （HTTP状态码为 400，401 ...）

  返回字段名	类型	描述
  error	string	错误类型
  error_description	string	错误描述

  示例JSON

    {
      "error": "bad_request",
      "error_description": "error_description"
    }

• 请求示例

curl -v -u <client_id>:<client_serent> \
   -d "grant_type=authorization_code" \
   -d "code=<authorization_code>" \
 'http://accounts.cug.edu.cn/oauth2/token'

2.3 调用API

通过将获取的access_token添加到HTTP请求的Header中, 调用API，实现多种操作，本章将以获取用户基本信息为例，在这之前，请用用户授权方式获取access token。

2.3.1 获取用户基本信息

• 接口地址: http://api-accounts.cug.edu.cn/oauth2/v1/userinfo
• 请求方法：GET
• 返回格式：JSON
• 请求header:

• 键	类型	值
  Authorization	text	Bearer+ 空格 + 获取的access_token
  Content-Type	text	application/x-www-form-urlencoded

  代码示例：

  request.setHeader("Authorization", "Bearer " + accessToken);
  request.setHeader("Content-Type", "application/x-www-form-urlencoded");
  

• 返回
• • 成功，http状态码为200

  返回的参数名	返回类型	描述
  uid	string	用户唯一身份标识符
  name	string	姓名
  email	string	邮箱
  phone	string	电话号码
  sex	string	性别：可能出现的值为 male，female，other 三种
  avatarurl	string	头像
  birthday	date	生日
  createdat	date	创建日期
  linkedaccounts	JSON Array	关联到学号信息，例如包含：{"host": "ruc","username": "0000"}的账户，即表示该账号拥有人民大学学号为0000的账户权限

  JSON示例：

      {
        "uid": "573061OY0CbPS31W1OM24L"
        "name": "孙小明",
        "email": "test@tiup.cn",
        "phone": "+86 15650762921",
        "sex": "male",
        "avatarurl": "https://static.tiup.us/avatar.jpg",
        "birthday": "2014-01-01T00:00:00+08:00",
        "createdat": "2014-01-01T00:00:00+08:00",
        "linkedaccounts":[
          {
          "host": "cug",
          "username": "0000"
          }
        ]
      }

备注：根据管理端权限与安全策略不同，获取到到字段可能有所删减，如果没有出现您需要到返回字段，请联系客服进行授权申请。

• • 错误，http状态码味400，401等

    {
      "error": "bad_request",
      "error_description": "error_description"
    }

• 示例

curl -i -X GET \
   -H "Authorization:Bearer <access_token>" \
 'http://api-accounts.cug.edu.cn/oauth2/v1/userinfo'

三、使用TiUP账户登录

可以通过Oauth 2.0 实现用户登录。接入流程图如下所示：

3.1 获取用户授权

参考TiUP Oauth 2.0 开放协议第二部分，获取用户基本信息，实现账户到登录与同步，接入流程如下。

3.2 关联到本地账户

使用TiUP sso sdk或参考第二章内容，获取到用户信息后，关联UID字段或学工号到本地系统用户，如果本地系统用户不存在，可根据您的应用策略，利用用户信息生成本地用户。