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

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

Alexaイベントゲートウェイにイベントを送信するには、スマートホームスキルを有効にするユーザーごとに、そのスキルでLogin with Amazon（LWA）認可サーバーとのOAuth 2.0交換を実装する必要があります。この交換により、ユーザーに代わってスキルがイベントゲートウェイにアクセスできるようになります。その後、スキルは、Alexaイベントゲートウェイへの非同期応答およびイベントにこのアクセストークンを含めます。このトークンを通じて、Alexaイベントゲートウェイエンドポイントでスマートホームスキルが認証され、AlexaでAmazonユーザーが識別されます。

Amazonでスマートホームスキルを認証し、アクセストークンを管理するには、以下のガイドラインに従ってください。

用語

このトピックでは、認可に関する以下の用語を使用します。

OAuth 2.0 - ユーザーが、ほかのサーバー上のリソースへのアクセス権限をアプリケーションに付与するための認証標準。AlexaがOAuthを使用する目的は2つあります。まず、アカウントリンク中、ユーザーが自分のAmazonアカウントをシステムのアカウントに接続する際、開発者のOAuthサーバーはユーザー情報へのアクセス権限をAlexaスキルに付与します。さらに、AmazonのOAuthサーバーは、ユーザーに代わってAlexaイベントゲートウェイへのアクセス権限をスキルに付与します。どちらのフローもOAuth Authorization code grantタイプを使用します。詳細については、OAuth 2.0を参照してください。
認可コード - Authorization code grantタイプの場合、スマートホームスキルとビデオスキルは、認可コードをアクセストークンと更新トークンのペアと交換します。AlexaはAlexa.Authorization.AcceptGrantディレクティブで認可コードを送信します。
アクセストークン - ユーザーを識別し、ユーザーによるデータへのアクセス許可を表す認証情報です。Alexaは、「ベアラー」アクセストークンタイプをサポートしています。詳細については、OAuth Access Token Typesを参照してください。
イベントゲートウェイ認可フローでは、スキルは2つのアクセストークンを使用します。
- システム内のユーザーデータにアクセスするためのトークン。スキルはAlexa.Authorization.AcceptGrantでgrantee.tokenを受け取ります。Alexaはアカウントリンク中にgrantee.tokenを取得します。詳細については、Alexaスキルにアカウントリンクを追加するを参照してください。
- イベントゲートウェイにアクセスするためのトークン。スキルは、認可コードおよびスキルの認証情報をaccess_tokenと交換します。その後、ユーザーに代わってイベントと非同期応答を送信するたびに、イベントゲートウェイへのメッセージのscopeにアクセストークンを含めます。
更新トークン - 古いアクセストークンの有効期限が切れた後、スキルが新しいアクセストークンをリクエストするときに使用する認証情報です。

イベントゲートウェイ認可フロー

アカウントリンクが完了した後、AlexaがスキルにAlexa.Authorization.AcceptGrantディレクティブを送信して、イベントゲートウェイ認可フローを開始します。このディレクティブには、Alexaがアカウントリンク中に取得したアクセストークンが含まれます。スキルはこのトークンを使用して、システム内でユーザーを識別します。このディレクティブには認可コードも含まれています。スキルは、スキルのクライアントIDとクライアントシークレットに加え、この認可コードを使用して、Alexaイベントゲートウェイへのアクセス権限をLWA OAuthサーバーから取得します。LWAは、これらの認証情報をアクセストークン・更新トークンと交換します。スキルでは、これらのトークンをユーザーごとに保存する必要があります。アクセストークンは、Alexaイベントゲートウェイにイベントを送信するときに使用します。およそ60分ごとに更新トークンを使用して、LWAに新しいトークンをリクエストします。

次の図は、Alexaゲートウェイにイベントを送信するためにスキルが実装するOAuth 2.0メッセージフローを示しています。この図はChangeReportイベントのフロー例ですが、どの非同期イベントでも同じフローを使用できます。図に示されている手順については、このトピックの後半で詳しく説明します。

LWA OAuthサーバーにアクセストークンをリクエストし、アクセストークンの有効期限が切れた後で新しいトークンをリクエストするスキルのメッセージ例。 — クリックで拡大表示

認可フローを実装する

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イベントゲートウェイに送信された非同期メッセージは失敗します。

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

フィードバックを送信

最終更新日: 2025 年 08 月 05 日