Authorization code grantを設定する

---

Alexa Skills Kitは、カスタムスキル、スマートホームスキル、ビデオスキル、会議スキル、音楽スキルでのアカウントリンクでAuthorization code grantをサポートしています。

このGrant種別では、ユーザーのサービス認証後、認可サーバーが認可コード（code）を提供します。Alexaはこのcodeを使って、認可サーバーからアクセストークンと更新トークンのペアをリクエストします。Alexaは、古いトークンの期限が切れたら更新トークンを使って新しいアクセストークンをリクエストできます。

• Authorization Code Grantフローの概要
• Authorization Code Grantの設定手順
• 認証画面のURI
  • 認証画面のURIに渡されるパラメーター
• アクセストークンと更新トークン
• アカウントリンクの設定
  • Alexaのリダイレクト先のURL
• アカウントリンクフローのテスト
• 関連トピック

Authorization Code Grantフローの概要

1. ユーザーがアカウントリンクプロセスを開始します。どこで開始するかはスキルの種類によって異なります。
   • カスタムスキルの場合、カスタムスキルのアカウントリンクを参照してください。
   • スマートホームやビデオ、会議、音楽などのスキルの場合、スマートホームなどのドメインのアカウントリンクを参照してください。

2. Alexaアプリでは、アカウントリンクを設定する際に指定した認証画面のURIを使用してアプリにログインページを表示します。このログインページでは認可サーバーを使ってユーザーの認証を行います。

   Alexaアプリが指定した認証画面のURIを呼び出すと、このURIにはクエリー文字列のパラメーターとしてstate、client_id、response_type、scope、redirect_uriが含まれます。

3. ユーザーは認可サーバーの認証情報を使ってログインします。
4. ユーザーが認証されると、認可サーバーが認可コード（code）を生成します。
5. 認可サーバーによりユーザーはAmazonが提供するredirect_uriにリダイレクトされます。その際、URLのクエリ文字列パラメーターでstateとcodeが渡されます。

6. AlexaサービスはPOSTリクエストのcodeを使って、認可サーバーのアクセストークンURIからアクセストークンと更新トークンのペアをリクエストします。認証サーバーは、アクセストークンと更新トークンをJSONレスポンスで返します。

   認可サーバーは4.5秒以内にトークンリクエストに応答する必要がありますのでご注意ください。

7. Alexaはアクセストークンと更新トークンを保存します。

   ユーザーのAlexaアカウントは他のサービスのアカウントにリンクされ、スキルが使用できるようになりました。

8. 以降、ユーザーがスキルに対してリクエストを行うとき、各リクエスト（カスタムスキルのIntentRequestやスマートホームスキルのTurnOnディレクティブなど）にはアクセストークン（access_token）が含まれます。スキルはこのトークンを使ってリソースサーバーから必要な情報を取得します。access_tokenの期限が切れると、Alexaは更新トークンを使ってアクセストークンURIを再度呼び出し、新しいアクセストークンと更新トークンのペアをリクエストします。

以下の図は、ユーザーがアカウントをリンクしてAlexaが認可サーバーからアクセストークンを取得するときの最初のセットアップを表しています。

この図では、ユーザーがスキルに対してリクエストを行い、スキルがアクセストークンを使ってリソースサーバーから情報を取得するフローを表しています。

Authorization Code Grantの設定手順

1. アカウントリンクの要件に記載されている要件を満たしている認可サーバーがあることを確認します。
2. 開発者ポータルでAuthorization code grant用にスキルを設定します。詳細については、アカウントリンクの設定を参照してください。

Authorization code grantを設定したら、次の手順に進み、スキルコードにアクセストークンを検証して使用する処理を追加します。詳細については、次のページを参照してください。

• カスタムスキルコードでアクセストークンを検証して使用する
• スマートホーム、ビデオ、会議スキルでアクセストークンを検証して使用する

認証画面のURI

ユーザーがアカウントリンクのプロセスを開始すると、Alexaアプリに認可サーバーのログインページが表示されます。認可サーバーは、ユーザーの認証情報を検証してcodeを返す必要があります。Alexaはこのコードを使ってアクセストークンと交換します。

開発者ポータルのビルド > アカウントリンクページにこのログインページのURLを指定します。ログインページのURLは、認証画面のURIフィールドに入力します。codeをアクセストークンと交換するサーバーのURIは、アクセストークンのURIフィールドに指定します。

たとえば、Amazonが提供するリダイレクト先のURLが以下だったとします。

認証画面のURIはユーザーを以下にリダイレクトします。

パラメーターは、URLのハッシュタグ（#）以降に指定されるURLフラグメントで渡されます。

認可サーバーの要件については、認可URIの要件を参照してください。

認証画面のURIに渡されるパラメーター

認証画面のURIを呼び出す場合、AlexaアプリではURLのクエリー文字列に以下のパラメーターを含みます。

パラメーター	説明
client_id	スキルのIDです。このIDを使って、アカウントリンクを使うよう設定した他のスキルと区別するなど、スキル固有の機能を提供できます。client_idは、スキルのアカウントリンクを設定する際に定義します。
redirect_uri	サービスが認証したユーザーをリダイレクトする、Amazon固有のリダイレクト先のエンドポイント（リダイレクト先のURL）です。このパラメーターで想定される値は、開発者コンソールでスキルのアカウントリンクを設定する際にも表示されます。
response_type	他のサービスによってユーザーが認証された後に返される応答の種類を表します。Authorization code grantの場合は常にcodeです。
scope	Alexaユーザーが必要とするアクセスを表すスコープのリスト（任意）です。これらのスコープは、スキルのアカウントリンクを設定する際に定義します。 サービスはアクセストークンを生成するときにこの情報を使用します。たとえば、サービスはリソースサーバーの基本のプロフィール情報にはアクセスできるが、支払い情報にはアクセスできないトークンを作成する場合などです。 スコープは複数使用できます。リストは、URLエンコードされたスペースで区切ります。 ログインページでは、ユーザーにアカウントリンクによってどのようなアクセスが付与されるかを伝える必要があります。たとえば、ログインページには「アカウントリンクを行うと、タクシー予約スキルがあなたに代わってタクシーの配車を依頼し、料金をあなたの口座に請求できるようになります。」などのテキストを表示できます。 スマートホームスキルの場合、このページには「アカウントリンクを行うと、マイライトスキルでマイライトハブに接続された照明を制御できるようになります。」などと表示できます。
state	アカウントリンクを使用してユーザーをトラッキングするために、Alexaサービスが内部的に使用する値です。 Alexaアプリは、認証URIを介して認証サーバーにstate値を送信します。承認サーバーは、その特定のアカウントリンクリクエストのリダイレクトURIを呼び出すときに、同じstate値を使用する必要があります。認可サーバーへの各リクエストには、独自のstate値があります。

たとえば、ページの認証画面のURIがhttps://www.ridehailer.com/loginの場合、Alexaアプリによって呼び出されるURLは以下のようになります。

アクセストークンと更新トークン

認可サーバーはユーザーを一意に識別するアクセストークンを提供する必要があります。スキルはこのトークンを使ってリソースサーバーのユーザーに関する情報にアクセスできます。

Alexaサービスは、認可サーバーのアクセストークンエンドポイント（開発者コンソールのアクセストークンURI）を呼び出して、codeとクライアント認証情報をPOSTリクエストで渡します。認可サーバーはアクセストークンと任意の更新トークンをJSONレスポンスで返す必要があります。更新トークンは任意ですが、アクセストークンに期限がある場合に使うことをお勧めします。

アクセストークンリクエストの例：

アクセストークンレスポンスの例：

アクセストークンと更新トークンの要件については、アクセストークンのURI要件を参照してください。

アクセストークンを生成する場合、リソースサーバー固有のトークンを提供します。セキュリティを確保するため、トークンはユーザーを識別でき、推測できない値にしてください。

アカウントリンクの設定

開発者コンソールのビルド＞アカウントリンクでアカウントリンクを有効にします。また、ASK CLIまたはスキル管理APIを使ってアカウントリンクを設定することもできます。

以下の表は、アカウントリンク設定で入力の必要なフィールドです。サードパーティOAuthプロバイダーを使用する場合、そのプロバイダーのドキュメントを確認してフィールドに入力する値を判断してください。

フィールド	説明
ユーザーがアカウントや既存アカウントへのリンクを作成することを許可しますか？	カスタムスキルでアカウントリンクを有効にする場合に選択します。 このオプションはスマートホームスキルとビデオスキルでは自動で選択されます。
ユーザーがアカウントリンクなしでスキルを有効にすることを許可してください	ユーザーがスキルを有効にする際にアカウントリンクフローを行わない場合は、これを選択します。カスタムスキルでのみ使用できます。スキルが、アカウントを必要とする機能にだけでなく、アカウントリンクが不要な便利な機能がある場合に使用します。ユーザーがアカウントをリンクせずにスキルを有効にするを参照してください。 このオプションはデフォルトではオンです。
Authorization Grant種別を選択	アクセストークン取得に使用するOAuth 2.0のAuthorization Grant種別です。Auth Code Grantを選択します。スマートホームスキルとビデオスキルの場合、このGrant種別しかサポートされないため自動で選択されます。
認証画面のURI	ユーザーがサービスへのログインに使用できるページのURIです。ユーザーがアカウントリンクプロセスを開始すると、Alexaアプリはこのページを表示します。詳細と要件については認証画面のURIを参照してください。 サードパーティのOAuthプロバイダーを使用している場合、認可リクエスト用に提供されているURIをご確認ください。たとえばLogin with Amazonの場合、認証画面のURIはhttps://www.amazon.com/ap/oaです。
アクセストークンのURI	認可サーバーのアクセストークンエンドポイントのURIです。 AlexaサービスはこのURIを呼び出して、認可コードをアクセストークンに交換します。前回のトークンの有効期限が切れると、Alexaは更新トークンを使ってこのURIを呼び出して新しいアクセストークンを取得します。 サードパーティのOAuthプロバイダーをお使いの場合、アクセストークンリクエスト用に提供されているURIをご確認ください。たとえばLogin with Amazonの場合、アクセストークンリクエストのURIはhttps://api.amazon.com/auth/o2/tokenです。 トークンの要件と詳細については、アクセストークンと更新トークンを参照してください。
ユーザーのクライアントID	認証をリクエストするユーザーを識別する一意の文字列です。この値は、client_idパラメーターとして認証画面のURIに渡されます。 このクライアントIDも、アクセストークンURIからアクセストークンをリクエストするときにAlexaサービスが含めるクライアント認証情報の一部です。 サードパーティOAuthプロバイダーを使用している場合、プロバイダーが想定しているクライアントIDを確認してください。たとえばLogin with Amazonの場合、このIDはLogin with Amazonのセキュリティプロファイルを作成するときに作成されます。
ユーザーのシークレット	アクセストークンURIを使ってAlexaサービスの認証を行うための認証情報です。ユーザーのクライアントIDと組み合わせて、Alexaからのリクエストを識別するのに使用されます。 サードパーティOAuthプロバイダーを使用している場合、プロバイダーが想定しているクライアントIDを確認してください。たとえばLogin with Amazonの場合、クライアントシークレットはLogin with Amazonのセキュリティプロファイルを作成するときに作成されます。
ユーザーの認可スキーム	アクセストークンURIからトークンをリクエストするときにAlexaが使用する認証の種類を指定します。
ユーザーのリダイレクト先のURL	開発者アプリをポイントし、アプリ間アカウントリンクの実装のみに使用されます。
Scope	他のサービスの権限のリスト（任意）です。リソースサーバーが異なるアクセススコープをサポートする場合、それらのスコープを指定します。最大15個まで指定できます。 ここで指定するすべてのスコープは、Alexaアプリが認証画面のURIを呼び出す際のscopeパラメーターに含まれます（URLエンコードされたスペースで区切る）。 サードパーティのOAuthプロバイダーを使用している場合、プロバイダーがサポートするスコープのセットから指定してください。たとえばLogin with Amazonの場合、profile、profile:user_id、postal_codeがサポートされます。
ドメインリスト	認証画面のURIがデータを取得するドメインのリスト（任意）です。ログインページが他のドメインからコンテンツを取得する場合は、そのドメインをこのリストに指定します。 認証画面のURI外のドメインの場合にのみ必須です。たとえば、認証画面のURIがhttps://www.ridehailer.com/loginだとします。ページがwww.ridehailer.com外のドメインから画像などのコンテンツを取得する場合、これらをドメインリストに追加する必要があります。最大30個まで指定できます。
デフォルトのアクセストークンの有効期限	アクセストークンの有効期間を秒単位で指定します。OAuthクライアントがexpires_inを返さない場合にこの値を使用します。OAuthクライアントがexpires_inを返す場合は、OAuthクライアントによって指定された値が使用されます。
Alexaのリダイレクト先のURL	ユーザー認証後にユーザーをリダイレクトするAmazon提供のリダイレクト先のエンドポイントが表示されます。リクエストに使用する値は、認証画面のURIに含まれるredirect_uriパラメーターとしてログインページに渡されます。リダイレクト先のエンドポイントを参照してください。

Alexaのリダイレクト先のURL

Alexaが使用するリダイレクト先のエンドポイントは、開発者コンソールのビルド＞アカウントリンクページのAlexaのリダイレクト先のURLフィールドに表示されます。このエンドポイントは、ユーザー認証後にログインページからユーザーをリダイレクトする必要があるURLです。

Alexaのリダイレクト先のURLには、複数のURIが表示されます。Alexaアプリは認証画面のURIに、ユーザーがデバイスを登録した場所に応じて使用する値を渡します。URIは、redirect_uriパラメーターとして認証画面のURIに渡されます。

たとえば、Authorization code grantのredirect_uriパラメーターに渡される値はこのようになります。

認証画面のURIの要件で述べたとおり、認証画面のURIはユーザーをredirect_uriにリダイレクトし、URLクエリー文字列にstateとcodeを含めます。例：

アカウントリンクフローのテスト

アカウントリンクの設定を完了すると、アカウントリンクフローをテストできます。Alexaアプリでスキルを有効にし、アカウントリンクプロセスを開始します。サービスにログインしてAlexaアプリに戻ることを確認します。

アカウントリンクの実装を終了するには、受信するリクエストにアクセストークンがあるかどうかを確認して適切なアクションを実行するよう、スキルコードを更新する必要があります。詳細については、以下を参照してください。

• カスタムスキル： カスタムスキルコードでアクセストークンを検証して使用する
• スマートホームスキルとその他のドメイン： スマートホーム、ビデオ、会議スキルでアクセストークンを検証して使用する

関連トピック

• アカウントリンクの構成要素
• クイックリファレンス： Alexaスキルにアカウントリンクを追加する
• OAuth 2.0認可フレームワーク（RFC 6749）
• OAuth.com

---

---

最終更新日: 2023 年 05 月 16 日