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

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

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

amazon.Login方法

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

authorize

AuthorizeRequest authorize(options, next);

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

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

参数

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

另请参阅

logout

logout();

调用authorize,注销当前用户。

参数

无。

返回内容

无。

示例:

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

另请参阅

retrieveToken

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)帮助调用者识别登录用户的唯一标识符。只有请求范围为profileprofile: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) {
     // 显示个人资料信息。
 });

另请参阅

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.comsite2.example.com,则每个网站标头的站点域名都应设置为 example.com。这么做将确保两个站点的Cookie都有权访问相同的缓存令牌。

参数

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

返回内容

无。

另请参阅

setUseCookie

setUseCookie(useCookie);

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

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

参数

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

返回内容

无。

另请参阅

setRegion

setRegion(region);

Login With Amazon具有多个授权和资源终端节点。此API将为Login with Amazon SDK确定应通信的授权和资源终端节点的区域。使用authorizeretreiveProfile 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将根据授权请求类型添加新属性。如果请求失败,错误属性将提供错误信息。

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

响应类型 属性
授权响应  codestate
访问令牌响应(已弃用) access_tokentoken_typeexpires_inscope
错误响应 errorerror_descriptionerror_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)授权服务器授予访问令牌的许可范围。必须是为profileprofile:user_idpostal_code或信息组合。

state

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

status

status - (String)当前的请求状态。请求状态有三种,分别为queuedin progresscomplete

token_type

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