Authorization code grantを設定する
Alexa Skills Kitは、カスタムスキル、スマートホームスキル、ビデオスキル、会議スキル、音楽スキルでのアカウントリンクでAuthorization code grantをサポートしています。
このGrant種別では、ユーザーがサービスに対して認証された後、認可サーバーが認可コードを付与します。Alexaは、このコード（code）を使って認可サーバーにアクセストークンと更新トークンのペアをリクエストします。古いアクセストークンの期限が切れると、Alexaは更新トークンを使って新しいアクセストークンをリクエストします。
Authorization code grantフローの概要
Alexaは、OAuth 2.0のアカウントリンクフローとAuthorization code grantを使用して、ユーザーのAmazonアカウントをシステムのアカウントにリンクします。このフローは、従来のアカウントリンクとアプリ間アカウントリンク（Alexaアプリから開始する場合）のどちらでも同じです。従来のアカウントリンクでは、Alexaは設定されたURIを使用してウェブサイトのログインページを開きます。アプリ間アカウントリンクでは、Alexaは設定されたURIを使用してアプリのログインページを開きます。アプリがデバイスにインストールされていない場合、フォールバックとしてWebサイトのURIが使用されます。
アカウントをリンクする
ユーザーアカウントをリンクするAuthorization code grantフローの手順は以下のとおりです。
- ユーザーがAlexaアプリでスキルを有効にして、アカウントリンクプロセスを開始します。どこで開始するかはスキルの種類によって異なります。
- カスタムスキルの場合、カスタムスキルのアカウントリンクを参照してください。
- スマートホームやビデオ、会議、音楽などのスキルの場合、スマートホームなどのドメインのアカウントリンクを参照してください。
- AlexaアプリがAlexaサービスに認証画面のURLをリクエストします。
- Alexaサービスがアカウントリンクの設定時に指定した認証画面のURIにリクエストを送信し、その際
state、client_id、response_type、scope、redirect_uriをクエリ文字列のパラメーターとして渡します。 - 認可サーバーが認証画面のURLを返します。
- Alexaアプリが、ユーザーが認可サーバーに対して認証するためのログインページを表示します。
ウェブサイトURLの場合、Alexaはアプリ内ブラウザでログインページを開きます。
アプリ間アカウントリンクの場合、Alexaはアプリにディープリンクして該当する画面を表示します。 - ユーザーが認可サーバーの認証情報でログインします。
- 認可サーバーがユーザーを認証し、認可コード（
code）を生成します。 - 認可サーバーが手順4の
redirect_uriにユーザーをリダイレクトし、その際にstateとcodeをURLのクエリ文字列パラメーターとして渡します - Alexaサービスが、認可サーバー上に設定されたアクセストークンURIからアクセストークンと更新トークンのペアを取得するために、
codeとcode_verifierをPOSTリクエストで送信します。重要： 認可サーバーは4.5秒以内にトークンリクエストに応答する必要があります。 - サーバーが認可コードを検証し、アクセストークンと更新トークンを発行します。
- Alexaはアクセストークンと更新トークンを保存します。
ユーザーのAlexaアカウントは他のサービスのアカウントにリンクされ、スキルが使用できるようになりました。
以下の図は、ユーザーがAlexaアプリからアカウントをリンクした場合のアカウントリンクフローを示しています。Alexaは、上記の手順に沿って認可サーバーからアクセストークンを取得します。
スキルでアクセストークンを使用する
以降、ユーザーがスキルにリクエストを送信する際、各リクエスト（カスタムスキルのIntentRequestやスマートホームスキルのTurnOnディレクティブなど）にはアクセストークン（access_token）が含まれます。スキルはこのトークンを使ってリソースサーバーから必要な情報を取得します。アクセストークンの有効期限が切れると、Alexaは更新トークンを使ってアクセストークンURIを再度呼び出し、新しいアクセストークンと更新トークンのペアをリクエストします。
以下の図は、アクセストークンを使用してリソースサーバーから情報を取得する場合のスキルとのやり取り（対話）を示しています。
認証画面のURI
認証画面のURLはAlexa開発者コンソールのビルド＞アカウントリンクページで設定し、認証画面のURIフィールドにURLを入力します。Alexaサービスは、URLのクエリ文字列を使用して認可サーバーにパラメーターを渡します。たとえば認証画面のURIがhttps://www.ridehailer.com/loginの場合、Alexaは次のパラメーターを送信します。
https://www.ridehailer.com/login?state=abc&client_id=unique-id&scope=order_car+basic_profile&response_type=code&redirect_uri=https%3A//pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA
Alexaサービスは、認証画面のURIを開く際のクエリ文字列に以下のパラメーターを含めます。
| パラメーター | 説明 |
|---|---|
|
|
スキルのIDです。この値を使って、アカウントリンクを設定した複数のスキルを識別するなど、スキル固有の機能を提供できます。 |
|
|
サービスが認証したユーザーをリダイレクトする、Amazon固有のリダイレクト先のエンドポイント（リダイレクト先のURL）です。このパラメーターの値の候補は、開発者コンソールでスキルのアカウントリンクを設定する際にも表示されます。 |
|
|
認可サーバーによってユーザーが認証された場合に返す応答の種類です。Authorization code grantの場合、 |
|
|
Alexaユーザーが必要とするアクセスを表すスコープのリスト（任意）です。これらのスコープは、スキルのアカウントリンクを設定する際に定義します。
|
|
|
アカウントリンクを使用してユーザーをトラッキングするために、Alexaサービスが内部的に使用する値です。 Alexaサービスは、認証画面のURIを介して認可サーバーに |
Alexaのリダイレクト先URL
Alexaアプリが使用するリダイレクト先のエンドポイントは、開発者コンソールのビルド＞アカウントリンクページのAlexaのリダイレクト先のURLフィールドに表示されます。これらのエンドポイントは、ユーザーの認証後、ログインページからユーザーをリダイレクトする必要があるURLです。リストには、Alexaリージョンごとに1つ、複数のURLが表示されます。
Alexaアプリは、ユーザーがデバイスを登録した場所に基づいてリダイレクト先のURLを選択し、URLクエリ文字列のredirect_uriクエリパラメーターに認証画面のURIを指定して渡します。認証後、認可サーバーはredirect_uriを使用してユーザーをAlexaアプリに戻す必要があります。
たとえば、redirect_uriパラメーターがhttps://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAAの場合、ユーザーはログインページから以下のURLにリダイレクトされます。その後、認可サーバーはクエリ文字列にこのstateパラメーターとcodeパラメーターを指定して渡します。
https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA?state=xyz&code=SplxlOBeZQQYbYS6WxSbIA
通常、リダイレクト先のエンドポイントは、特に認可サーバーを所有していない場合でも認証画面のURIから呼び出すことができるよう、認可サーバーに登録します。スキルが複数のリージョンで機能するよう、ユーザーのリダイレクト先のURLに表示されるすべてのURIを登録してください。
登録方法は使用する認可サーバーによって異なります。たとえばLogin with Amazonでは、セキュリティプロファイルを設定してAllowed Return URLsフィールドに利用可能なリダイレクト先URLを指定する必要があります。
サーバーの要件については、OAuthプロバイダーのドキュメントを参照してください。
アクセストークンと更新トークンの詳細
Alexa開発者コンソールで認可サーバーのアクセストークンエンドポイントを設定するには、ビルド＞アカウントリンクページのアクセストークンのURIフィールドに適切なURLを入力します。
ユーザーがアカウントをリンクすると、Alexaサービスは認可コードとクライアント認証情報を含むPOSTリクエストをトークンURIに送信します。その後、認可サーバーは、ユーザーを一意に識別するアクセストークンを生成して返す必要があります。このトークンはリソースサーバーに固有で、セキュリティを考慮して作成されている必要があります。具体的には、ユーザーを識別する一方で、推測不可能である必要があります。更新トークンはオプションですが、アクセストークンの有効期限が切れた場合にユーザーが再認証せずにアクセスを継続できるよう、認可サーバーから更新トークンを返すことを推奨します。アクセストークンと更新トークンの要件については、アクセストークンのURI要件を参照してください。
次のコードは、Alexaからのアクセストークンリクエストの例です。
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=123456EXAMPLE
&client_id=exampleId
&client_secret=ABCDEFGEXAMPLE
&code_verifier=AB12CVEXAMPLE
&redirect_uri=https%3A//pitangui.amazon.com/api/skill/link/M3PCA6K3O9X0NW
アクセストークンと更新トークンの生成に成功すると、認可サーバーは次のような応答を送信します。
HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"Atza|EXAMPLEACCESSTOKEN123456...",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"Atzr|EXAMPLEREFRESHTOKEN123456X..."
}
前提条件
Alexaスキルにおけるアカウントリンクの要件に記載されている要件を満たす認可サーバーがあることを確認します。
Authorization code grantの設定手順
スキルにアカウントリンクを設定するには、以下の手順を実行します。
- Alexa開発者ポータルでAuthorization code grant用にスキルを設定します。詳細については、Alexa開発者ポータルでアカウントリンクを設定する手順を参照してください。
- アクセストークンを検証して使用するための処理をスキルコードに追加します。
- アカウントリンクフローをテストします。
ステップ1： アカウントリンクの設定
アカウントリンクは、Alexa開発者コンソールのビルド＞アカウントリンクページで有効にすることができます。また、ASK CLIまたはアカウントリンクREST APIで設定することもできます。
アカウントリンク設定
設定で、スキルで使用できるアカウントリンクオプションを有効または無効にします。次のセクションのセキュリティプロバイダーオプションは、ここで有効にした設定に応じて表示されます。
以下の表は、アカウントリンクの設定に必要なフィールドの一覧です。
| フィールド | 説明 |
|---|---|
|
ユーザーがアカウントや既存アカウントへのリンクを作成することを許可しますか？ |
カスタムスキルでアカウントリンクを有効にする場合、このオプションをオンにします。 スマートホームスキルとビデオスキルでは自動で選択されます。 |
|
アカウントリンクなしでスキルを有効にすることをユーザーに許可します（推奨） |
ユーザーがアカウントをリンクせずにスキルを有効にできるようにする場合、このオプションをオンにします。カスタムスキルでのみ選択できます。アカウントを必要とする機能だけでなくアカウントを必要としない機能も提供するスキルで役に立つオプションです。詳細については、ユーザーがアカウントをリンクせずにスキルを有効にするを参照してください。 このオプションはデフォルトではオンです。 |
|
ユーザーがユーザーアプリケーションやウェブサイトからアカウントをリンクできるようにします |
ユーザーがウェブサイトを使用して認証できるようにする場合、このオプションをオンにします。 |
|
モバイルアプリでのユーザー認証を可能にします |
アプリ間アカウントリンクを有効にして、ユーザーがモバイルアプリを使用して認証できるようにする場合、このオプションをオンにします。 |
|
ユーザーが音声を使用して自分のアカウントをスキルにリンクすることを許可する |
ユーザーが音声でAmazonアカウントをサービスのアカウントとリンクできるようにする場合、このオプションをオンにします。 |
セキュリティプロバイダー情報
セキュリティプロバイダー情報で、Authorization grant種別を選択し、以下に記載するセキュリティプロバイダー情報を設定します。ここに表示されるオプションは、設定セクションで有効にしたオプションによって変わります。サードパーティOAuthプロバイダーを使用する場合、そのプロバイダーのドキュメントを確認してフィールドに入力する値を判断してください。
| フィールド | 説明 |
|---|---|
|
Authorization Grant種別を選択 |
アクセストークン取得に使用するOAuth 2.0のAuthorization Grant種別です。Auth Code Grantを選択します。スマートホームスキルとビデオスキルの場合、このGrant種別しかサポートされないため自動で選択されます。 |
|
Web認証画面のURI |
ユーザーがサービスにログインできるよう、ウェブページに認証画面を開くためのURI。ユーザーがアカウントリンクプロセスを開始すると、Alexaアプリはこのページを表示します。詳細については、認証画面のURIを参照してください。 サードパーティのOAuthプロバイダーを使用している場合は、認可リクエスト用に提供されているURIを確認してください。たとえばLogin with Amazon（LWA）の場合、認証画面のURIは |
|
iOSアプリの認証URI |
ユーザーがサービスにログインするための認証ページをiOSモバイルアプリで開くためのユニバーサルリンク。ユーザーがiOSモバイルアプリからアカウントリンクプロセスを開始すると、Alexaアプリはこのリンクを開きます。詳細については、認証画面のURIを参照してください。 |
|
Androidアプリの認証URI |
ユーザーがサービスにログインするための認証ページをAndroidモバイルアプリで開くためのアプリリンク。ユーザーがAndroidモバイルアプリからアカウントリンクプロセスを開始すると、Alexaアプリはこのリンクを開きます。詳細については、認証画面のURIを参照してください。 |
|
アクセストークンのURI |
認可サーバー上のアクセストークンエンドポイントのURI。 AlexaサービスはこのURIを呼び出して、認可コードをアクセストークンと交換します。アクセストークンの有効期限が切れると、AlexaはこのURIを呼び出して、更新トークンを新しいアクセストークンと交換します。 サードパーティのOAuthプロバイダーをお使いの場合、アクセストークンリクエスト用に提供されているURIをご確認ください。たとえばLogin with Amazonの場合、アクセストークンリクエストのURIは トークンの要件と詳細については、アクセストークンと更新トークンを参照してください。 |
|
ユーザーのクライアントID |
認証をリクエストするユーザーを識別する一意の文字列です。この値は、 このクライアント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を呼び出す際の サードパーティのOAuthプロバイダーを使用している場合、プロバイダーがサポートするスコープのセットから指定してください。たとえばLogin with Amazonの場合、 |
|
ドメインリスト |
認証画面のURIがデータを取得するドメインのリスト（任意）です。ログインページが他のドメインからコンテンツを取得する場合は、そのドメインをこのリストに指定します。 このフィールドは、認証画面のURI以外のドメインを使用する場合にのみ必要です。たとえば、認証画面のURIが |
|
デフォルトのアクセストークンの有効期限 |
アクセストークンの有効期間を秒単位で指定します。OAuthクライアントが |
|
AlexaクライアントID |
Alexaスキルの認証情報。 |
|
Alexaクライアントシークレット |
Alexaスキルの認証情報。 |
|
Alexaのリダイレクト先のURL |
サービスでユーザーを認証した後にログインページからユーザーをリダイレクトする、Amazon提供のリダイレクト先エンドポイント。Alexaは、ログインページへのリクエストで使用する値を、認証画面のURIの |
ステップ2： スキルコードでのアクセストークンの使用
Authorization code grantを設定したら、アクセストークンを検証して使用する処理をスキルコードに追加します。スキルはこのこのアクセストークンを使ってリソースサーバーからユーザー情報を取得できます。詳細については、スキルの種類に応じて以下のトピックを参照してください。
ステップ3： アカウントリンクフローのテスト
アカウントリンクの設定を完了すると、アカウントリンクフローをテストできます。Alexaアプリでスキルを有効にし、アカウントリンクプロセスを開始します。サービスにログインしてAlexaアプリに戻ることを確認します。
アカウントリンクの実装を終了するには、受信するリクエストにアクセストークンがあるかどうかを確認して適切なアクションを実行するよう、スキルコードを更新します。また、ユーザーがアカウントリンクを有効にしなかった場合やキャンセルした場合に、応答でアカウントリンクカードを送信するコードも追加します。Alexaアプリに表示された場合、このカードには認証画面のURIへのリンクが表示されます。ユーザーはこのカードから直接アカウントリンクプロセスを開始できます。
詳細については、次のトピックを参照してください。
- カスタムスキル： カスタムスキルコードでアクセストークンを検証して使用する
- スマートホームスキルとその他のドメイン： スマートホーム、ビデオ、会議スキルでアクセストークンを検証して使用する
関連トピック
最終更新日: 2025 年 05 月 27 日