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

Note: Sign in to the developer console to build or publish your skill.

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": "一意のバージョン4 UUID",
      "payloadVersion": "3"
    },
    "payload": {
      "grant": {
        "type": "OAuth2.AuthorizationCode",
        "code": "someAuthCode"
      },
      "grantee": {
        "type": "BearerToken",
        "token": "someAccessToken"
      }
    }
  }
}

LWAにアクセストークンをリクエストする

LWAとのアクセストークンフローを開始するには、LWAに認可コードを使用してアクセストークンを取得するREST APIリクエストを送信します。

注：アクセストークンリクエストにredirect_uriを含めないでください。

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

認可の例

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

クリップボードにコピーされました。

"""
Copyright 2021 Amazon.com, Inc. or its affiliates.All Rights Reserved.
SPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0
Licensed under the Amazon Software License  http://aws.amazon.com/asl/
"""
import json
import logging
import urllib.request
import urllib.parse
from urllib.error import HTTPError

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

# TODO： Login with Amazon（LWA）APIを呼び出すためのクライアントIDを更新します。
client_id = "＜クライアントID＞"
# TODO： LWA APIを呼び出すためのクライアントシークレットを更新します。
client_secret = "＜クライアントシークレット＞"
# TODO： エンドポイントIDを更新します。
endpoint_id = "device_id"


def handle_accept_grant(alexa_request):
    auth_code = alexa_request["directive"]["payload"]["grant"]["code"]
    message_id = alexa_request["directive"]["header"]["messageId"]

    # 認可コードからアクセストークンと更新トークンを取得するLogin With Amazon APIを使用します。
    lwa_token_url = "https://api.amazon.com/auth/o2/token"

    data = urllib.parse.urlencode(
        {
            "grant_type": "authorization_code",
            "code": auth_code,
            "client_id": client_id,
            "client_secret": client_secret
        }
    ).encode("utf-8")

    headers = {
        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8"
    }

    url_request = urllib.request.Request(lwa_token_url, data, headers, "POST")

    try:
        with urllib.request.urlopen(url_request) as response:
            """
            応答には以下が含まれます。
            - access_token： Alexaイベントゲートウェイに送信するディレクティブへの非同期応答とイベントで使用されます。
            - refresh_token： access_tokenが期限切れになったときに、新しいトークンをLWAから取得するために使用されます。
            - token_type： 想定されるトークンの種類はベアラーです。
            - expires_in： access_tokenが期限切れになるまでの秒数です（想定される値は3600秒、つまり1時間です）。
            """
            lwa_tokens = json.loads(response.read().decode("utf-8"))

            # TODO： LWAトークンを安全な場所（AWS Secrets Managerなど）に保存します。
            logger.info("成功。")
            logger.info(f"access_token：{lwa_tokens['access_token']}")
            logger.info(f"refresh_token：{lwa_tokens['refresh_token']}")
            logger.info(f"token_type：{lwa_tokens['token_type']}")
            logger.info(f"expires_in：{lwa_tokens['expires_in']}")
    except HTTPError as http_error:
        logger.error(f"エラーが発生しました：{http_error.read().decode('utf-8')}")

        # Alexaに送信する失敗応答を構築します。
        response = {
            "event": {
                "header": {
                    "messageId": message_id,
                    "namespace": "Alexa.Authorization",
                    "name": "ErrorResponse",
                    "payloadVersion": "3"
                },
                "payload": {
                    "type": "ACCEPT_GRANT_FAILED",
                    "message": "ユーザーの認可コードからLWAトークンを取得できませんでした。"
                }
            }
        }
    else:
        # Alexaに送信する成功応答を構築します。
        response = {
            "event": {
                "header": {
                    "namespace": "Alexa.Authorization",
                    "name": "AcceptGrant.Response",
                    "messageId": message_id,
                    "payloadVersion": "3"
                },
                "payload": {}
            }
        }

    logger.info(f"AcceptGrant応答：{json.dumps(response)}")

    return response

def lambda_handler(request, context):
    logger.info(f"request：{request}")

    namespace = request["directive"]["header"]["namespace"]
    name = request["directive"]["header"]["name"]

    if namespace == "Alexa.Authorization" and name == "AcceptGrant":
        return handle_accept_grant(request)

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

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

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

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

AcceptGrantリクエストに応答する

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

重要： AcceptGrantの処理中にエラーが発生した場合、ユーザーはスキルを有効にすることができません。

Alexaゲートウェイに送信するイベントでトークンを使用する

スキルからAlexaイベントゲートウェイに送信するメッセージでは、access_tokenの値を使用します。このベアラーアクセストークンを、HTTP Authorizationヘッダーと、メッセージ本文のendpoint.scopeに含めます。詳細については、イベントの送信を参照してください。

有効期限が切れる前にトークンを更新する

期限切れのトークンを使用してAlexaイベントゲートウェイにメッセージを送信すると、AlexaからHTTP 401 Unauthorized応答が返されます。ベストプラクティスとして、アクセストークンの有効期限が切れる前に、更新トークンを使用して新しいアクセストークンと更新トークンをLWAにリクエストしてください。通常、アクセストークンは60分で期限切れになります。トークンを更新するには、アクセストークンを更新する操作を使用します。

重要： 更新トークンを使用して新しいトークンをLWAから取得する場合、古いトークンは有効期限になるまで引き続き有効です。

トークンの更新の例

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

クリップボードにコピーされました。

"""
Copyright 2021 Amazon.com, Inc. or its affiliates.All Rights Reserved.
SPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0
Licensed under the Amazon Software License  http://aws.amazon.com/asl/
"""
import json
import logging
import urllib.request
import urllib.parse
from urllib.error import HTTPError

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

# TODO： 更新トークン、または安全な場所から更新トークンを取得する呼び出しで更新します。
refresh_token = "＜更新トークン＞"
# TODO： Login with Amazon（LWA）APIを呼び出すためのクライアントIDを更新します。
client_id = "＜クライアントID＞"
# TODO： LWA APIを呼び出すためのクライアントシークレットを更新します。
client_secret = "＜クライアントシークレット＞"

# Login with Amazon APIエンドポイント
lwa_token_url = "https://api.amazon.com/auth/o2/token"

data = urllib.parse.urlencode(
    {
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
        "client_id": client_id,
        "client_secret": client_secret
    }).encode("utf-8")

headers = {
    "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8"
}

request = urllib.request.Request(lwa_token_url, data, headers, "POST")

try:
    with urllib.request.urlopen(request) as response:
        """
        応答には以下が含まれます。
        - access_token： Alexaイベントゲートウェイに送信するディレクティブへの非同期応答とイベントで使用されます。
        - refresh_token： access_tokenが期限切れになったときに、新しいトークンをLWAから取得するために使用されます。
        - token_type： 想定されるトークンの種類はベアラーです。
        - expires_in： access_tokenが期限切れになるまでの秒数です（想定される値は3600秒、つまり1時間です）。
        """
        lwa_tokens = json.loads(response.read().decode("utf-8"))

        # TODO： 以前と同じ安全な場所に新しいLWAトークンを保存します。
        logger.info("成功。")
        logger.info(f"access_token：{lwa_tokens['access_token']}")
        logger.info(f"refresh_token：{lwa_tokens['refresh_token']}")
        logger.info(f"token_type：{lwa_tokens['token_type']}")
        logger.info(f"expires_in：{lwa_tokens['expires_in']}")
except HTTPError as http_error:
    logger.error(f"エラーが発生しました：{http_error.read().decode('utf-8')}")

認証フローをテストする

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

テストを有効にするには

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の管理ページにアクセスして、スキルへの同意を明示的に取り消した。ユーザーが同意を取り消すと、LWAで認可Grantが取り消され、ユーザーアカウントに関連付けられたリソースの一部または全部に対するスキルからのアクセスが拒否されます。

スキルには、イベントゲートウェイへの非同期メッセージなど、Grantに依存するイベントの送信を停止するロジックが必要です。スキルのほかの部分は通常どおりに機能させる必要があります。

Grantの取り消し通知

Alexaは、ユーザーが認可Grantを取り消したことを以下のいずれかの方法で通知します。

トークンを更新できません。このシナリオでトークンを更新しようとすると、LWAからinvalid_grantエラーコードが返されます。このエラーは、ユーザーが認可を取り消したことを示します。詳細については、アクセストークンを更新するを参照してください。
トークンの有効期限が切れる前に、ユーザーがスキルを無効にした場合または同意を取り消した場合、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が明確に識別する必要があります"
  }
}

新しい認可コードをリクエストする

ユーザーに関連付けられていたアクセストークンや更新トークンが失われた場合は、バックフィルプロセスを使用して新しいトークンをリクエストする必要があります。このプロセスを開始するには、開発者サポートページのお問い合わせフォームを使用します。このフォームを送信すると、スキルを有効にしている各ユーザーにAlexaからAcceptGrantディレクティブが再送されます。

お問い合わせフォームには以下の情報を入力してください。

Eメールアドレス： スキルに関連付けられている開発者アカウントのEメールアドレスを指定してください。
カテゴリー： Alexa
お問い合わせ内容： スキルの認証バックフィルをリクエストし、スキルIDをお知らせください。

このプロセスにより、1秒あたりに最大10件のトランザクションを受け取ることがあります。このレートに対応できない場合は、お問い合わせのリクエストでお知らせください。

バックフィルプロセスが完了するまで、スキルで送信できるのは同期イベントだけになります。バックフィルプロセスの間、Alexaイベントゲートウェイに送信された非同期メッセージは失敗します。

このページは役に立ちましたか？

フィードバックを送信

最終更新日: 2024 年 12 月 20 日