grantsをサポートしています。このGrant種別では、ユーザーのサービス認証後、認可サーバーが認可コード(code)を提供します。Alexaはこのcodeを使ってアクセストークンと更新トークンのペアを認可サーバーにリクエストします。Alexaは、古いトークンの期限が切れたら更新トークンを使って新しいアクセストークンをリクエストできます。Grantフローの概要ユーザーがアカウントリンクプロセスを開始します。どこで開始するかはスキルの種類によって異なります。カスタムモデルを使用するスキルの場合、カスタムスキルのアカウントリンクを参照してください。スマートホームやビデオ、会議、音楽などプリビルドモデルを使用するスキルの場合、スマートホームなどのドメインのアカウントリンクを参照してください。Alexaアプリでは、アカウントリンクを設定する際に指定した認証画面のURIを使用してアプリにログインページを表示します。このログインページでは認可サーバーを使用してユーザーの認証を行います。Alexaアプリが指定した認証画面のURIを呼び出すと、このURIにはクエリー文字列のパラメーターとしてstate、client_id、response_type、scope、redirect_uriが含まれます。ユーザーは認可サーバーの認証情報を使ってログインします。ユーザーが認証されると、認可サーバーが認可コード(code)を生成します。認可サーバーによりユーザーはAmazonが提供するredirect_uriにリダイレクトされます。その際、URLのクエリ文字列パラメーターでstateとcodeが渡されます。Alexaサービスは、codeを使って認可サーバーのアクセストークンURIからアクセストークンと更新トークンのペアをリクエストします。認可サーバーは4.5秒以内にトークンリクエストに応答する必要がありますのでご注意ください。Alexaはアクセストークンと更新トークンを保存します。ユーザーのAlexaアカウントは他のサービスのアカウントにリンクされ、スキルが使用できるようになりました。以降、ユーザーがスキルに対してリクエストを行うとき、各リクエスト(カスタムスキルのIntentRequestやスマートホームスキルのTurnOnディレクティブなど)にはアクセストークン(access_token)が含まれます。スキルはこのトークンを使ってリソースサーバーから必要な情報を取得します。access_tokenの期限が切れると、Alexaは更新トークンを使ってアクセストークンURIを再度呼び出し、新しいアクセストークンと更新トークンのペアをリクエストします。以下の図は、ユーザーがアカウントをリンクしてAlexaが認可サーバーからアクセストークンを取得するときの最初のセットアップを表しています。grantフローこの図では、ユーザーがスキルに対してリクエストを行い、スキルがアクセストークンを使ってリソースサーバーから情報を取得するフローを表しています。grantを使用したアカウントリンクの要件を満たす認可サーバーがあることを確認します。認可サーバーは必須パラメーターを受け入れ、ユーザーを認証し、認可codeを生成してAmazonが提供するredirect_uriにユーザーをリダイレクトできる必要があります。アクセストークンURIはクライアントの認証情報と認可codeを受け入れ、ユーザーのaccess_token(および将来新しいaccess_tokenを取得するために使用できるrefresh_token)を返す必要があります。詳細については、認証画面のURIを参照してください。grant用にスキルを設定します。詳細については、開発者ポータルでアカウントリンクを設定するを参照してください。grantを設定したら、次の手順に進み、スキルコードにアクセストークンを検証して使用する処理を追加します。関連トピック:カスタムスキルコードでアクセストークンを検証して使用するスマートホームとビデオのスキルコードでアクセストークンを検証して使用する認証画面のURIユーザーがアカウントリンクのプロセスを開始すると、Alexaアプリに認可サーバーのログインページが表示されます。認可サーバーは、ユーザーの認証情報を検証してcodeを返す必要があります。Alexaはこのコードを使ってアクセストークンと交換します。アカウントリンクページにこのログインページのURLを指定します。ログインページのURLは、認証画面のURIフィールドに入力します。codeをアクセストークンと交換するサーバーのURIは、アクセストークンのURIフィールドに指定します。サードパーティOAuthプロバイダーの認証画面のURIサードパーティOAuthプロバイダーを使用する場合、そのプロバイダーのドキュメントを確認してアカウントリンクの設定に必要な認証画面のURIを決めてください。認可リクエストとアクセストークンリクエストのURIを検索します。認証画面のURIを呼び出す場合、AlexaアプリではURLのクエリー文字列に以下のパラメーターを含みます。説明client_idスキルのIDです。このIDを使って、アカウントリンクを使うよう設定した他のスキルと区別するなど、スキル固有の機能を提供できます。client_idは、スキルのアカウントリンクを設定する際に定義します。redirect_uriサービスが認証したユーザーをリダイレクトする、Amazon固有のリダイレクト先のエンドポイント(リダイレクト先のURL)です。このパラメーターで想定される値は、開発者コンソールでスキルのアカウントリンクを設定する際にも表示されます。response_type他のサービスによってユーザーが認証された後に返される応答の種類を表します。grantの場合は常にcodeです。scopeAlexaユーザーが必要とするアクセスを表すスコープのリスト(任意)です。これらのスコープは、スキルのアカウントリンクを設定する際に定義します。サービスはアクセストークンを生成するときにこの情報を使用します。リソースサーバーの基本のプロファイル情報へのアクセスは許可するが支払い情報へのアクセスは認めないトークンを、サービスが作成する場合などです。スコープは複数使用できます。リストは、URLエンコードされたスペースで区切ります。ログインページでは、ユーザーにアカウントリンクによってどのようなアクセスが付与されるかを伝える必要があります。ログインページには「アカウントリンクを行うと、タクシー予約スキルがあなたに代わってタクシーの配車を依頼し、料金をあなたの口座に請求できるようになります。」などのテキストを表示できます。スマートホームスキルの場合、このページには「アカウントリンクを行うと、マイライトスキルでマイライトハブに接続された照明を制御できるようになります。」などと表示できます。stateアカウントリンクを使用してユーザーをトラッキングするために、Alexaサービスが内部的に使用する値です。認証画面のURIは、リダイレクト先のURLが呼び出された場合にこの値を変更せずに戻す必要があります。ページの認証画面のURIがhttps://www.carfu.com/loginの場合、Alexaアプリによって呼び出されるURLは以下のようになります。https://www.carfu.com/login?state=abc&client_id=unique-id&scope=order_car%20basic_profile&response_type=code&redirect_uri=https%3A//pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAAユーザーの言語でのログインページの作成Alexaアプリは、ユーザーが使用するブラウザがサポートされている言語のいずれかで設定されている場合、ブラウザの言語設定を使用してアプリを表示しようとします。これ以外の言語の場合、アプリはデフォルトでen-usになります。ユーザーエクスペリエンスに一貫性を持たせるには、ログインページもAlexaアプリと同じ言語で表示するようにしてください。言語の情報を取得するには、まずAccept-Languageヘッダーを確認します。Alexaアプリは認証画面のURIを呼び出すとき、このヘッダーを設定しようとします。ヘッダーが設定されていない場合、navigator.languageまたはnavigator.browserLanguageを確認してユーザーのブラウザで定義されている言語を使用できます。Navigator言語プロパティを参照してください。ユーザーのブラウザ設定は、ユーザーのAlexa搭載デバイスで定義されている言語とは関係ありません。ユーザーは、デバイスで日本語を使うよう設定し、ブラウザを英語(英国)で使うよう設定することができます。この場合、Alexaアプリは日本語で表示され、Accept-Languageヘッダーは英語(en-gb)に設定されます。ユーザーにとって使いやすいログインエクスペリエンスの提供ユーザーがアカウントリンクプロセスを開始すると、Alexaアプリは指定したログインページを表示します。サービスを使っているユーザーだけでなく、Alexaからサービスを見つけ、サービスのアカウントを作成してくれるかもしれないユーザーにとっても、使いやすいエクスペリエンスを提供するようにしてください。以下に、ログインページのベストプラクティスをいくつか紹介します。ログインページのユーザー名やメールアドレスのフィールドでは、オートコレクトや自動で頭文字を大文字にするオプションはオフにし、入力エラーが少なくなるようにします。フォームのフィールド検証を使い、末尾のスペースや大文字小文字の誤りといったよくあるエラーを検知できるようにします。郵便番号や電話番号などのフィールドでは、スキルを利用できる地域ごとに適切な検証処理を適用するようにします。ページでは、入力可能なユーザー認証情報について指示します。ユーザーがAmazonアカウントではなくサービスの認証情報でログインする必要がある点を明確に説明します。サードパーティの認証サーバーを使用する場合は、そのサーバーの認証情報でログインする必要がある点をはっきりと伝えます。サービスのウェブサイトやモバイルアプリでFacebook、Amazon、Googleなど複数のサインインメカニズムをサポートしている場合、ログインページでも同じメカニズムをサポートするようにします。サポートしない場合、サービスを使用するユーザーがアカウントをリンクできません。サービスのウェブサイトやモバイルアプリで新しいアカウントの作成をサポートし、このフローのサポートとテストも行えるようにします。ユーザーは新しいアカウントの作成とリンクをシームレスに行う必要があるため、ユーザーがAlexaを使用して初めてサービスを見つけた場合も考慮します。アカウント名やパスワードを忘れてしまったユーザーのために、アカウントの復旧オプションをサポートします。以上すべてのシナリオを使ってアカウントリンクをテストし、ユーザーに使いやすいページになっているかどうかを確認します。ユーザーがログインできない場合に表示されるエラーメッセージが、問題を明確に伝えていることを確認します。Alexaスキルにアカウントリンクを追加する10のヒント(英語)も参照してください。認証画面のURIは、以下の要件を満たす必要があります。HTTPS経由で提供される必要があります。Alexaアプリで表示されるため、モバイルでも見やすいログインページにする必要があります。このページをポップアップウィンドウで開いたり、JavaScriptのアラートやメッセージボックスを起動することはできません。ユーザーにエラーが発生した場合(ユーザーが誤ったユーザー名やメールアドレス、パスワードを入力した場合など)、エラーは同じログインページにインラインで表示される必要があります。ユーザーの認証情報を受け取り、認可サーバーを使用してユーザーを認証する必要があります。認可サーバーに渡す認可codeを生成してリソースサーバーでユーザーを一意に識別するアクセストークンを取得する必要があります。クエリ文字列で渡されるstate値をトラッキングする必要があります。ユーザー認証後、ページはAmazonが提供するリダイレクト先のエンドポイント(リダイレクト先のURL)にユーザーをリダイレクトする必要があります。使用するURLは、redirect_uriパラメーターとして認可リクエストに含まれます。スキルのアカウントリンクを設定する際、開発者コンソールにはその他のURLも表示されるため、ログインページがredirect_uriパラメーターとして受け取る可能性のある値を確認できます。URLのクエリー文字列にstateとcodeを含めます。Amazon(LWA)を使用するか、Amazon認定の認証局によって署名された証明書を持つプロバイダーを使用することができます。このリストに記載されていても、https://letsencrypt.org/を使用することはできませんのでご注意ください。Amazonが提供するリダイレクト先のURLが以下だったとします。https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAAユーザーの認証画面のURIは、ユーザーを以下にリダイレクトします。https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA?state=xyz&code=SplxlOBeZQQYbYS6WxSbIAパラメーターはURLクエリー文字列で渡されます。アクセストークンと更新トークン認可サーバーはユーザーを一意に識別するアクセストークンを提供する必要があります。スキルはこのトークンを使ってリソースサーバーのユーザーに関する情報にアクセスできます。Alexaサービスは認可サーバーのアクセストークンエンドポイント(開発者コンソールでアクセストークンのURIとして指定)を呼び出して、codeとクライアント認証情報を渡します。認可サーバーはアクセストークンと任意の更新トークンを返す必要があります。更新トークンは任意ですが、アクセストークンに期限がある場合に使うことをお勧めします。以下に注意してください。認可サーバーは4.5秒以内にトークンリクエストに応答する必要があります。Alexaサービスは古いアクセストークンの期限が切れると、更新トークンを使って新しいアクセストークンを取得できます。エンドユーザーの操作は必要ありません。新しいアクセストークンが発行されたときに、認可サーバーで前回のアクセストークンをすぐに無効にしないでください。分散されたシステムが同時に動作するAlexaのようなサービスでは、サービスを使用できなくなる可能性があります。認可サーバーで、アクセストークン応答のexpires_inパラメーターで指定された有効期限の前にAlexaサービスに渡されたアクセストークンの無効化や取り消しをしないようにしてください。インテントがアクセスの停止である場合を除きます。渡されたアクセストークンがすでに無効であることをAlexaに通知するメカニズムはありません。アクセストークンの有効期限は6分以上にしてください。アクセストークン応答のexpires_inパラメーターを360以上に設定する必要があります。新しい更新トークンが使用後に生成されたとき、認可サーバーで前回の更新トークンをすぐに無効にしないでください。アカウントリンクする以外になくなってしまう可能性もあるためです。対処法としては、無期限の更新トークンを持つか、有効期限がある場合にはX世代前までの古い更新トークンを有効にしておき、認可サーバーが最新の更新トークンを受け取ったことを確認してそのトークンを新しいアクセストークン取得に使った場合にのみ無効にするかのいずれかがあります。Alexaが更新トークンを使って既存ユーザーの新しいアクセストークンを取得する場合、Alexaはユーザーがアカウントリンク時に設定したアクセストークンURIを使用します。後でアクセストークンURIを変更した場合でも、以前にアカウントリンクを完了したユーザーが更新されたトークンを取得するには古いURIを引き続き使用します。新しいアクセストークンURIに切り替えるには、ユーザーがアカウントのリンクを解除して、リンクし直す必要があります。スキルの公開後にOAuthコンフィギュレーションを変更する場合、既存のユーザーが新しいURIに移行するまで古いアクセストークンURIを使えるようにしておく必要があります。アクセストークンを生成する場合、リソースサーバー固有のトークンを提供します。セキュリティを確保するため、トークンはユーザーを識別でき、推測できない値にしてください。開発者コンソールのビルド>アカウントリンクでアカウントリンクを有効にします。CLIまたはスキル管理APIを使ってアカウントリンクを設定することもできます。カスタムスキルの場合、アカウントリンクは任意です。アカウントリンクを使用するカスタムスキルが認定、公開されたら、そのスキルのアカウントリンクを無効にすることはできません。以下の表は、アカウントリンク設定で入力の必要なフィールドです。サードパーティOAuthプロバイダーを使用する場合、そのプロバイダーのドキュメントを確認してフィールドに入力する値を判断してください。フィールド説明ユーザーがアカウントや既存アカウントへのリンクを作成することを許可しますか?カスタムスキルでアカウントリンクを有効にする場合に選択します。このオプションはスマートホームスキルとビデオスキルでは自動で選択されます。アカウントリンクなしでスキルを有効にすることをユーザーに許可します。ユーザーがスキルを有効にする際にアカウントリンクフローを行わない場合は、これを選択します。カスタムスキルでのみ使用できます。スキルが、アカウントを必要とする機能にだけでなく、アカウントリンクが不要な便利な機能がある場合に使用します。ユーザーがアカウントをリンクせずにスキルを有効にするを参照してください。このオプションはデフォルトではオンです。Grantを選択します。スマートホームスキルとビデオスキルの場合、このGrant種別しかサポートされないため自動で選択されます。認証画面のURIユーザーがサービスへのログインに使用できるページのURIです。ユーザーがアカウントリンクプロセスを開始すると、Alexaアプリはこのページを表示します。詳細と要件については認証画面のURIを参照してください。サードパーティのOAuthプロバイダーを使用している場合、認可リクエスト用に提供されているURIをご確認ください。Amazonの場合、認証画面のURIはhttps://www.amazon.com/ap/oaです。アクセストークンのURI認可サーバーのアクセストークンエンドポイントのURIです。AlexaサービスはこのURIを呼び出して認可コードをアクセストークンと交換します。前回のトークンの有効期限が切れると、Alexaは更新トークンを使ってこのURIを呼び出し、新しいアクセストークンを取得します。サードパーティのOAuthプロバイダーをお使いの場合、アクセストークンリクエスト用に提供されているURIをご確認ください。Amazonの場合、アクセストークンリクエストのURIはhttps://api.amazon.com/auth/o2/tokenです。トークンの要件と詳細については、アクセストークンと更新トークンを参照してください。ユーザーのクライアントID認証をリクエストするユーザーを識別する一意の文字列です。この値は、client_idパラメーターとして認証画面のURIに渡されます。このクライアントIDも、アクセストークンURIからアクセストークンをリクエストするときにAlexaサービスが含めるクライアント認証情報の一部です。サードパーティOAuthプロバイダーを使用している場合、プロバイダーが想定しているクライアントIDを確認してください。Amazonのセキュリティプロファイルを作成するときに作成されます。ユーザーのシークレットアクセストークンURIを使ってAlexaサービスの認証を行うための認証情報です。ユーザーのクライアントIDと組み合わせて、Alexaからのリクエストを識別するのに使用されます。サードパーティOAuthプロバイダーを使用している場合、プロバイダーが想定しているクライアントIDを確認してください。Amazonのセキュリティプロファイルを作成するときに作成されます。ユーザーの認可スキームアクセストークンURIからトークンをリクエストするときにAlexaが使用する認証の種類を指定します。ユーザーのリダイレクト先のURL開発者アプリをポイントし、アプリ間アカウントリンクの実装のみに使用されます。Scope他のサービスの権限のリスト(任意)です。リソースサーバーがさまざまなアクセススコープをサポートする場合、それらのスコープをここで指定します。最大15個まで指定できます。ここで指定するすべてのスコープは、Alexaアプリが認証画面のURIを呼び出す際のscopeパラメーターに含まれます(URLエンコードされたスペースで区切る)。サードパーティのOAuthプロバイダーを使用している場合、プロバイダーがサポートするスコープのセットから指定してください。Amazonの場合、profile、profile:user_id、postal_codeがサポートされます。ドメインリスト認証画面のURIがデータを取得するドメインのリスト(任意)です。ログインページが他のドメインからコンテンツを取得する場合は、そのドメインをこのリストに指定します。認証画面のURI外のドメインの場合にのみ必須です。認証画面のURIがhttps://www.carfu.com/loginだとします。ページがwww.carfu.com外のドメインから画像などのコンテンツを取得する場合、これらをドメインリストに追加する必要があります。最大30個まで指定できます。デフォルトのアクセストークンの有効期限アクセストークンの有効期間を秒単位で指定します。OAuthクライアントがexpires_inを返さない場合にこの値を使用します。OAuthクライアントがexpires_inを返す場合は、OAuthクライアントによって指定された値が使用されます。Alexaのリダイレクト先のURLユーザー認証後にユーザーをリダイレクトするAmazon提供のリダイレクト先のエンドポイントが表示されます。リクエストに使用する値は、認証画面のURIに含まれるredirect_uriパラメーターとしてログインページに渡されます。リダイレクト先のエンドポイントを参照してください。Alexaのリダイレクト先のURLAlexaが使用するリダイレクト先のエンドポイントは、開発者コンソールのビルド>アカウントリンクページのAlexaのリダイレクト先のURLフィールドに表示されます。このエンドポイントはユーザー認証後にログインページがユーザーをリダイレクトする必要のあるURLです。Alexaのリダイレクト先のURLには、複数のURIが表示されます。Alexaアプリは認証画面のURIに、ユーザーがデバイスを登録した場所に応じて使用する値を渡します。URIは、redirect_uriパラメーターとして認証画面のURIに渡されます。リダイレクト先のエンドポイントを認可サーバーのホワイトリストに登録するリダイレクト先のエンドポイントは通常、特に認可サーバーを所有していない場合でも認証画面のURIから呼び出すことができるように認可サーバーのホワイトリストに登録する必要があります。スキルが複数の地域で機能するよう、ユーザーのリダイレクト先のURLに表示されるすべてのURIをホワイトリストに登録してください。ホワイトリストへの登録方法は、使用する認可サーバーによって異なります。Amazonでは、セキュリティを設定して利用可能なリダイレクト先URLをリダイレクトURLフィールドに指定する必要があります。これらの要件については、OAuthプロバイダーのドキュメントを参照してください。grantのredirect_uriパラメーターに渡される値はこのようになります。https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA認証画面のURIの要件で述べたとおり、認証画面のURIはユーザーをredirect_uriにリダイレクトし、URLクエリー文字列にstateとcodeを含めます。複数の地域にスキルを配信する場合、スキルは地域固有のリダイレクト先のURLを使用する必要があります。使用するURLは、redirect_uriパラメーターとしてログインページの呼び出しに含まれます。アカウントリンクフローのテストアカウントリンクの設定を完了すると、アカウントリンクフローをテストできます。Alexaアプリでスキルを有効にし、アカウントリンクプロセスを開始します。サービスにログインしてAlexaアプリに戻ることを確認します。アカウントリンクの実装を終了するには、受信するリクエストにアクセストークンがあるかどうかを確認して適切なアクションを実行するよう、スキルコードを更新する必要があります。詳細については、以下を参照してください。