認可コードグラント
認可コードグラントによって、クライアント（通常はウェブサイト）はユーザーエージェント（ユーザーのブラウザ）をAmazonのURIに移動させることができます。ユーザーには、ユーザープロファイルへのアクセスをウェブサイトに許可するように求めるページが表示されます。ユーザーが承認すると、クライアントは認可コードを受け取り、そのコードと引き換えにアクセストークンとリフレッシュトークンを取得できます。
アクセストークンを取得したクライアントは、ユーザープロファイルを読み取ることができます。このユーザーエクスペリエンスの詳細については、認可グラントを参照してください。
ユーザーがリクエストを拒否した場合、クライアントは認可サービスからエラーを受け取ります。
認可リクエスト
認可をリクエストするには、クライアント（ウェブサイト）でユーザーエージェント（ブラウザ）をリダイレクトして、次のパラメーターと共にhttps://www.amazon.com/ap/oaへの安全なHTTP呼び出しを行う必要があります。認可ヘッダーを使用してアクセストークンをリクエストする場合は、Base64エンコードのclient_id:client:secretを使用する必要があります。
| パラメーター | 説明 |
|---|---|
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 |
推奨。Proof Key for Code Exchange（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エラー' + 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エラー' + response.error);
return;
}
amazon.Login.retrieveToken(response.code, function(response) {
if ( response.error ) {
alert('OAuthエラー' + response.error);
return;
}
alert('アクセストークン：' + response.access_token);
});
});
amazon.Login.authorizeの最初のパラメーターは常にoptionsオブジェクトです。2番目のパラメーターは、認可レスポンスを処理する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 |
クライアントがリクエストしたscopeに誤りがあります。 |
server_error |
認可サーバーで予期しないエラーが発生しました（HTTP 500内部サーバーエラーとして処理）。 |
temporarily_unavailable |
認可サーバーは、一時的なオーバーロードまたは予定されていたメンテナンスのために使用できません（HTTPエラー503サービス利用不可として処理）。 |
アクセストークンリクエスト
認可レスポンスと有効な認可コードを受け取ったクライアント（ウェブサイト）は、そのコードを使用してアクセストークンを取得できます。アクセストークンがあれば、クライアントはユーザープロファイルを読み取ることができます。
アクセストークンをリクエストするには、クライアントは次のいずれかのリージョンのエンドポイントに、安全な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を使用してトークンリクエストを行うには、authorizeの呼び出しに使用される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 |
ユーザーアカウントのアクセストークン。最大サイズは2,048バイトです。 |
token_type |
返されたトークンのタイプ。bearerである必要があります。 |
expires_in |
アクセストークンが無効になるまでの秒数。 |
refresh_token |
新しいアクセストークンをリクエストするために使用できるリフレッシュトークン。最大サイズは2,048バイトです。 |
レスポンスパラメーターは、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日
