アカウントリンクの要件



このトピックでは、Alexaスキルにアカウントリンクを実装する際の要件について説明します。アカウントリンクの必要なスキルの種類については、アカウントリンクが必要かどうかを確認するを参照してください。

アカウントリンクの概念については、Alexaスキルにおけるアカウントリンクの概念を参照してください。ユーザーエクスペリエンスについては、Alexaスキルにおけるアカウントリンクのユーザーエクスペリエンスを参照してください。

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

システムが満たす必要のある要件は次のとおりです。

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

認証画面のURI要件

ユーザーがアカウントリンクを開始すると、Alexaアプリは認証画面のURIに移動します。このURIは、次のような認可サーバー上の機能へのエントリーポイントとなります。 1)ユーザーがシステムにログインするためのログインページを表示する、2)システムでユーザーを認証する、3)ユーザーを識別する認可コードを生成する、4)そして、Alexaアプリに認可コードを渡す

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

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

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

アクセストークンのURI要件

Alexaアプリが認証画面のURIから認可コードを取得したら、アクセストークンのURIを呼び出して認可コードをアクセストークンと交換します。このアクセストークンを使用して、システムのユーザーデータにアクセスできます。

アクセストークンのURIが満たす必要のある要件は次のとおりです

  • 機能 – アクセストークンのURIは以下の要件を満たす必要があります。
    • システムのユーザーを一意に識別するアクセストークンを生成します。
    • 4.5秒以内にアクセストークンリクエストに応答します。
    • 更新トークンを生成します。Alexaサービスは古いアクセストークンの期限が切れると、この更新トークンを使って新しいアクセストークンを取得できます。エンドユーザーの操作は必要ありません。
  • アクセストークン – アクセストークンの要件は以下のとおりです。
    • アクセストークンの有効期限は6分以上にしてください。つまり、アクセストークン応答のexpires_inパラメーターを360以上に設定する必要があります。
    • 認可サーバーで、アクセストークン応答のexpires_inパラメーターで指定された有効期限の前にAlexaサービスに渡されたアクセストークンの無効化や取り消しをしないようにしてください。ただし、インテントがアクセスの停止である場合を除きます。アクセストークンが既に無効であることをAlexaサービスに通知するメカニズムはありません。アクセストークンの期限が短すぎると、分散されたシステムが同時に動作するAlexaのようなサービスでは、サービスがすぐに使用できなくなる可能性があります。
  • 更新トークン – 新しいトークンを生成しても認可サーバーですぐに古い更新トークンを無効にしないでください。サービスを使用できなくなる可能性があるだけでなく、ユーザーの復旧手段がAlexaアプリからスキルを無効化、再度有効化、そしてアカウントリンクする以外になくなる可能性があるためです。ベストプラクティスとしては、有効期限のない更新トークンにするか、有効期限が切れた場合でも一定数の古い更新トークンを有効なままにしておくことをお勧めします。その場合、Alexaサービスが最新の更新トークンを受け取り、新しいアクセストークンの取得に使用したと認可サーバーで確認できた場合にのみ更新トークンを無効にします。
  • 古いアクセストークンのURI – スキルの公開後にOAuthコンフィギュレーションを変更する場合、既存のユーザーを新しいアクセストークンURIに移行するまで古いアクセストークンURIを使えるようにしておく必要があります。これは、Alexaユーザーが更新トークンを使用して既存ユーザーの新しいアクセストークンを取得する際に、Alexaはユーザーがアカウントをリンクしたときに設定したアクセストークンURIを使うためです。後でアクセストークンURIを変更した場合でも、以前にアカウントリンクを完了したユーザーは更新されたトークンを取得するために古いURIを引き続き使用します。新しいアクセストークンURIに切り替えるには、ユーザーがアカウントのリンクを解除して、リンクし直す必要があります。

リソースサーバーの要件

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