第三方登录接口

OAuth2.0登录
接口使用条款
接入准备工作
登录流程
退出
软件环境
联系方式

NADC用户通行证第三方登录接口文档

(2024年12月27日更新)

NADC用户通行证基于OAuth2.0标准，为NADC平台内部各子系统以及第三方合作网站或应用提供单点登录以及用户信息共享等支持。

OAuth（开放授权）是一个开放标准，允许用户授权第三方网站访问存储在另外服务提供者上的信息，而不需要将用户名和密码提供给第三方网站或分享他们数据的所有内容。OAuth2.0是OAuth协议的延续版本，但并不向前兼容OAuth1.0。
NADC通行证OAuth2.0登录：对于用户相关的开放接口（例如获取用户信息等），为了保护用户数据的安全和隐私，第三方网站或应用访问用户数据前都需要显式的向用户征求授权。NADC通行证采用OAuth2.0标准协议来进行用户身份验证和获取用户授权，认证流程简单，安全性高。

接口使用条款

NADC用户是用户相关接口资源的拥有者，需要尊重和保护用户的权益；
未经用户允许，不允许将用户的个人信息用于个人、组织或者任何机构的商业行为，研究行为也必须征求用户的同意；
禁止滥用接口，请求频率过快将导致请求终止。

接入准备工作

申请应用ID和应用密钥

联系NADC管理员(support(at)china-vo.org)，申请开发者身份。
登录通行证，通过右上角[工作台]进入[我的应用]界面，可以新增或编辑本人申请的所有应用信息。
在[我的应用]页面，点击[申请新的应用]按钮，根据提示填入相关信息(应用名称、主页、回调地址等)，提交后等待管理员审批。
管理员审批后，系统一次性分配应用ID和密钥，也可以修改应用，但每次修改都需要再次审批。

从安全角度考虑，目前NADC通行证仅支持Authorization Code模式，适用于需要从web server访问的应用。如需其他授权模式支持或对接微信小程序等，请联系管理员(support(at)china-vo.org)。

获取Authorization Code
- 请求地址: https://oauth.china-vo.org/oauth/authorize
- 请求方法：GET
- 请求参数:
  - client_id : 在NADC通行证上注册的第三方应用ID。
  - redirect_uri : 在用户授权完毕后将要跳转到的网页链接地址(回调地址，必须为应用主页的下级地址)。
  - response_type : code(固定值)
  - scope : profile(固定值)
  - state : 随机字符串(可选)，可用于后期验证。
- 完整示例:
```
  GET https://oauth.china-vo.org/oauth/authorize?response_type=code&client_id=${client_id}&redirect_uri=${redirect_uri}&scope=profile&state=xyz123
```
- 返回结果：
```
  回调地址?code=xxxxxx&state=xyz123
```
通过code获取access_token
- 请求地址: https://oauth.china-vo.org/oauth/token
- 请求方法：POST
- 请求参数:
  - code : 从回调地址中获取(参见上一节的返回结果)。
  - client_id : 在通行证上注册的第三方应用ID。
  - client_secret : 应用ID对应的密钥。
  - redirect_uri : 在用户授权完毕之后将要跳转到的网页链接地址。
  - grant_type : authorization_code(固定值)。
  - scope : profile(固定值)
- 完整示例:
```
POST https://oauth.china-vo.org/oauth/token
                    grant_type=authorization_code&
                    code=${code}&
                    redirect_uri=${redirect_uri}&
                    client_id=${client_id}&
                    client_secret=${client_secret}&
                    scope=profile
                
```
- 返回结果示例：
```
{ "access_token":"RsT5OjbzRn430zqMLgV3Ia", "expires_in":3600 }
```
根据access_token获得对应用户信息(profile)
- 请求地址: https://oauth.china-vo.org/api/profile
- 请求方法：GET
- 请求参数: 参数在请求Header里面，格式为
```
Authorization : Bearer ${access_token}
```
- 完整示例(以curl为例):
```
 curl -H "Authorization: Bearer RsT5OjbzRn430zqMLgV3Ia" https://oauth.china-vo.org/api/profile
```
- 特别注意: Bearer与access_token之间必须有一个英文空格。
- 返回json格式:
```
{ "code": 200, "message": "success", "data": { "user": { ...} } }
```
  其中user包含如下信息：
  - umtId : 用户ID(唯一标识)
  - unionId : 微信unionId(可空)，NADC平台内用户微信的唯一标识，主要用于微信登录、微信小程序接入。
  - ldap_id : 短用户名(可空)，ldap用户ID(唯一标识)
  - name : 用户名称
  - register_date : 注册日期
  - confirmed : 用户邮箱是否验证
  - locked : 锁定标识
  - email : 用户电子邮箱
  - phone : 用户手机号码
  - avatar_url : 用户头像url
  umtId是NADC平台内用户身份的唯一标识，第三方应用可将此ID进行存储便于用户下次登录时辨识其身份，或将其与用户在本应用内的原有账号进行绑定。

退出

当用户退出后第三方应用需要向通行证也发送一份登出请求，用以清理通行证对当前用户的session记录信息和token记录信息。

请求地址 : https://oauth.china-vo.org/oauth/logout
请求方法：GET
请求参数 :
- WebServerURL(可选) : 成功登出之后重定向的url(应为该应用域名下的地址)，默认为通行证主页。

软件环境

理论上，OAuth2.0标准不限定编程语言，NADC通行证对第三方应用的开发语言无强制要求。
OAuth开发包的推荐列表：

Python : authlib
Java : scribejava

联系方式

support(at)china-vo.org

NADC用户通行证第三方登录接口文档

NADC通行证OAuth2.0登录

接口使用条款

接入准备工作

登录流程

退出

软件环境

联系方式