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": "メッセージ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`	スキルのクライアントシークレットです。開発者コンソールのアクセス権限メニューで確認できます。	文字列	◯

注：リクエストに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メディアタイプでエンコードします。

パラメーター	説明	型	必須
`access_token`	ユーザーアカウントのトークンです。最大サイズは 2048バイトです。	文字列	◯
`token_type`	トークンの種類です。このパラメーターを`bearer`に設定する必要があります。	文字列	◯
`expires_in`	アクセストークンが無効になるまでの秒数です。	整数	◯
`refresh_token`	スキルがLWAに新しいアクセストークンをリクエストできるようにするトークンです。最大サイズは 2048バイトです。	文字列	◯

認可の例

次の例では、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ヘッダーと、メッセージ本文のエンドポイントのスコープに含めます。詳細については、イベントの送信を参照してください。

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

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

重要： 更新トークンを使用して新しいトークンを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: 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`	スキルのクライアントシークレットです。開発者コンソールのアクセス権限メニューで確認できます。	文字列	◯

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

LWA更新トークン応答

成功した場合のHTTP応答には、ベアラーアクセストークン・更新トークンと、アクセストークンが無効になるまでの秒数が含まれます。詳細については、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の管理ページにアクセスして、スキルへの同意を明示的に取り消した。

スキルには、イベントゲートウェイへの非同期メッセージなど、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 日