OAuth2.0

2023-03-22 10:15 星期三

协议概述

OAuth（开放授权）是一个开放标准，允许用户授权第三方移动应用访问他们存储在另外的服务提供者上的信息，而不需要将用户名和密码提供给第三方移动应用或分享他们数据的所有内容，OAuth 2.0 是 OAuth 协议的延续版本，但不向后兼容 OAuth 1.0 即完全废止了 OAuth1.0。

名词解释

  • Third-party application：第三方应用程序，又称”客户端”（client）。
  • HTTP service：HTTP服务提供商，简称”服务提供商”。
  • Resource Owner：资源所有者，又称”用户”（user）。
  • User Agent：用户代理，指浏览器。
  • Authorization server：认证服务器，即服务提供商专门用来处理认证的服务器。
  • Resource server：资源服务器，即服务提供商存放用户生成的资源的服务器。它与认证服务器，可以是同一台服务器，也可以是不同的服务器。

登录流程

  1. 用户打开客户端以后，客户端要求用户给予授权。
  2. 用户同意给予客户端授权。
  3. 客户端使用上一步获得的授权，向认证服务器申请令牌。
  4. 认证服务器对客户端进行认证以后，确认无误，同意发放令牌。
  5. 客户端使用令牌，向资源服务器申请获取资源。
  6. 资源服务器确认令牌无误，同意向客户端开放资源。

开发详情

开发详情以授权码模式为例。

步骤1：

  • 获取用户授权，如果用户未登录系统，则要求用户进行身份认证（跳转至授权服务器进行认证），应用发起重定向至授权服务器的以下地址。接口支持 PKCE 模式，如需进行 PKCE 模式的校验，可传入相应的参数。
HTTP Method：GET
https://demo.cloudentify.com/api/oauth/authorize

请求参数：

  • client_id：必填，客户端 ID，从管理平台-应用管理-企业应用列表的App ID处获取；
  • response_type：必填，固定值“code”；
  • redirect_uri：必填，授权成功后的重定向地址；
  • state：非必填，应用系统提供的一个随机字符串，服务器会原样重定向给应用系统，防止 CSRF、XSRF；
  • scope：必填，固定值‘user’；
  • code_challenge_method：非必填，PKCE 模式的必要参数，即 code_challenge 值的计算方法，目前仅支持 SHA256；
  • code_challenge：非必填，PKCE 模式的必要参数，计算方式：code_challenge = code_challenge_method(code_verifier)。code_verifier 为校验码原文，应用系统需要自行保存code_verifier，并在获取授权令牌的请求中带上，用作验证，code_challenge_method使用SHA256。

请求示例：

https://demo.cloudentify.com/api/oauth/authorize?client_id=EFTDBB&response_type=code&redirect_uri=http%3A%2F%2Fwww.test.com&code_challenge_method=S256&code_challenge=FWOeBX6Qw_krhUE2M0lOIH3jcxaZzfs5J4jtai5hOX4&state=123456
  • 授权服务器进行认证后，将通过redirect_uri传入的重定向地址，向应用下发授权码。

HTTP Method：GET
http://www.test.com?code=b9eb0dc233&state=123456

步骤2：

  • 应用获取到授权码后，使用授权码换取访问令牌。
HTTP Method：POST
https://demo.cloudentify.com/api/oauth/token

请求参数：

  • Authorization：必填，存放Header中， 接口鉴权值，Basic base64encode(client_id:client_secret)；注：client_id、client_secret请在云信管理平台应用管理处获取（创建应用时生成）；
  • grant_type：必填，固定值“authorization_code”；
  • redirect_uri：必填，授权成功后的重定向地址。如果“oauth/authorize”请求带有 redirect_uri 参数，则本步骤请求必须上送 redirect_uri 参数；
  • code：必填，授权码；
  • code_verifier：非必填，PKCE 模式必要参数，code_verifier 校验码原文。

请求示例：

Authorization: 'Basic MTIzNDU2OjEyMzQ1Ng=='
https://demo.cloudentify.com/api/oauth/token?grant_type=authorization_code&redirect_
uri=http%3A%2F%2Fwww.baidu.com&code=123456&code_verifier=2D9RWc5iTdtejle7GTMzQ9Mg15InNmqk3GZL-Hg5Iz0&scope=openid

返回参数：

  • access_token：access_token令牌；
  • expires_in：access_token有效时间；
  • token_type：固定值“bearer”；
  • refresh_token：刷新令牌。

返回示例：

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

步骤3：

  • 访问令牌过期后，可使用刷新令牌置换新的访问令牌。
HTTP Method：POST
https://demo.cloudentify.com/api/oauth/token

请求参数：

  • Authorization：必填，存放Header中， 接口鉴权值，Basic base64encode(< client_id >:(client_secret))；
  • grant_type：必填，固定值“refresh_token”；
  • refresh_token：必填，refresh_token。

请求示例：

Authorization: 'Basic MTIzNDU2OjEyMzQ1Ng=='
https://demo.cloudentify.com/api/oauth/token?grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

返回参数：

  • access_token：access_token令牌；
  • expires_in：access_token有效时间；
  • token_type：固定值“bearer”；
  • refresh_token：刷新令牌。

返回示例：

{
     "access_token":"2YotnFZFEjr1zCsicMWpAA",
     "token_type":"bearer",
     "expires_in":3600,
     "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

步骤4：

  • 应用可通过访问令牌获取用户信息。
HTTP Method：POST
https://demo.cloudentify.com/api/oauth/oidc/me?access_token=f148b9b4-2f02-42dd-8a59-4ca92a12c48b

返回示例：

{
    "username": "steven",
    "email": "steven@example.com",
    "phonesn": "1xxxxxxxxxx",
    "name": null,
    "nickname": null,
    "country": null,
    "province": null,
    "city": null,
    "address": null,
    "gender": "unknown",
    "authorization": {
		"roleList": [
			{
				"roleCode": "OrderAdmin",
				"descp": "订单管理员"
			},
            …
		],
		"ruleList": [
			{
				"accessmode": 0,
				"accessmodeStr": "允许",
				"resourceName": "订单管理",
				"resourceCode": "1000",
				"parentResourceCode": ""
			},
            …
		]
}

步骤5：

  • 检查Access Token是否合法。
Authorization: 'Basic MTIzNDU2OjEyMzQ1Ng=='
https://demo.cloudentify.com/api/oauth/check_token?token=f148b9b4-2f02-42dd-8a59-4ca92a12c48b

返回示例：

{
    "active": true,
    "user_name": "steven",
    "scope": [
        "user"
     ],
    "exp": 1646808647,
    "authorities": [],
    "client_id": "EFTDBB09882221123333"
}

登录态注销（退出登录）：

  • 业务系统主动调用飞天云信注销Access Token。
HTTP Method：GET
Authorization: 'Bearer f148b9b4-2f02-42dd-8a59-4ca92a12c48b'
https://demo.cloudentify.com/api/oauth/revokeToken

注：调用接口时，将access_token访问令牌写到请求头Authorization中。

  • 业务系统被动等待飞天云信调用注销用户登录状态。

业务系统提供登出回调URL，接口描述如下：

HTTP Method：POST
Header Content-Type：application/x-www-form-urlencoded

接口参数：

  1. id：UUID；
  2. principal：登录业务系统的用户名；
  3. request：固定值“logoutRequest”；
  4. issueInstant：请求时间，格式为yyyy-MM-dd’T’HH:mm:ss.SSS’Z；
  5. online_ticket：OAuth2协议的access_token。