授权码授予
授权代码授予允许客户端(通常为网站)将用户代理(用户浏览器)定向至亚马逊的URI。然后,页面会请求用户授予访问其个人资料的网站权限。请求获得批准后,客户端将收到授权代码,可通过此代码换取访问令牌和刷新令牌。
客户端获得访问令牌后,就可以读取客户个人资料。有关客户体验的更多详细信息,请参阅授权授予。
如果用户拒绝请求,客户端将收到授权服务发出的错误信息。
授权请求
要请求授权,客户端(网站)必须重定向用户代理(浏览器),使用以下参数对https://www.amazon.com/ap/oa
进行安全的HTTP调用。如果使用授权标头来请求访问令牌,请注意,该授权标头应采用client_id: client: secret的Base64编码。
参数 | 描述 |
---|---|
client_id |
必需。客户标识符。当您注册您的网站以将其作为Login with Amazon的客户端时,系统会提供该参数。最大不超过100字节。 |
scope |
必需。请求的范围。必须是profile 、profile:user_id 、postal_code 或某些组合,以空格分隔(例如profile%20postal_code )。有关更多信息,请参阅客户个人资料。 |
response_type |
必需。请求的响应类型。此场景中必须为code 。 |
redirect_uri |
必需。授权服务重定向用户的HTTPS地址。 |
state |
推荐。客户端在请求和响应期间用来保持状态的不透明值。用户重定向返回客户端时,授权服务会将此值包括在内。此外,状态值还可用于阻止跨站点伪造请求。有关更多信息,请参阅跨站点伪造请求。 |
code_challenge |
推荐。通过代码交换证明密钥 (PKCE) 来确保授权代码授予安全。基于浏览器的应用必须使用代码挑战,推荐将其用于所有应用类型。有关更多信息,请参阅PKCE RFC。 |
code_challenge_method |
推荐。用于为code_challenge 参数编码code_verifier 的方法。建议为S256 。也可以设置为plain 。如果不存在其他选项,则默认为plain 。 |
例如:
https://www.amazon.com/ap/oa?client_id=foodev
&scope=profile
&response_type=code
&state=208257577ll0975l93l2l59l895857093449424
&redirect_uri=https://client.example.com/auth_popup/token
&code_challenge=Fw7s3XHRVb2m1nT7s646UrYiYLMJ54as0ZIU_injyqw
&code_challenge_method=S256
要使用适用于JavaScript的Login with Amazon SDK发出授权请求,您必须填写options
对象并调用amazon.Login.authorize
。
选项1: 服务器应用
适用于可以使用服务器端脚本的应用。此为建议集成方式。这种集成方式的令牌永远不会暴露给用户,因此更安全。访问令牌和刷新令牌都会进行返回。刷新令牌无需用户参与便可获取新的访问令牌。
options = { } ;
options.scope = 'profile';
options.response_type='code';
amazon.Login.authorize(options, function(response) {
if ( response.error ) {
alert('oauth error ' + response.error);
return;
}
<!-- 将response.code传递给您的服务器,并使用它来请求刷新和
访问令牌。 -->
});
选项2: 基于浏览器的应用
适用于无服务器支持的JavaScript应用。由于浏览器无法安全存储client_secret
,必须使用PKCE (options.pkce = true
)。访问令牌请求由用户浏览器作出,因此用户将暴露给访问令牌。从严格的安全角度来看,用户信息最好处于隐藏状态。因此将不会返回刷新令牌。访问令牌过期后,用户必须重新进行身份验证才能继续访问相应的资源。如果您的架构支持服务器端脚本,我们建议在服务器上执行代码以交换令牌(选项1)。
options = { } ;
options.scope = 'profile';
options.pkce = true; // SDK会生成`code_verifier`和`code_challenge`
amazon.Login.authorize(options, function(response) {
if ( response.error ) {
alert('oauth error ' + response.error);
return;
}
amazon.Login.retrieveToken(response.code, function(response) {
if ( response.error ) {
alert('oauth error ' + response.error);
return;
}
alert('Access Token: ' + response.access_token);
});
});
amazon.Login.authorize
的第一个参数始终为options
对象。第二个参数为处理授权响应的JavaScript函数或重定向到另一页面的URI。URI必须与调用该SDK的页面属于同一个域,且必须使用HTTPS进行指定。
例如:
options = {} ;
options.scope = 'profile';
options.response_type = 'code';
amazon.Login.authorize(options, 'https://mysite.com/redirect_here');
用户批准或拒绝请求后,授权服务器会将用户重定向到redirect_uri
。客户端将收到授权响应(如下所述)。
授权响应
客户端(网站)指导用户代理(浏览器)发出授权请求后,授权服务会将用户代理重定向到客户端指定的URI。如果用户已对访问请求进行授权,则该URI将包含code
参数(其中包含授权代码)和scope
参数(其中包含以+
分隔的用户同意范围列表)。例如:
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBezQQYbYS6WxSbIA
&state=208257577ll0975l93l2l59l895857093449424
&scope=profile
授权码的大小为18到128个字符。授权代码的有效期为5分钟。
重定向也会复制用户代理在授权请求中传递的state
。您可以通过状态值跟踪用户请求前的状态。此外,状态还可用于阻止跨站点伪造请求。
如果使用适用于JavaScript的Login with Amazon SDK,以上参数可在amazon.Login.authorize
提供的response
对象中获取(示例参见上文授权请求部分)。
授权错误
如果用户未授予访问请求,或者出现错误,授权服务会将用户代理(用户浏览器)重定向到客户端指定的URI。该URI将包含具体的错误参数。例如:
HTTP/1.1 302 Found
Location: https://client.example.com/cb#error=access_denied
&state=208257577ll0975l93l2l59l895857093449424
授权请求失败的错误参数包括:
错误参数 | 描述 |
---|---|
error |
包含错误代码值的ASCII错误代码。 |
error_description |
人类可读的ASCII字符串,含有错误相关信息,对客户端开发者非常有用。 |
error_uri |
指向一个网页的URI,含有人类可读的错误相关信息,对客户端开发者非常有用。 |
state |
客户端在初始授权请求中传递的state 。 |
如果使用适用于JavaScript的Login with Amazon SDK,以上参数可在amazon.Login.authorize
提供的response
对象中获取(示例参见上文授权请求部分)。
返回的error
值中可能包含以下错误代码:
错误代码 | 描述 |
---|---|
invalid_request |
请求中缺少必要参数、具有无效值,或格式不正确。 |
unauthorized_client |
客户端无权请求授权代码。 |
access_denied |
资源所有者或授权服务器拒绝了此请求。 |
unsupported_response_type |
该请求指定了不受支持的响应类型。在此情景下,response_type 必须为code 。 |
invalid_scope |
客户端请求范围错误 |
server_error |
授权服务器发生意外错误(将其视为500内部服务器HTTP错误)。 |
temporarily_unavailable |
授权服务器因暂时过载或计划维护而导致当前不可用(将其视为503服务不可用HTTP错误)。 |
访问令牌请求
客户端(网站)收到包含有效授权代码的授权响应后,可使用该授权代码获取访问令牌。有了访问令牌,客户端就可以读取客户个人资料。
为请求获取访问令牌,客户端会向以下区域终端节点之一发出安全HTTP POST
请求:
- 北美 (NA) -
https://api.amazon.com/auth/o2/token
- 欧盟 (EU) -
https://api.amazon.co.uk/auth/o2/token
- 远东 (FE) -
https://api.amazon.co.jp/auth/o2/token
请在POST
请求中使用下表列出的参数。
参数 | 描述 |
---|---|
grant_type |
必需。请求的访问权限授予类型。必须为authorization_code 。 |
code |
必需。授权请求返回的代码。 |
redirect_uri |
必需。如果您在授权请求中提供了redirect_uri ,则在此情景下必须传递相同的redirect_uri 。如果您使用适用于JavaScript的Login with Amazon SDK来发出授权请求,则在此情况下无需传递redirect_uri 。 |
client_id |
必需。客户端标识符。客户端标识符在网站注册为客户端时进行设置。有关更多信息,请参阅客户端标识符。 |
client_secret |
可选。注册过程中分配给客户端的密钥值。由于网页无法安全存储客户端密钥,您不应在基于浏览器的应用中使用客户端密钥。在没有传递任何client_secret 的情景下,将不会返回刷新令牌。如果code_verifier 有效,则仍会返回访问令牌。 |
code_verifier |
推荐。在授权请求中用于生成code_challenge 的同一code_verifier 。如果授权请求使用了code_challenge ,则必须使用代码验证器。有关更多信息,请参阅PKCE RFC。 |
例如:
POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code
&code=SplxlOBezQQYbYS6WxSbIA
&client_id=foodev
&client_secret=Y76SDl2F
&code_verifier=5CFCAiZC0g0OA-jmBmmjTBZiyPCQsnq_2q5k9fD-aAY
例如:
POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Authorization: Basic czzCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code
&code=SplxlOBezQQYbYS6WxSbIA
要使用适用于JavaScript的Login with Amazon SDK发出令牌请求,您必须在授权调用的options对象中将pkce设置为true。然后使用授权响应中从Authorize
API返回的授权代码来调用amazon.Login.retrieveToken
API。
在pkce设置为true、code_challenge
未指定的情况下,SDK将生成code_verifier
和code_challenge
。code_challenge
用于授权请求。code_verifier
存储在amazon_Login_pkce_params
Cookie中,retrieveToken
API会将它用于令牌请求以获取访问令牌。
必须启用Cookie,且retrieveToken调用必须与authorize
调用位于相同的域。有关更多信息,请参阅retrieveToken API.
options = {}
options.scope = 'profile';
options.pkce = true;
amazon.Login.authorize(options, function(response) {
amazon.Login.retrieveToken(response.code, callback);
});
访问令牌响应
客户端(网站)发出安全的HTTP POST授权请求后,授权服务器将立即返回访问令牌,否则将返回HTTP响应错误。例如:
HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX..."
}
成功的响应包括以下值:
参数 | 描述 |
---|---|
access_token |
用户账户的访问令牌。最大不超过2048字节。 |
token_type |
返回的令牌类型。应为bearer 。 |
expires_in |
访问令牌的有效秒数。 |
refresh_token |
刷新令牌,可用于获取新的访问令牌。最大不超过2048字节。 |
响应参数使用application/json
媒体类型进行编码。有关更多信息,请参阅RFC4627。
访问令牌错误
对于某些错误,授权服务可能会返回HTTP 401(未授权)状态代码。这包括以下情况:客户端在授权标头中传递了client_id
和client_secret
值,但无法对客户端进行身份验证。
不成功的响应包括以下值:
错误参数 | 描述 |
---|---|
error |
包含错误代码值的ASCII错误代码。 |
error_description |
人类可读的ASCII字符串,含有错误相关信息,对客户端开发者非常有用。 |
error_uri |
指向一个网页的URI,含有人类可读的错误相关信息,对客户端开发者非常有用。 |
返回的error
值中可能包含以下错误代码:
错误代码 | 描述 |
---|---|
invalid_request | 请求中缺少必要参数、具有无效值,或格式不正确。 |
invalid_client |
客户端身份验证失败。该参数用于授权服务不返回HTTP 401(未授权)状态代码的情况。 |
invalid_grant |
授权代码无效、已过期、已撤销,或已发放至另一client_id 。 |
unauthorized_client |
客户端无权使用授权代码。可能因code_verifier无效而导致。 |
unsupported_grant_type |
客户端指定了错误的token_type 。 |
ServerError |
服务器运行错误。 |
使用刷新令牌
访问令牌在设定时间过后将失效(通常将返回expires_in
参数)。获取访问令牌后还会收到一个刷新令牌。您可以使用刷新令牌来检索新的访问令牌。
要提交刷新令牌,客户端会使用以下参数向https://api.amazon.com/auth/o2/token
发出安全的HTTP POST请求:
参数 | 描述 |
---|---|
grant_type |
必需。请求的访问权限授予类型。必须为refresh_token 。 |
refresh_token |
必需。由初始访问令牌响应(见上文)返回的刷新令牌。 |
例如:
POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Authorization: Basic czzCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=refresh_token
&refresh_token=Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX...
例如:
POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=refresh_token
&refresh_token=Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX...
&client_id=foodev
&client_secret=Y76SDl2F
提交刷新令牌的响应属于访问令牌响应。
Last updated: 2023年12月11日