認可コードグラント
認可コードグラントによって、クライアント(通常はウェブサイト)はユーザーエージェント(ユーザーのブラウザ)を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_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_type はcode である必要があります。 |
invalid_scope |
クライアントがリクエストしたスコープに誤りがあります。 |
server_error |
認可サーバーで想定外のエラーが発生しました(HTTP500内部サーバーエラーとして処理)。 |
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
client_id
およびclient_secret
がHTTP Basic認証によって認可ヘッダーに渡される場合があります。詳細については、RFC2617(英語のみ)を参照してください。次に例を示します。
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(英語のみ)を参照してください。
アクセストークンエラー
エラーによっては、認可サービスで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...
client_id
およびclient_secret
がHTTP Basic認証によって認可ヘッダーに渡される場合があります。詳細については、RFC2617(英語のみ)を参照してください。次に例を示します。
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
リフレッシュトークンの送信に対するレスポンスがアクセストークンレスポンスです。