适用于JavaScript的Login with Amazon SDK参考指南

此文档为适用于JavaScript的Login with Amazon SDK参考。此文档包含适用于JavaScript的Login with Amazon SDK参考信息，以及有关如何加载SDK的信息。Login with Amazon作为一项网站服务，能够让亚马逊客户使用亚马逊凭证登录到您的网站或移动应用。用户成功登录后，您的应用可以访问其亚马逊个人资料中的某些信息。

amazon.Login方法
amazon.Login类
- AuthorizeRequest
  - onComplete
  - access_token
  - code
  - error
  - error_description
  - error_uri
  - expires_in
  - scope
  - state
  - status
  - token_type

amazon.Login方法

login.js中的所有函数均可在amazon.Login命名空间中找到。这些函数能够识别客户端应用、请求访问令牌以及交换客户个人资料信息的访问令牌。客户个人资料

authorize
getClientId
logout
retrieveToken
retrieveProfile
setClientId
setSandboxMode
setSiteDomain
setUseCookie

authorize

AuthorizeRequest authorize(options, next);

根据options请求授权，然后进行重定向或者调用next。系统会根据options设置打开用户登录的弹出窗口，将重定向至登录页面。调用授权前必须先调用setClientId。调用retrieveProfile或retrieveToken前必须先调用authorize。

此方法的返回对象为AuthorizeRequest。在此对象上调用onComplete来注册回调函数或重定向URI，类似于next参数。请求完成后，该对象将包含说明响应情况的属性详情（如访问令牌或授权码）。

参数：

options – 必需 - (Object)。
options可以包含以下属性：
- interactive - (String)指定何时向用户显示登录界面。auto会尝试使用缓存的令牌。如果缓存令牌失败或不存在，则会向用户显示登录界面。always不使用缓存的令牌，且始终显示登录界面。never会使用缓存的令牌；如果令牌没有生效，授权将返回invalid_grant。默认为auto。
- popup - (Boolean) true、false 使用弹出窗口浏览器窗口重定向当前登录的授权对话框。默认为true。如果为false，则下一项参数必须为重定向URL重定向URL。原生iOS应用不支持弹出窗口。
- response_type - (String)请求的授权类型。指定隐式授予请求的token或授权码授予的code。目前已不再支持token。未来所有客户端必须指定为code。默认为token。
- scope - 必需 - （String或Array[String]）访问范围。必须是为profile、profile:user_id、postal_code或信息组合。
- state - (String)状态参数。客户端在请求和响应期间用来保持状态的不透明值。Login with Amazon将授权服务将用户重定向返回客户端时将包含此值授权服务。此外，状态值还可用于阻止跨站点伪造请求。有关更多信息，请参阅跨站点伪造请求。
- pkce - (Boolean)通过代码交换证明密钥(PKCE)来确保授权码授予安全。基于浏览器的应用必须设置为true。如果设置为true，response_type将自动设置为code。如果没有指定code_challenge，SDK将生成一项code_verifier和code_challenge。code_challenge用于授权请求。code_verifier存储在Cookie中，并在令牌请求中由retrieveToken API使用。默认为false。有关更多信息，请参阅PKCE RFC。
- code_challenge - (String)可选。使用PKCE时，为授权请求指定要包含的code_challenge。如果没有指定且此字段设置为true，SDK将生成code_verifier和code_challenge。如果自行生成code_verifie，则应使用SHA-256计算code_challenge。
next（Function或String）重定向浏览器响应的URI，或者与授权响应一同进行调用的JavaScript函数。

关于next参数

如果next为URI，用户登录后，当前窗口将立即重定向到此URI，授权响应将添加到查询字符串。URI必须使用HTTPS协议，且与当前窗口属于同一域。

示例：授权码授予

options = { scope: 'profile', response_type: 'code' };
amazon.Login.authorize(options, 'https://example.org/redirect_here')
// 成功时，当前窗口将重定向至：
// https://example.org/redirect_here?code=ABJHSCO...

// 失败时，当前窗口将重定向至：
// https://example.org/redirect_here?error=access_denied&...

示例：隐式授予（已弃用）

options = { scope: 'profile' };
amazon.Login.authorize(options, 'https://example.org/redirect_here')
// 成功时，当前窗口将重定向至：
// https://example.org/redirect_here?access_token=XYZ&token_type=bearer&…

// 失败时，当前窗口将重定向至：
// https://example.org/redirect_here?error=access_denied&...

如果next为回调函数，将调用包含授权响字段的响应对象。

示例：授权码授予

options = { scope: 'profile', response_type: 'code' };
amazon.Login.authorize(options, function(response) {
  if ( response.error ) {
      alert('oauth error ' + response.error);
     return;
  }
alert('success: ' + response.code);
});

示例：隐式授予（已弃用）

options = { scope: 'profile' };
amazon.Login.authorize(options, function(response) {
  if ( response.error ) {
      alert('oauth error ' + response.error);
     return;
  }
alert('success: ' + response.access_token);
});

响应缓存

authorize接收到有效的访问令牌响应后，会自动缓存令牌和相关元数据，以便重复使用。这类缓存会在页面重新加载和浏览器会话中持续存在。如果之后可以用已缓存的令牌响应来完成authorize调用，SDK将不再请求新的授权，而是重复使用此缓存令牌。options.interactive可用来覆盖此行为。

交互模式

options.interactive设置有三种交互模式可供选择。具体包括：

auto：尝试授权用户使用已缓存的令牌。如果失败，将在必要情况下启动新的授权，显示登录和同意界面同意界面。
always：显示登录界面并忽略缓存令牌，启动新授权。
never：尝试授权用户使用已缓存的令牌。如果失败，将返回invalid_grant错误。

返回内容

AuthorizeRequest对象。登录请求完成后，AuthorizeRequest将允许调用者注册回调函数或者要使用的重定向URL。还允许调用者获取当前请求状态。请求完成后，新属性将根据授权请求类型添加到AuthorizeRequest。如果请求失败，该对象将添加错误属性。

getClientID

getClientId();

获取可用于授权请求的客户端标识符客户端标识符。调用此函数前必须先调用setClientId。

参数

无。

返回内容

clientId - (String)。分配给应用的客户端ID。最大不超过100字节。

另请参阅

setClientId

logout

logout();

调用authorize，注销当前用户。

参数

无。

返回内容

无。

示例：

<script type="text/javascript">
  document.getElementById('logout').onclick = function() {
     amazon.Login.logout();
  };
</script>

另请参阅

authorize

retrieveToken

注意： 此函数不支持Internet Explorer 9或更低版本。

retrieveToken(code, callback);

适用于使用PKCE、基于浏览器的应用(options.pkce = true)。检索访问令牌并将其传递给回调函数。使用authorize提供的授权码。未提供代码和回调的情况下，如果该值有效或返回null，则返回缓存令牌。使用由authorize API存储在amazon_Login_pkce_params Cookie中的code_verifier。必须启用Cookie，且retrieveToken调用必须与authorize调用位于相同的域。

参数

code - 可选 - (String)授权码

回调 (callback)

function(response);

与令牌或错误字符串一同进行调用。

回调参数

response - (Object)
- success - (Boolean) true（如果请求成功）；否则返回false。
- error - (String)如果请求失败将提供此字符串，其中包含一条错误消息。
- access_token - (String)如果请求成功，提供此字符串，其中包含个人资料消息。
- expires_in - (Number)访问令牌的有效秒数。

示例：

<script type="text/javascript">

window.doLogin = function() {
  var tokenResponse = amazon.Login.retrieveToken();
  if (tokenResponse) {
    alert("Cached Access Token: " + tokenResponse.access_token);
  } else {
    options = {};
    options.scope = 'profile';
    options.pkce = true;
    amazon.Login.authorize(options, function(response) {
      if ( response.error ) {
        alert('oauth error ' + response.error);
        return;
      }
      amazon.Login.retrieveToken(response.code, function(response) {
        alert('Access Token: ' + response.access_token);
        if (window.console && window.console.log)
          window.console.log(response);
      });
    });
  };
};
</script>

retrieveProfile

retrieveProfile(accessToken, callback);

检索客户个人资料并将其传递给回调函数。使用authorize提供的访问令牌。

参数

accessToken - 必需 - (String)访问令牌。

回调 (callback)

function(response);

与个人资料数据或错误字符串一同进行调用。

回调参数

response - (Object)
- success - (Boolean) true（如果请求成功）；否则返回false。
- error - (String)如果请求失败将提供此字符串，其中包含一条错误消息。
- profile - (Object)如果请求成功，提供此对象，其中包含个人资料消息。
  - CustomerId - (String)帮助调用者识别登录用户的唯一标识符。只有请求范围为profile或profile:user_id，且得到授权后才会显示。
  - Name - (String)客户名称。只有请求范围为profile，且得到授权后才会显示。
  - PostalCode - (String)客户主要地址的邮政编码。只有请求范围为postal_code，且得到授权后才会显示。
  - PrimaryEmail - (String)客户的主要电子邮件地址。只有请求范围为profile，且得到授权后才会显示。

示例1：

<script type="text/javascript">
document.getElementById('LoginWithAmazon').onclick = function() {
 setTimeout(window.doLogin, 1);
 return false;
};
window.doLogin = function() {
  options = {};
  options.scope = 'profile';
  options.pkce = true;
  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;
        }
        amazon.Login.retrieveProfile(response.access_token, function(response) {
           alert('Hello, ' + response.profile.Name);
           alert('Your e-mail address is ' + response.profile.PrimaryEmail);
           alert('Your unique ID is ' + response.profile.CustomerId);
           if (window.console && window.console.log)
              window.console.log(response);
        });
     });
 });
};
</script>

示例2：

var access_token = 'Atza|EKdsnskdna…';

amazon.Login.retrieveProfile(access_token, function(response) {
  if ( response.success ) {
     alert('Hello, ' + response.profile.Name);
     alert('Your e-mail address is ' + response.profile.PrimaryEmail);
     alert('Your unique ID is ' + response.profile.CustomerId);
  }
  else {
     alert('Oh no! An error happened: ' + response.error);
  }
});

示例3（已弃用）：

如果access_token已省略，retrieveProfile将调用authorize来请求profile范围。不再支持此选项。

 amazon.Login.retrieveProfile(function (response) {
     // 显示个人资料信息。
 });

另请参阅

authorize

setClientId

setClientId(clientId);

设置将用于请求授权的客户端标识符。必须先调用此函数才能调用authorize。

参数

clientId - 必需 - (String)。分配给应用的客户端ID。

返回内容

无。

示例：

window.onAmazonLoginReady = function() {
  amazon.Login.setClientId('YOUR-CLIENT-ID');
};

setSandboxMode

setSandboxMode(sandboxMode);

确定Login with Amazon是否应为请求使用Amazon Pay沙盒。要使用Amazon Pay沙盒，应先调用 setSandboxMode (true)，然后再调用authorize。

参数

sandboxMode - 必需 - (boolean)。使用Amazon Pay沙盒处理请求则返回true，否则返回false。

返回内容

无。

另请参阅

setSiteDomain

setSiteDomain(siteDomain);

设置用于保存Cookie的域名。此域名必须与当前页面的源相匹配。默认为当前页面的完整域。例如，如果您在两个页面中都使用了适用于JavaScript的Login with Amazon SDK，即 site1.example.com和site2.example.com，则每个网站标头的站点域名都应设置为 example.com。这么做将确保两个站点的Cookie都有权访问相同的缓存令牌。

参数

siteDomain - 必需 - (字符串)。存储Login with Amazon Cookie的站点。必须与当前页面同源。

返回内容

无。

另请参阅

setUseCookie

setUseCookie

setUseCookie(useCookie);

确定Login with Amazon是否应使用写入amazon_Login_accessToken Cookie的访问令牌。您可以使用此值与其他页面共享访问令牌。访问令牌仍然只向创建它们的注册账户授予访问权限。

如果为true，则适用于JavaScript的Login with Amazon SDK将检查该Cookie中有没有缓存令牌，并在该Cookie中存储新授予的令牌。

参数

useCookie - 必需 - (boolean)。true表示将来自authorize的访问令牌存储到一个Cookie中，否则返回false。

返回内容

无。

另请参阅

authorize
setSiteDomain
setRegion

setRegion

setRegion(region);

Login With Amazon具有多个授权和资源终端节点。此API将为Login with Amazon SDK确定应通信的授权和资源终端节点的区域。使用authorize和retreiveProfile API前需要先调用此区域。

如果尚未设置，则默认为“NorthAmerica”

参数

region - (amazon.Login.Region) - 必需。以下任选其一

amazon.Login.Region.NorthAmerica
amazon.Login.Region.Europe
amazon.Login.Region.AsiaPacific

返回内容

无。

amazon.Login类

AuthorizeRequest

AuthorizeRequest类用于authorize调用响应，登录请求完成后，AuthorizeRequestM将允许调用者注册回调函数或者要使用的重定向URL。还允许调用者获取当前请求状态。请求完成后，AuthorizeRequest将根据授权请求类型添加新属性。如果请求失败，错误属性将提供错误信息。

下表详细说明了每个响应类型的新添加属性：

响应类型	属性
授权响应	code和state
访问令牌响应（已弃用）	access_token、token_type、expires_in和scope
错误响应	error、error_description和error_uri

onComplete

onComplete(next);

注册回调函数或设置重定向URI，以便授权请求完成时调用。如果在请求完成后调用此函数，将会立即生效或进行重定向。如果使用的是回调函数，则首个参数为AuthorizeRequest。如果使用的是重定向URI，浏览器将使用查询字符串中包含的OAuth 2响应参数，重定向到此URI。

如果设置了多个重定向URL，AuthorizeRequest将使用最新的URL。

参数

next - (Function or String)重定向浏览器响应的URI，或者与授权响应一同进行调用的JavaScript函数。

access_token

access_token - (String)授权服务器发放的访问令牌。

code

code - (String)可用于交换访问令牌的授权码。

error

error - (String)用于说明授权失败原因的简短错误代码。以下任选其一：

错误	描述
access_denied	客户或授权服务器拒绝此请求。
invalid_grant	授权服务器因无法使用缓存令牌而拒绝请求。
invalid_request	请求中缺少必要参数，具有无效值，或格式错误。
invalid_scope	一个或多个请求范围无效。
server_error	授权服务器发生意外错误。类似500 HTTP状态代码。
temporarily_unavailable	授权服务器因暂时状况造成当前不可用。类似503 HTTP状态代码。
unauthorized_client	客户端未得到执行此请求的授权。

error_description

error_description - (String)人类可读的错误描述。

error_uri

error_uri - (String)包含更多错误信息的URI网页。

expires_in

expires_in - (Number)访问令牌的有效秒数。

scope

scope - (String)授权服务器授予访问令牌的许可范围。必须是为profile、profile:user_id、postal_code或信息组合。

state

state - (String)使用options对象提供给authorize的state值。

status

status - (String)当前的请求状态。请求状态有三种，分别为queued、in progress和complete。

token_type

token_type - (String)已发放的令牌类型。必须为不记名。