Alexaイベントゲートウェイへのアクセス権限のリクエスト

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
}

リクエスト本文のパラメーター

パラメーター 説明 必須

grant_type

リクエストされたアクセス認可のタイプです。このパラメーターをauthorization_codeに設定する必要があります。

文字列

code

AcceptGrantディレクティブからの認可コードです。

文字列

client_id

スキルのクライアントIDです。Alexa開発者コンソールのアクセス権限メニューで確認できます。詳細については、イベントを送信するための権限の設定を参照してください。

文字列

client_secret

スキルのクライアントシークレットです。開発者コンソールのアクセス権限メニューで確認できます。

文字列

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メディアタイプでエンコードします。

パラメーター 説明 必須

access_token

ユーザーアカウントのトークンです。
最大サイズは 2048バイトです。

文字列

token_type

トークンの種類です。このパラメーターをbearerに設定する必要があります。

文字列

expires_in

アクセストークンが無効になるまでの秒数です。

整数

refresh_token

スキルがLWAに新しいアクセストークンをリクエストできるようにするトークンです。
最大サイズは 2048バイトです。

文字列

認可の例

次の例では、Alexa.Authorization.AcceptGrantディレクティブを処理し、LWAにアクセストークンをリクエストします。

ユーザーとリージョンごとにトークンを保存する

アクセストークン・更新トークンは、いつでもユーザーに関連付けられるように、被付与者のアクセストークンと一緒に保存します。トークンは安全な場所(アマゾンウェブサービス(AWS)のDynamoDBやデバイス制御クラウド内のセキュアなトークンストアなど)に保存してください。

複数の地理的リージョンでスキルを提供する場合は、リージョンごとにLambda関数を設定する必要があります。たとえば、イベントを送信するスキルを米国と英国で提供する場合は、北米とヨーロッパのそれぞれにLambdaを設定する必要があります。米国のユーザーの場合は、北米用に設定されたLambda関数にAcceptGrantディレクティブを送信します。LWAとの認可フローを完了し、そのユーザーのトークンを保存して、スキルの北米用Lambda関数からアクセスできるようにします。このユーザーの場合、イベントは北米のゲートウェイエンドポイントに送信します。英国のユーザーの場合は、ヨーロッパ用に設定されたLambda関数にAcceptGrantを送信し、トークンを保存して、ヨーロッパのエンドポイントにイベントを送信します。

ユーザーが地理的リージョン間を移動した場合は、スキルの再有効化と再リンクを行う必要があります。これにより、関連付けられたユーザー情報の保存場所をスキルが変更できます。

AcceptGrantリクエストに応答する

認証が完了したら、AcceptGrant.Responseを返します。エラーが発生した場合は、ACCEPT_GRANT_FAILEDエラー応答を返します。

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

リクエスト本文のパラメーター

パラメーター 説明 必須

grant_type

リクエストされたアクセス認可のタイプです。このパラメーターをrefresh_tokenに設定する必要があります。

文字列

refresh_token

前回のLWA応答から受け取った更新トークンです。

文字列

client_id

スキルのクライアントIDです。Alexa開発者コンソールのアクセス権限メニューで確認できます。詳細については、イベントを送信するための権限の設定を参照してください。

文字列

client_secret

スキルのクライアントシークレットです。開発者コンソールのアクセス権限メニューで確認できます。

文字列

LWA更新トークン応答

成功した場合のHTTP応答には、ベアラーアクセストークン・更新トークンと、アクセストークンが無効になるまでの秒数が含まれます。詳細については、LWAアクセストークン応答を参照してください。これらのトークンは、いつでもユーザーに関連付けられるように、被付与者のアクセストークンと一緒に保存します。

トークンの更新の例

以下の例では、LWAに新しいアクセストークンをリクエストします。

認証フローをテストする

認証フローをテストするには、以下の手順を実施します。

テストを有効にするには

  1. Alexa開発者コンソールにサインインします。
  2. ゲームの登録時に作成したスキルを見つけます。
  3. そのスキルの行で、アクションのドロップダウンメニューから編集を選択します。
  4. テストページを開きます。
  5. テストが有効になっていない場合は、このスキルでは、テストは無効になっていますというテキストの横で、ドロップダウンリストからスキルのテストステージとして開発中を選択します。
  6. テストが既に有効になっている場合は、スキルテストが有効になっているステージというテキストの横で、ドロップダウンリストからスキルのテストステージとして開発中を選択します。

認証メッセージフローを開始するには

  1. Alexa開発者アカウントと同じ認証情報を使用して、モバイルデバイス上のAlexaアプリにサインインします。
  2. Alexaアプリでスキルを見つけるには、その他をタップし、スキル・ゲームをタップします。
  3. スキル・ゲームで、有効なスキルをタップします。
  4. スキルの種類を右にスクロールし、開発をタップします。
  5. スキル名を選択し、有効にして使用するをタップします。
  6. Alexaでプロンプトが表示されたら、Amazon開発者アカウントにサインインします。
  7. スキルへのアクセスを許可するには、権限の内容を確認し、アクセス権限を保存をタップします。

CloudWatchコンソールでスキルのログエントリを表示するには

  1. AWSマネジメントコンソールにサインインします。
  2. CloudWatchコンソールに移動します。
  3. CloudWatchコンソールで、左側のメニューのログを展開し、ロググループをクリックします。
  4. ロググループで、/aws/lambda/my-smart-home-skillをクリックしてスキルのログストリームを開きます。
  5. ログストリームで、Alexaからスキルに送信された各ディレクティブのログを表示するには、表示するログエントリをクリックします。
  6. 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イベントゲートウェイに送信された非同期メッセージは失敗します。