Alexaイベントゲートウェイへのアクセス権限のリクエスト
Alexaイベントゲートウェイにイベントを送信するには、スキルを有効にするユーザーごとに、スキルでLogin with Amazon(LWA)OAuthサーバーとのOAuth 2.0交換を実装する必要があります。この交換により、ユーザーに代わってスキルがイベントゲートウェイにアクセスできるようになります。ユーザーアクセストークンは、後でイベントや非同期応答をAlexaイベントゲートウェイに送信するときに提供します。このトークンを通じて、Alexaイベントゲートウェイエンドポイントでスキルが認証され、AlexaでAmazonユーザーが識別されます。
Amazonユーザーアカウントでスキルを認証し、アクセストークンを管理するには、以下のガイドラインに従ってください。
イベントゲートウェイ認可フロー
Alexaイベントゲートウェイの認可フローを開始するには、AlexaがスキルにAlexa.Authorization.AcceptGrant
ディレクティブを送信します。このディレクティブには、Alexaがアカウントリンク中に取得したベアラートークンが含まれます。スキルでは、ベアラートークンを使用してシステムのユーザーを識別します。ディレクティブには認可コードも含まれています。スキルは、スキルのクライアントID・クライアントシークレットと共に認可コードを使用して、LWA OAuthサーバーからユーザーのアクセス権限を取得します。LWAは、これらの認証情報をアクセストークン・更新トークンと交換します。スキルでは、これらのトークンをユーザーごとに保存する必要があります。アクセストークンは、Alexaイベントゲートウェイにイベントを送信するときに必要になります。60分ごとに更新トークンを使用して、LWAに新しいトークンをリクエストします。
以下の図は、OAuth 2.0のメッセージフローを示しています。
スキルは、ユーザーに代わってイベントや非同期応答を送信するたびに、イベントゲートウェイへのメッセージのスコープにアクセストークンを含めます。
認可フローを実装する
Alexa.Authorization.AcceptGrant
ディレクティブを処理し、LWAにトークンをリクエストし、各ユーザーのトークンを保存するには、Lambda関数のスキルコードにコードを追加します。
AcceptGrantディレクティブを処理する
以下は、Alexaからスキルに送信されるAlexa.Authorization.AcceptGrant
ディレクティブの例です。grant.code
は、LWAにアクセストークンをリクエストするために使用する認可コードです。grantee.token
は、スキルシステムのユーザーを識別します。これは、アカウントリンク中にAlexaが受け取ったアクセストークンです。
{
"directive": {
"header": {
"namespace": "Alexa.Authorization",
"name": "AcceptGrant",
"messageId": "メッセージID",
"payloadVersion": "3"
},
"payload": {
"grant": {
"type": "OAuth2.AuthorizationCode",
"code": "someAuthCode"
},
"grantee": {
"type": "BearerToken",
"token": "someAccessToken"
}
}
}
}
LWAにアクセストークンをリクエストする
LWAとのアクセストークンフローを開始するには、https://api.amazon.com/auth/o2/token
にセキュアなリクエストを送信します。詳細については、LWAのアクセストークンリクエストを参照してください。
以下は、LWAへの認証リクエストの例です。
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: someAuthCode from AcceptGrant directive
&client_id: your.client.id
&client_secret: your.client.secret
}
リクエスト本文のパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
リクエストされたアクセス認可のタイプです。このパラメーターを |
文字列 |
◯ |
|
|
文字列 |
◯ |
|
スキルのクライアントIDです。Alexa開発者コンソールのアクセス権限メニューで確認できます。詳細については、イベントを送信するための権限の設定を参照してください。 |
文字列 |
◯ |
|
スキルのクライアントシークレットです。開発者コンソールのアクセス権限メニューで確認できます。 |
文字列 |
◯ |
redirect_uri
を含めないでください。LWAアクセストークン応答
成功した場合のHTTP応答には、ベアラーアクセストークン・更新トークンと、アクセストークンが無効になるまでの秒数が含まれます。これらのトークンは、いつでもユーザーに関連付けられるように、被付与者のアクセストークンと一緒に保存します。
以下は、正常な認証応答の例です。
HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"someAccessToken",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"someRefreshToken"
}
応答本文には以下のパラメーターが含まれます。LWAは、これらのパラメーターをapplication/json
メディアタイプでエンコードします。
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
ユーザーアカウントのトークンです。 |
文字列 |
◯ |
|
トークンの種類です。このパラメーターを |
文字列 |
◯ |
|
アクセストークンが無効になるまでの秒数です。 |
整数 |
◯ |
|
スキルがLWAに新しいアクセストークンをリクエストできるようにするトークンです。 |
文字列 |
◯ |
認可の例
次の例では、Alexa.Authorization.AcceptGrant
ディレクティブを処理し、LWAにアクセストークンをリクエストします。
ユーザーとリージョンごとにトークンを保存する
アクセストークン・更新トークンは、いつでもユーザーに関連付けられるように、被付与者のアクセストークンと一緒に保存します。トークンは安全な場所(アマゾンウェブサービス(AWS)のDynamoDBやデバイス制御クラウド内のセキュアなトークンストアなど)に保存してください。
複数の地理的リージョンでスキルを提供する場合は、リージョンごとにLambda関数を設定する必要があります。たとえば、イベントを送信するスキルを米国と英国で提供する場合は、北米とヨーロッパのそれぞれにLambdaを設定する必要があります。米国のユーザーの場合は、北米用に設定されたLambda関数にAcceptGrant
ディレクティブを送信します。LWAとの認可フローを完了し、そのユーザーのトークンを保存して、スキルの北米用Lambda関数からアクセスできるようにします。このユーザーの場合、イベントは北米のゲートウェイエンドポイントに送信します。英国のユーザーの場合は、ヨーロッパ用に設定されたLambda関数にAcceptGrant
を送信し、トークンを保存して、ヨーロッパのエンドポイントにイベントを送信します。
ユーザーが地理的リージョン間を移動した場合は、スキルの再有効化と再リンクを行う必要があります。これにより、関連付けられたユーザー情報の保存場所をスキルが変更できます。
AcceptGrantリクエストに応答する
認証が完了したら、AcceptGrant.Response
を返します。エラーが発生した場合は、ACCEPT_GRANT_FAILED
エラー応答を返します。
AcceptGrant
の処理中にエラーが発生した場合、ユーザーはスキルを有効にすることができません。Alexaゲートウェイに送信するイベントでトークンを使用する
スキルからAlexaイベントゲートウェイに送信するメッセージでは、access_token
の値を使用します。このアクセストークンを、HTTP Authorizationヘッダーと、メッセージ本文のエンドポイントのスコープに含めます。詳細については、イベントの送信を参照してください。
有効期限が切れる前にトークンを更新する
期限切れのトークンを使用してAlexaイベントゲートウェイにメッセージを送信すると、AlexaからHTTP 401 Unauthorized
応答が返されます。ベストプラクティスとして、アクセストークンの有効期限が切れる前に、更新トークンを使用して新しいアクセストークンと更新トークンをLWAにリクエストしてください。通常、アクセストークンは60分で期限切れになります。更新トークンの使用方法の詳細については、リフレッシュトークンの使用を参照してください。
更新リクエストの例
以下は、LWAに送信する更新トークンリクエストの例です。
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: someRefreshToken
&client_id: your.client.id
&client_secret: your.client.secret
リクエスト本文のパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
リクエストされたアクセス認可のタイプです。このパラメーターを |
文字列 |
◯ |
|
前回のLWA応答から受け取った更新トークンです。 |
文字列 |
◯ |
|
スキルのクライアントIDです。Alexa開発者コンソールのアクセス権限メニューで確認できます。詳細については、イベントを送信するための権限の設定を参照してください。 |
文字列 |
◯ |
|
スキルのクライアントシークレットです。開発者コンソールのアクセス権限メニューで確認できます。 |
文字列 |
◯ |
redirect_uri
を含めないでください。LWA更新トークン応答
成功した場合のHTTP応答には、ベアラーアクセストークン・更新トークンと、アクセストークンが無効になるまでの秒数が含まれます。詳細については、LWAアクセストークン応答を参照してください。これらのトークンは、いつでもユーザーに関連付けられるように、被付与者のアクセストークンと一緒に保存します。
トークンの更新の例
以下の例では、LWAに新しいアクセストークンをリクエストします。
認証フローをテストする
認証フローをテストするには、以下の手順を実施します。
テストを有効にするには
- Alexa開発者コンソールにサインインします。
- ゲームの登録時に作成したスキルを見つけます。
- そのスキルの行で、アクションのドロップダウンメニューから編集を選択します。
- テストページを開きます。
- テストが有効になっていない場合は、このスキルでは、テストは無効になっていますというテキストの横で、ドロップダウンリストからスキルのテストステージとして開発中を選択します。
- テストが既に有効になっている場合は、スキルテストが有効になっているステージというテキストの横で、ドロップダウンリストからスキルのテストステージとして開発中を選択します。
認証メッセージフローを開始するには
- Alexa開発者アカウントと同じ認証情報を使用して、モバイルデバイス上のAlexaアプリにサインインします。
- Alexaアプリでスキルを見つけるには、その他をタップし、スキル・ゲームをタップします。
- スキル・ゲームで、有効なスキルをタップします。
- スキルの種類を右にスクロールし、開発をタップします。
- スキル名を選択し、有効にして使用するをタップします。
- Alexaでプロンプトが表示されたら、Amazon開発者アカウントにサインインします。
- スキルへのアクセスを許可するには、権限の内容を確認し、アクセス権限を保存をタップします。
CloudWatchコンソールでスキルのログエントリを表示するには
- AWSマネジメントコンソールにサインインします。
- CloudWatchコンソールに移動します。
- CloudWatchコンソールで、左側のメニューのログを展開し、ロググループをクリックします。
- ロググループで、/aws/lambda/my-smart-home-skillをクリックしてスキルのログストリームを開きます。
- ログストリームで、Alexaからスキルに送信された各ディレクティブのログを表示するには、表示するログエントリをクリックします。
- Alexaから送信された
Alexa.Authorization.AcceptGrant
ディレクティブと、スキルからの応答を確認します。
取り消しを処理する
Alexaでは、以下の理由で認可Grantが取り消されることがあります。
- ユーザーがスキルを無効にした。
- ユーザーがAmazonアカウントのアカウント>Login with Amazonの管理ページにアクセスして、スキルへの同意を明示的に取り消した。
スキルには、イベントゲートウェイへの非同期メッセージなど、Grantに依存するイベントの送信を停止するロジックが必要です。スキルのほかの部分は通常どおりに機能させる必要があります。
Grantの取り消し通知
Alexaは、認可Grantが取り消されたことを2とおりの方法で通知します。
- トークンの有効期限が切れる前に、ユーザーがスキルを無効にした場合または同意を取り消した場合、AlexaはHTTP応答に
403 Forbidden
ステータスコードを返します。
以下はHTTP 403
応答の例です。
HTTP/1.1 403 Forbidden
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close
{
"header": {
"namespace": "System",
"name": "Exception",
"messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
},
"payload": {
"code": "SKILL_DISABLED_EXCEPTION",
"description": "スキルが無効にされました。そのユーザーに関するイベントの送信を停止するには、そのスキルがユーザーによって無効にされたことを3Pが明確に識別する必要があります"
}
}
-
トークンを更新できません。このシナリオでトークンを更新しようとすると、LWAから
invalid_grant
エラーコードが返されます。このエラーは、ユーザーが認可を取り消したことを示します。詳細については、アクセストークンエラーを参照してください。ユーザーが同意を取り消すと、LWAで認可Grantが取り消され、ユーザーアカウントに関連付けられたリソースの一部または全部に対するスキルからのアクセスが拒否されます。
新しい認可コードをリクエストする
ユーザーに関連付けられていたアクセストークンや更新トークンが失われた場合は、バックフィルプロセスを使用して新しいトークンをリクエストする必要があります。このプロセスを開始するには、開発者サポートページのお問い合わせフォームを使用します。このフォームを送信すると、スキルを有効にしている各ユーザーにAlexaからAcceptGrant
ディレクティブが再送されます。
お問い合わせフォームには以下の情報を入力してください。
- Eメールアドレス: スキルに関連付けられている開発者アカウントのEメールアドレスを指定してください。
- カテゴリー: Alexa
- お問い合わせ内容: スキルの認証バックフィルをリクエストし、スキルIDをお知らせください。
このプロセスにより、1秒あたりに最大10件のトランザクションを受け取ることがあります。このレートに対応できない場合は、お問い合わせのリクエストでお知らせください。
バックフィルプロセスが完了するまで、スキルで送信できるのは同期イベントだけになります。バックフィルプロセスの間、Alexaイベントゲートウェイに送信された非同期メッセージは失敗します。
最終更新日: 2022 年 05 月 25 日