認可コードグラント


認可コードグラント

認可コードグラントによって、クライアント(通常はウェブサイト)はユーザーエージェント(ユーザーのブラウザ)を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 推奨。このリクエストからレスポンスまでの状態を維持するためにクライアントが使用する不透明型の値。認可サービスがユーザーをクライアントに戻すときに、この値をパラメーターに含めます。また、クロスサイトリクエストフォージェリを防ぐためにも使用されます。詳細については、クロスサイトリクエストフォージェリを参照してください。

次に例を示します。

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

JavaScript用のLogin with Amazon SDKを使用して認可リクエストを行うには、optionsオブジェクトを入力し、amazon.Login.authorizeを呼び出す必要があります。

options = { } ;
options.scope = 'profile';
options.response_type='code';
amazon.Login.authorize(options, function(response) {
  if ( response.error ) {
   alert('oauthエラー' + response.error);
   return;
  }
  <!-- response.codeサーバーに渡しこれ使用して
  アクセストークンをリクエストします Javascript SDKこの手順サポートしません
  クライアントシークレット公開されることになるため)-->
});

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パラメーター(認可コード付き)が含まれます。次に例を示します。

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBezQQYbYS6WxSbIA
&state=208257577ll0975l93l2l59l895857093449424

認可コードは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 必須。登録時にクライアントに割り当てられたシークレット値。

次に例を示します。

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

次に例を示します。

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には、アクセストークンと認可コードを交換する関数が含まれていません。その理由としては、交換時にクライアントシークレットが必要になりますが、これはスクリプトに格納すべきでないからです。したがって、ウェブサーバーで交換を行う必要があります。認可コードのリクエストにamazon.Login.authorizeを使用する場合、サーバーに認可コードを渡すか、サーバー側のコードで処理されるredirect_uriを使用する必要があります。

アクセストークンレスポンス

クライアント(ウェブサイト)が安全な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 認可コードを使用する権限がクライアントにありません。
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

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