認可コードグラント


認可コードグラント

認可コードグラントによって、クライアント(通常はウェブサイト)はユーザーエージェント(ユーザーのブラウザ)を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_verifierをエンコードしてcode_challengeパラメーターを生成するために使用されるメソッド。推奨値は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 クライアントがリクエストしたスコープに誤りがあります。
server_error 認可サーバーで想定外のエラーが発生しました(HTTP500内部サーバーエラーとして処理)。
temporarily_unavailable 認可サーバーは、一時的なオーバーロードまたは予定されていたメンテナンスのために使用できません(HTTPエラー503サービス利用不可として処理)。

アクセストークンリクエスト

認可レスポンスと有効な認可コードを受け取ったクライアント(ウェブサイト)は、そのコードを使用してアクセストークンを取得できます。アクセストークンがあれば、クライアントはユーザープロファイルを読み取ることができます。アクセストークンをリクエストするため、クライアントは次のパラメーターを使用して、https://api.amazon.com/auth/o2/tokenに安全なHTTP 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_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(英語のみ)を参照してください。

アクセストークンエラー

エラーによっては、認可サービスでHTTP401(認可エラー)のステータスコードが返される場合があります。これには、クライアントが認可ヘッダーにclient_idおよびclient_secretの値を渡して、クライアントが認証されなかった場合などがあります。

失敗時のレスポンスには次の値が含まれます。

エラーパラメーター 説明
error  エラー値を表すASCIIコード。
error_description クライアント開発者が判読できる形でエラーに関する情報を記載したASCII文字列。
error_uri クライアント開発者が判読できる形でエラーに関する情報を記載したウェブページへのURI。

errorの値として、次のいずれかのエラーコードが返されます。

エラーコード 説明
invalid_request リクエストに必須パラメーターがない、値が無効、または形式に誤りがあります。
invalid_client クライアントの認証に失敗しました。これは、認可サービスがHTTP401(認可エラー)のステータスコードを返さない場合に使用されます。
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

リフレッシュトークンの送信に対するレスポンスがアクセストークンレスポンスです。