本文介绍Web应用如何通过OAuth 2.0扮演登录用户访问阿里云API。
前提条件
基本流程
用户通过浏览器登录Web应用。
Web应用重定向到阿里云OAuth 2.0服务并将URL返回给浏览器。
说明如果用户还未登录,则会进一步重定向到阿里云登录服务。
用户通过浏览器登录阿里云OAuth 2.0服务并申请授权码。
阿里云OAuth 2.0服务重定向到Web应用并返回授权码给浏览器。
浏览器通过Web应用使用授权码向阿里云OAuth 2.0服务申请代表用户身份的令牌。
阿里云OAuth 2.0服务向Web应用返回访问令牌(access_token)。
Web应用通过获取的访问令牌(access_token)向阿里云发起访问API的请求。
说明由于访问令牌(access_token)可以代表用户身份,因此应用可以访问当前用户的资源。
获取访问令牌
Web应用通过浏览器将用户重定向到阿里云OAuth 2.0服务从而获取授权码。
授权码的请求地址:
https://signin.aliyun.com/oauth2/v1/auth
。表 1. 请求参数 参数名称
是否必选
描述
client_id
是
应用ID。
redirect_uri
是
创建应用时填写的重定向URL之一。
response_type
是
返回类型。根据OAuth 2.0协议,目前支持设置此参数的取值为code。
scope
否
空格分隔的OAuth范围列表。如不指定此参数取值,则默认为应用的全部OAuth范围。
access_type
否
应用的访问类型。取值分为两种类型:
online:应用不需要离线刷新访问令牌。
offline:针对离线访问类型的请求,会发放刷新令牌,应用可以根据需求持续刷新访问令牌。
默认取值为online。
state
否
应用通过state 参数实现多种目的,例如:状态保持、作为nonce使用从而减少CSRF威胁等。state如果设置为任意字符串,阿里云OAuth2.0服务会将请求中的state参数及取值原样放到返回参数中以供后续使用。
prompt
否
该参数用于指定服务器是否需要提示用户进行授权操作。
如果指定,会强制要求用户进行授权,即使该阿里云账号已经做过授权,也需要重新授权。如果不指定,则只在该阿里云账号第一次使用该应用时要求授权。
取值:
admin_consent
,表示服务端会在向客户端返回信息之前展示授权页面。请求示例
https://signin.aliyun.com/oauth2/v1/auth? client_id=123****& redirect_uri=https://example.com/authcallback/& response_type=code& scope=openid /acs/ccc& access_type=offline& state=123456****
返回示例
GET HTTP/1.1 302 Found Location: https://example.com/authcallback/?code=ABAFDGDFXYZW888&state=123456****
Web应用使用授权码向阿里云OAuth 2.0服务申请代表用户身份的令牌。
换取访问令牌的请求地址:
https://oauth.aliyun.com/v1/token
。表 2. 请求参数 参数名称
是否必选
描述
code
是
初始请求中获取的授权码。
client_id
是
应用ID。
redirect_uri
是
初始请求中设置的参数。
grant_type
是
根据OAuth 2.0协议, 取值为authorization_code。
client_secret
否
应用密钥,用作换取访问令牌时鉴定应用身份的密码。
请求示例
POST /v1/token HTTP/1.1 Host: oauth.aliyun.com Content-Type: application/x-www-form-urlencoded code=ABAFDGDFXYZW888& client_id=123****& client_secret=`your_client_secret`& redirect_uri=https://example.com/authcallback/& grant_type=authorization_code
表 3. 返回参数 参数名称
描述
access_token
访问令牌。
访问令牌可以代表用户身份,应用使用此访问令牌来访问阿里云API。应用不需要理解访问令牌的含义,直接使用即可。
expires_in
访问令牌的剩余有效时间,单位为秒。
token_type
访问令牌的类型。取值为Bearer。
id_token
身份令牌。
身份令牌为OAuth签名的JWT(JSON Web Token)。如果初始请求的scope参数包含了openid,则返回身份令牌。
refresh_token
刷新令牌。
如果初始请求时应用的访问类型为offline,则返回刷新令牌。
scope
获取的授权码的实际授权范围。
如果应用需要的授权范围不止
openid
,那么您需要校验获取的scope是否符合预期。如果您安装的应用未授权指定的scope,请您重新授权。重新授权的方法:通过
https://signin.aliyun.com/oauth2/v1/auth
请求授权码时,设置参数prompt=admin_consent
。返回示例
{ "access_token": "eyJraWQiOiJrMTIzNCIsImVu****", "token_type": "Bearer", "expires_in": "3600", "refresh_token": "Ccx63VVeTn2dxV7ovXXfLtAqLLERA****", "id_token": "eyJhbGciOiJIUzI1****", "scope": "openid /acs/ccc" }
获取新的访问令牌
换取访问令牌的请求地址:https://oauth.aliyun.com/v1/token
。
参数名称 | 是否必选 | 描述 |
refresh_token | 是 | 用授权码换取访问令牌时获得的刷新令牌。 |
client_id | 是 | 应用ID。 |
grant_type | 是 | 根据OAuth 2.0协议, 取值为refresh_token。 |
client_secret | 否 | 应用密钥,用作换取访问令牌时鉴定应用身份的密码。 |
请求示例
POST /v1/token HTTP/1.1
Host: oauth.aliyun.com
Content-Type: application/x-www-form-urlencoded
refresh_token=Ccx63VVeTn2dxV7ovXXfLtAqLLERAH1Bc&
client_id=123****&
client_secret=`your_client_secret`&
grant_type=refresh_token
参数名称 | 描述 |
access_token | 新的访问令牌。应用可以使用新的访问令牌来访问阿里云API。 |
expires_in | 访问令牌的剩余有效时间,单位为秒。 |
token_type | 访问令牌的类型。取值为Bearer。 |
返回示例
{
"access_token": "eyJraWQiOiJrMTIzNCIsImVu****",
"token_type": "Bearer",
"expires_in": "3600"
}
撤销刷新令牌
Web应用获取了刷新令牌后,在用户退出登录应用或用户将自己的账号从应用中移除时,必须撤销刷新令牌。
撤销刷新令牌的请求地址:https://oauth.aliyun.com/v1/revoke
。
参数名称 | 是否必选 | 描述 |
token | 是 | 需要撤销的刷新令牌。 |
client_id | 是 | 应用ID。 |
client_secret | 否 | 应用密钥。 |