JavaScript用のLogin with Amazon SDKリファレンスガイド

これは、JavaScript用のLogin with Amazon SDKのリファレンスです。このドキュメントには、JavaScript用のLogin with Amazon SDKに関するリファレンスとSDKの読み込み方法に関する情報が記載されています。Login with Amazonは、AmazonユーザーがAmazon認証情報を使用してウェブやモバイルアプリにログインできるウェブサービスです。ユーザーがログインすると、そのユーザーの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の設定によって、ユーザーがログインするためのポップアップウィンドウが開くか、ログインページにリダイレクトされます。authorizeの前に、setClientIdを呼び出す必要があります。retrieveProfileまたはretrieveTokenの前に、authorizeを呼び出す必要があります。

このメソッドはAuthorizeRequestオブジェクトを返します。そのオブジェクトでonCompleteを呼び出して、コールバック関数またはリダイレクトURIを登録します。これはnextパラメーターに似ています。リクエストが完了すると、レスポンスの詳細を記述したプロパティ（アクセストークンや認可コードなど）がオブジェクトに格納されます。

パラメーター：

options - 必須 -（Object）。
optionsでは、次のプロパティを使用できます。
- interactive -（String）ユーザーにログイン画面を表示するタイミングを指定します。autoの場合は、キャッシュされたトークンの使用を試みます。キャッシュされたトークンが使用できない、または存在しない場合、ユーザーにログイン画面が表示されます。alwaysの場合は、キャッシュされたトークンを使用せずに、常にログイン画面を表示します。neverの場合は、キャッシュされたトークンを使用します。そのトークンが機能しない場合、authorizeはinvalid_grantを返します。デフォルトはautoです。
- popup -（Boolean）trueは、ログイン用のポップアップウィンドウを表示します。falseの場合は、現在のブラウザウィンドウを認可ダイアログにリダイレクトします。デフォルトはtrueです。falseの場合、nextパラメーターをリダイレクト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）Proof Key for Code Exchange（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を指定します。これが指定されておらず、pkceがtrueに設定されている場合、SDKはcode_verifierとcode_challengeを生成します。code_verifierを自分で生成する場合は、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エラー' + response.error);
     return;
  }
alert('成功：' + response.code);
});

例：インプリシットグラント（廃止）

options = { scope: 'profile' };
amazon.Login.authorize(options, function(response) {
  if ( response.error ) {
      alert('oauthエラー' + response.error);
     return;
  }
alert('成功：' + response.access_token);
});

レスポンスのキャッシング

authorizeが有効なアクセストークンのレスポンスを受け取ると、トークンと関連するメタデータは、再利用できるように自動的にキャッシュされます。このキャッシュは、ページの再読み込み後も、異なるブラウザセッション間でも保持されます。後続のauthorizeの呼び出しを、キャッシュされたトークンレスポンスで実行できる場合、SDKは新しい認可をリクエストするのではなく、そのトークンを再利用します。options.interactiveを使用して、この動作をオーバーライドします。

インタラクティブモード

options.interactive設定により、インタラクティブモードを以下の3つの中から選択できます。

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("キャッシュされたアクセストークン：" + tokenResponse.access_token);
  } else {
    options = {};
    options.scope = 'profile';
    options.pkce = true;
    amazon.Login.authorize(options, function(response) {
      if ( response.error ) {
        alert('oauthエラー' + response.error);
        return;
      }
      amazon.Login.retrieveToken(response.code, function(response) {
        alert('アクセストークン：' + 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）ユーザーの主なEメールアドレス。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エラー' + response.error);
       return;
     }
     amazon.Login.retrieveToken(response.code, function(response) {
        if ( response.error ) {
          alert('oauthエラー' + response.error);
          return;
        }
        amazon.Login.retrieveProfile(response.access_token, function(response) {
           alert('こんにちは。' + response.profile.Name);
           alert('あなたのEメールアドレス：' + response.profile.PrimaryEmail);
           alert('あなたの一意のID：' + 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('こんにちは。' + response.profile.Name);
     alert('あなたのEメールアドレス：' + response.profile.PrimaryEmail);
     alert('あなたの一意のID：' + response.profile.CustomerId);
  }
  else {
     alert(' エラーが発生しました：' + 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 Sandboxを使用するには、authorizeを呼び出す前にsetSandboxMode(true)を呼び出します。

パラメーター

sandboxMode - 必須 -（boolean）。Amazon Pay Sandboxを使用してリクエストを処理する場合はtrue、使用しない場合はfalseになります。

戻り値

なし。

関連項目

setSiteDomain

setSiteDomain(siteDomain);

Cookieを保存するために使用するドメインを設定します。ドメインは現在のページのオリジンと一致している必要があります。デフォルトは現在のページのフルドメインになります。たとえば、JavaScript用のLogin with Amazon SDKを使用してsite1.example.comとsite2.example.comという2つのページを用意している場合、各サイトのヘッダーでサイトドメインをexample.comに設定します。これにより、どちらのサイトのCookieでも、キャッシュされている同じトークンにアクセスできるようになります。

パラメーター

siteDomain - 必須 -（String）。Login with AmazonのCookieを保存するためのサイト。現在のページのオリジンを共有する必要があります。

戻り値

なし。

関連項目

setUseCookie

setUseCookie

setUseCookie(useCookie);

amazon_Login_accessToken Cookieに書き込まれたアクセストークンをLogin with Amazonが使用するかどうかを指定します。この値を使用して、ほかのページとアクセストークンを共有できます。アクセストークンは特定のアカウントを対象に生成されるため、登録されたそのアカウントにのみ使用できます。

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またはString）ブラウザレスポンスをリダイレクトするためのURI、または認可レスポンスを引数として呼び出すJavaScript関数。

access_token

access_token -（String）認可サーバーによって発行されるアクセストークン。

code

code -（String）アクセストークンと交換できる認可コード。

error

error -（String）認可に失敗した理由を示す短いエラーコード。次のいずれかになります。

エラー	説明
access_denied	ユーザーまたは認可サーバーがリクエストを拒否しました。
invalid_grant	キャッシュされているトークンを使用できないため、認可サーバーがリクエストを拒否しました。
invalid_request	リクエストに必須パラメーターがない、値が無効、または形式に誤りがあります。
invalid_scope	リクエストされたスコープのうち少なくとも1つが無効です。
server_error	認可サーバーで想定外のエラーが発生しました。これは、HTTPステータスコード500に似ています。
temporarily_unavailable	現在、一時的な問題により認可サーバーを利用できません。これは、HTTPステータスコード503に似ています。
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）発行されたトークンの種類。bearerである必要があります。