Implicit grantを設定する
Alexa Skills Kitは、カスタムスキルでのアカウントリンクでImplicit grantをサポートしています。このGrant種別は、スマートホームスキルなどその他の種類のスキルには使用できません。
Implicit grantフローの概要
ユーザーはスキルを有効にする時点で、またはAlexaアプリのアカウントリンクカードから、アカウントリンクプロセスを開始できます。ユーザーのアカウントリンク操作の詳細については、カスタムスキルのアカウントリンクを参照してください。
-
Alexaアプリでスキルを有効にする、またはアカウントリンクカードのリンクをタップすると、プロセスが開始されます。
-
Alexaアプリでは、アカウントリンクを設定する際に指定した認証画面のURIを使用してアプリにログインページを表示します。このログインページでは認可サーバーを使用してユーザーの認証を行います。
Alexaアプリが指定した認証画面のURIを呼び出すと、このURIにはクエリー文字列のパラメーターとして
state、client_id、response_type、scope、redirect_uriが含まれます。 - ユーザーは認可サーバーの認証情報を使ってログインします。
- ユーザーが認証されると、認可サーバーはユーザーを一意に識別するアクセストークン（
access_token）を生成します。 - 認可サーバーによりユーザーは指定された
redirect_uriにリダイレクトされます。その際、URLフラグメントでstate、access_token、token_typeが渡されます。 -
AlexaサービスはAlexaユーザーの
access_tokenを保存します。ユーザーのAlexaアカウントはサービスのアカウントにリンクされ、スキルが使用できるようになりました。
- ユーザーがスキルにリクエストを行うとき、スキルに送信されるすべてのリクエスト（
IntentRequestなど）にアクセストークン（access_token）が含まれるようになります。スキルはこのトークンを使ってリソースサーバーから必要な情報を取得します。
以下の図は、ユーザーがアカウントをリンクしてAlexaが認可サーバーからアクセストークンを取得するときの最初のセットアップを表しています。
この図では、ユーザーがスキルに対してリクエストを行い、スキルがアクセストークンを使ってリソースサーバーから情報を取得するフローを表しています。
Implicit grantの設定手順
- Implicit grantを使用したアカウントリンクの要件とアカウントリンクの前提条件を満たす認可サーバーであることを確認してください。
- 開発者ポータルでImplicit grant用にスキルを設定します。詳細については、アカウントリンクの設定を参照してください。
Implicit grantを設定したら、次の手順に進み、スキルコードにアクセストークンを検証して使用する処理を追加します。詳細については、次のページを参照してください。
認証画面のURI
ユーザーがアカウントリンクのプロセスを開始すると、Alexaアプリに認可サーバーのログインページが表示されます。認可サーバーは、ユーザーの認証情報を検証してアクセストークンを返す必要があります。
開発者ポータルのビルド > アカウントリンクページにこのログインページのURLを指定します。ログインページのURLは、認証画面のURIフィールドに入力します。
サードパーティOAuthプロバイダーを使用する場合、そのプロバイダーのドキュメントを確認してアカウントリンクの設定に必要な認証画面のURIを決めてください。認可リクエストのURIを検索します。
認証画面のURIに渡されるパラメーター
認証画面のURIを呼び出す場合、AlexaアプリではURLのクエリー文字列に以下のパラメーターを含みます。
| パラメーター | 説明 |
|---|---|
|
|
スキルのIDです。このIDを使って、アカウントリンクを使うよう設定した他のスキルと区別するなど、スキル固有の機能を提供できます。 |
|
|
サービスが認証したユーザーをリダイレクトする、Amazon固有のリダイレクト先のエンドポイント（リダイレクト先のURL）です。このパラメーターで想定される値は、開発者コンソールでスキルのアカウントリンクを設定する際にも表示されます。 |
|
|
他のサービスによってユーザーが認証された後に返される応答の種類を表します。Implicit grantでは常に |
|
|
Alexaユーザーが必要とするアクセスを表すスコープのリスト（任意）です。これらのスコープは、スキルのアカウントリンクを設定する際に定義します。
|
|
|
アカウントリンクを使用してユーザーをトラッキングするために、Alexaサービスが内部的に使用する値です。 Alexaアプリは、認証URIを介して認証サーバーに |
認証画面のURI要件
アクセストークン
認可サーバーはユーザーを一意に識別するアクセストークンを提供する必要があります。スキルはこのトークンを使ってリソースサーバーのユーザーに関する情報にアクセスできます。
Alexaサービスは認可サーバーのアクセストークンエンドポイント（開発者コンソールでアクセストークンのURIとして指定）を呼び出して、codeとクライアント認証情報をPOSTリクエストで渡します。認可サーバーはアクセストークンと任意の更新トークンをJSON応答で返します。更新トークンは任意ですが、アクセストークンに期限がある場合に使うことをお勧めします。
アクセストークンリクエストの例：
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
アクセストークンレスポンスの例：
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..."
}
アクセストークンと更新トークンの要件についてはアクセストークンのURI要件を参照してください。
アクセストークンを生成する場合、リソースサーバー固有のトークンを提供します。セキュリティを確保するため、トークンはユーザーを識別でき、推測できない値にしてください。
アカウントリンクの設定
開発者コンソールのビルド＞アカウントリンクでアカウントリンクを有効にします。また、ASK CLIまたはスキル管理APIを使ってアカウントリンクを設定することもできます。
以下の表は、アカウントリンク設定で入力の必要なフィールドです。サードパーティOAuthプロバイダーを使用する場合、そのプロバイダーのドキュメントを確認してフィールドに入力する値を判断してください。
| フィールド | 説明 |
|---|---|
|
ユーザーがアカウントや既存アカウントへのリンクを作成することを許可しますか？ |
カスタムスキルでアカウントリンクを有効にする場合に選択します。 このオプションはスマートホームスキルとビデオスキルでは自動で選択されます。 |
|
ユーザーがアカウントリンクなしでスキルを有効にすることを許可してください |
ユーザーがスキルを有効にする際にアカウントリンクフローを行わない場合は、これを選択します。カスタムスキルでのみ使用できます。スキルが、アカウントを必要とする機能にだけでなく、アカウントリンクが不要な便利な機能がある場合に使用します。ユーザーがアカウントをリンクせずにスキルを有効にするを参照してください。 このオプションはデフォルトではオンです。 |
|
Authorization Grant種別を選択 |
アクセストークン取得に使用するOAuth 2.0のAuthorization Grantです。Implicit Grantを選択します。 |
|
認証画面のURI |
ユーザーがサービスへのログインに使用できるページのURIです。ユーザーがアカウントリンクプロセスを開始すると、Alexaアプリはこのページを表示します。詳細と要件については認証画面のURIを参照してください。 サードパーティのOAuthプロバイダーを使用している場合、認可リクエスト用に提供されているURIをご確認ください。たとえばLogin with Amazonの場合、認証画面のURIは |
|
ユーザーのクライアントID |
認証をリクエストするユーザーを識別する一意の文字列です。この値は、 サードパーティOAuthプロバイダーを使用している場合、プロバイダーが想定しているクライアントIDを確認してください。たとえばLogin with Amazonの場合、このIDはLogin with Amazonのセキュリティプロファイルを作成するときに作成されます。 |
|
Scope |
他のサービスの権限のリスト（任意）です。リソースサーバーがさまざまなアクセススコープをサポートする場合、それらのスコープをここで指定します。最大15個まで指定できます。 ここで指定するすべてのスコープは、Alexaアプリが認証画面のURIを呼び出す際の サードパーティのOAuthプロバイダーを使用している場合、プロバイダーがサポートするスコープのセットから指定してください。たとえばLogin with Amazonの場合、 |
|
ドメインリスト |
認証画面のURIがデータを取得するドメインのリスト（任意）です。ログインページが他のドメインからコンテンツを取得する場合は、そのドメインをこのリストに指定します。 認証画面のURI外のドメインの場合にのみ必須です。たとえば、認証画面のURIが |
|
Alexaのリダイレクト先のURL |
ユーザー認証後にユーザーをリダイレクトするAmazon提供のリダイレクト先のエンドポイントが表示されます。リクエストに使用する値は、認証画面のURIに含まれる |
Alexaのリダイレクト先のURL
Alexaが使用するリダイレクト先のエンドポイントは、開発者コンソールのビルド＞アカウントリンクページのAlexaのリダイレクト先のURLフィールドに表示されます。このエンドポイントはユーザー認証後にログインページがユーザーをリダイレクトする必要のあるURLです。
Alexaのリダイレクト先のURLには、複数のURIが表示されます。Alexaアプリは認証画面のURIに、ユーザーがデバイスを登録した場所に応じて使用する値を渡します。URIは、redirect_uriパラメーターとして認証画面のURIに渡されます。
リダイレクト先のエンドポイントは通常、特に認可サーバーを所有していない場合でも認証画面のURIから呼び出すことができるように認可サーバーのホワイトリストに登録する必要があります。スキルが複数の地域で機能するよう、ユーザーのリダイレクト先のURLに表示されるすべてのURIをホワイトリストに登録してください。
ホワイトリストへの登録方法は、使用する認可サーバーによって異なります。たとえばLogin with Amazonでは、セキュリティを設定して利用可能なリダイレクト先URLをリダイレクトURLフィールドに指定する必要があります。
これらの要件については、OAuthプロバイダーのドキュメントを参照してください。
たとえば、Implicit grantのredirect_uriパラメーターに渡される値はこのようになります。
https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=M2AAAAAAAAAAAA
認証画面のURIの要件で述べたとおり、認証画面のURIはユーザーをredirect_uriにリダイレクトし、URLフラグメントにstate、access_token、token_typeを含めます。例：
https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=M2AAAAAAAAAAAA#state=xyz&access_token=2YotnFZFEjr1zCsicMWpAA&token_type=Bearer
redirect_uriパラメーターとしてログインページの呼び出しに含まれます。アカウントリンクフローのテスト
アカウントリンクの設定を完了すると、アカウントリンクフローをテストできます。Alexaアプリでスキルを有効にし、アカウントリンクプロセスを開始します。サービスにログインしてAlexaアプリに戻ることを確認します。
アカウントリンクの実装を終了するには、受信するリクエストにアクセストークンがあるかどうかを確認して適切なアクションを実行するよう、スキルコードを更新する必要があります。詳細については、以下を参照してください。
関連トピック
- アカウントリンクとは
- カスタムスキルのアカウントリンク
- Authorization code grantを設定する
- ユーザーがアカウントをリンクせずにスキルを有効にする
- カスタムスキルコードでアクセストークンを検証して使用する
CLIまたはスキル管理APIを使ったアカウントリンクの設定：
- ASK CLI：create-account-linkingサブコマンド
- ASKスキル管理API： アカウントリンクの操作： アカウントリンクの更新
OAuthのリソース：
その他のリソース：