認可コードグラント

認可コードグラント

認可コードグラントによって、クライアント(通常はウェブサイト)はユーザーエージェント(ユーザーのブラウザ)をAmazonのURIに移動させることができます。ユーザーには、ユーザープロファイルへのアクセスをウェブサイトに許可するように求めるページが表示されます。ユーザーが承認すると、クライアントは認可コードを受け取り、そのコードと引き換えにアクセストークンリフレッシュトークンを取得できます。

アクセストークンを取得したクライアントは、ユーザープロファイルを読み取ることができます。このユーザーエクスペリエンスの詳細については、認可グラントを参照してください。

ユーザーがリクエストを拒否した場合、クライアントは認可サービスからエラーを受け取ります。

認可リクエスト

認可をリクエストするには、クライアント(ウェブサイト)でユーザーエージェント(ブラウザ)をリダイレクトして、次のパラメーターと共にhttps://www.amazon.com/ap/oaへの安全なHTTP呼び出しを行う必要があります。認可ヘッダーを使用してアクセストークンをリクエストする場合は、Base64エンコードのclient_id:client:secretを使用する必要があります。

パラメーター 説明
client_id 必須クライアント識別子。Login with Amazonのクライアントとしてウェブサイトを登録すると提供されます。最大サイズは100バイトです。
scope 必須。リクエストの範囲。profileprofile:user_idpostal_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_typecodeにする必要があります。
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_verifiercode_challengeを生成します。code_challengeは認可リクエストで使用されます。code_verifieramazon_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_idclient_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日