JavaScript用のLogin with Amazon SDKリファレンスガイド
これは、JavaScript用のLogin with Amazon SDKのリファレンスです。このドキュメントには、JavaScript用のLogin with Amazon SDKに関するリファレンスとSDKの読み込み方法に関する情報が記載されています。Login with Amazonは、AmazonユーザーがAmazon認証情報を使用してウェブやモバイルアプリにログインできるウェブサービスです。ユーザーがログインすると、そのユーザーのAmazonプロファイル情報の一部にアプリがアクセスできるようになります。
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バイトです。
関連項目
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("キャッシュされたアクセストークン:" + 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) {
// プロファイル情報を表示します。
});
関連項目
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(useCookie);
amazon_Login_accessToken
Cookieに書き込まれたアクセストークンをLogin with Amazonが使用するかどうかを指定します。この値を使用して、ほかのページとアクセストークンを共有できます。アクセストークンは特定のアカウントを対象に生成されるため、登録されたそのアカウントにのみ使用できます。
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が通信する認可エンドポイントとリソースエンドポイントのリージョンを指定します。これは、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である必要があります。