Alexaスキルにおけるアカウントリンクの要件

Alexaスキルにおけるアカウントリンクの要件

Alexaスキルのアカウントリンクは、OAuth 2.0認証フレームワークを使用します。スキルがアカウントリンクを使用する場合、認可サーバーが以下の要件を満たしている必要があります。

独自の認可サーバーがない場合、Login with Amazon（LWA）、またはAmazon認定の認証局によって署名された証明書を保有するほかのOAuth 2.0プロバイダーを使用することができます。https://letsencrypt.org/は証明書リストに記載されていますが、使用することはできませんので注意してください。

アカウントリンクが必要なスキルの種類については、アカウントリンクが必要かどうかを確認するを参照してください。

認証フレームワークの要件

使用する認証システムは、以下の要件を満たす必要があります。

  • OAuth – システムはOAuth 2.0をサポートする必要があります。
  • Grant種別 – カスタムスキルの場合、システムはAuthorization code grant種別またはImplicit grant種別をサポートする必要があります。アカウントリンクをサポートするほかの種類のスキル（スマートホームスキルなど）の場合は、Authorization code grant種別をサポートする必要があります。

認証画面のURI要件

ユーザーがAlexaアプリでアカウントリンクを開始すると、認証画面のURIが表示されます。このURIは認可サーバーへのエントリーポイントで、認可サーバーは以下を実施します。

  1. ユーザーがシステムにサインインするためのログインページを表示する。
  2. システム内のユーザーを認証する。
  3. ユーザーを識別する認可コードを生成する。
  4. 認可コードをAlexaサービスに返す。

認証画面のURIは、以下の要件を満たす必要があります。

  • プロトコル – 443番ポートでHTTPSを介してアクセスできる必要があります。
  • ユーザーインターフェース – モバイルでも見やすいログインページをAlexaアプリ内で表示し、ポップアップウィンドウを開いたり、JavaScriptのアラートやメッセージボックスを起動したりしないようにします。ユーザーにエラーが発生した場合（誤ったパスワードを入力した場合など）、ログインページにエラーを表示する必要があります。
  • 機能 – 認証画面のURIで、サービスは以下を実施する必要があります。
    • ユーザーの認証情報を受け取り、システム内のユーザーを認証します。
    • 認可コードを生成します。Alexaアプリは、この認可コードをアクセストークンのURIに渡して、システム内でユーザーを一意に識別するアクセストークンを取得します。
    • Alexaアプリからクエリ文字列で渡されたstate値をトラッキングします。認可サーバーは、該当するアカウントリンクリクエストのAlexaリダイレクトURIを呼び出す際、このstate値を使用する必要があります。
  • リダイレクト – ユーザーをAlexaアプリにリダイレクトする際の要件は以下のとおりです。
    • ユーザーを認証したら、Alexaアプリからクエリパラメーターとして認証画面のURIに渡されたAlexaリダイレクトURIに、ログインページからユーザーをリダイレクトする必要があります。その際、stateとcodeをAlexaリダイレクトURIのクエリ文字列に含めます。 たとえば、https://pitangui.amazon.com/api/skill/link/ABCDEFGHIJ?state=xyz&code=SplxlOBeZQQYbYS6WxSbIAのようになります。
    • ユーザーをリダイレクトするには、Alexaのリダイレクト先URLを認証プロバイダーに登録する必要があります。登録するURLは、開発者コンソールのアカウントリンクページにあるAlexaのリダイレクトの先URLの値、および認可リクエストURLのredirect_uriパラメーターで確認できます。スキルが複数のリージョンで機能するよう、表示されたすべてのURIを登録してください。
  • ドメイン – ログインページが認証画面のURI以外のドメインからコンテンツを取得する場合、すべてのドメインを開発者ポータルのドメインリストフィールドまたはアカウントリンクのスキーマのdomains配列に追加する必要があります。たとえば、認証画面のURIがhttps://www.ridehailer.com/loginで、www.ridehailer.com以外のドメインから何らかのコンテンツ（画像など）を取得する場合、そのドメインをドメインリストに追加する必要があります。追加しない場合、ログインページはエラーになります。

トークンのURI要件

認証画面のURIから認可コードを取得した後、AlexaサービスはアクセストークンのURIを呼び出して認可コードをアクセストークンと更新トークンに交換し、システム内のユーザーデータにアクセスします。

アクセストークンのURIの要件は次のとおりです

  • プロトコル – 443番ポートでHTTPSを介してアクセスできる必要があります。
  • 機能 – アクセストークンのURIで、サービスは以下を実施する必要があります。
    • システムのユーザーを一意に識別するアクセストークンを生成します。
    • 4.5秒以内にアクセストークンリクエストに応答します。
    • 更新トークンを生成します。Alexaサービスは古いアクセストークンの期限が切れると、この更新トークンを使って新しいアクセストークンを取得できます。エンドユーザーの操作は必要ありません。
    • OAuth 2.0エラー応答で定義されたHTTPステータスコードを返します。
    • サービスとAlexaの間のリンクを解除する場合にのみinvalid_grantはを返します。このエラーを受け取ると、Alexaはユーザートークンを削除し、Alexaアカウントとサービスのリンクを解除します。
    • HTTP 500 Server Errorやその他の5XXステータスコードなど、サーバーエラーに対して正しいHTTPステータスコードを返します。サーバーエラーに対して期限切れまたは無効な認証ステータスコードを送信しないでください。
  • アクセストークンと更新トークン – アクセストークンと更新トークンの要件は以下のとおりです。
    • Amazonでは、アクセストークンの有効期限（TTL）を1時間以上に設定することを推奨しています。同様に、アクセストークン応答のexpires_inパラメーターは3600秒以上に設定してください。
    • Amazonでは、更新トークンのTTL値を180日以上または無期限に設定することを推奨しています。
    • アクセストークンの有効期限は、更新トークンよりも短く設定する必要があります。
    • 更新トークンのローテーションを有効にした場合は、認可サーバーがアクセストークンを更新するたびに、新しい更新トークンを発行するか既存の更新トークンを延長します。
    • アクセスを停止する場合を除き、expires_inパラメーター値の有効期限が切れる前にアクセストークンを無効にしたり取り消したりしないでください。認可サーバーがアクセストークンを無効ししたことをAlexaサービスに通知するメカニズムはありません。アクセストークンの期限が短すぎると、分散されたシステムが同時に動作するAlexaサービスのようなシステムでは、サービスが使用できなくなる可能性があります。
    • 新しいトークンの生成後も一定期間古いアクセストークンと更新トークンが有効なままになるよう、認可サーバーを設定します。Alexaサービスが新しいアクセストークンと最新の更新トークンを受け取ったことを認可サーバーが確認するまで、更新トークンを無効にしないでください。
    • アクティブでない更新トークンを認可サーバーで無効にする場合は、アクティブでないとみなす期間を1年に設定することを推奨します。
    • ユーザーは複数のチャネルからシステム内のアカウントにアクセスする可能性があるため、ユーザーがシステムとアカウントリンクできるサービスやクライアントの数を制限しないでください。
    • ソフトウェアまたはハードウェアのメンテナンス中にトークンを無効にしないでください。
  • 古いアクセストークンのURI – スキルの公開後にOAuth設定を変更する場合、既存のユーザーを新しいアクセストークンURIにすべて移行するまで古いアクセストークンURIを使えるようにしておく必要があります。Alexaは、既存ユーザーのトークンを更新する際、ユーザーがアカウントをリンクしたときに設定したアクセストークンURIを使用します。後でアクセストークンURIを変更した場合でも、以前にアカウントリンクを完了したユーザーは更新されたトークンを取得するために古いURIを引き続き使用します。新しいアクセストークンURIに切り替えるには、ユーザーがアカウントのリンクを解除して、リンクし直す必要があります。

リソースサーバーの要件

ユーザーのデータを格納するリソースサーバーには、アクセストークンを受け取るURIが必要です。

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

最終更新日: 2025 年 07 月 25 日