トークンのメカニズム

シンプルサインインソリューションには、2種類のトークンが使用されます。

リンクトークン： システム内でユーザーのIDを認証するには、リンクトークンを発行します。リンクトークンは、Amazonユーザーとのリンクを証明するために使用されます。リンクトークンには、追加のコンテキスト情報（アカウントがリンクされた時刻など）が含まれる場合があります。
シンプルサインイン（SSI）トークン： 新しいサインインリクエストごとにAmazonが発行する一時的なトークン。SSIトークンは、リンクトークンをアプリに安全に返信するために使用されます。このトークンはリンクトークンをカプセル化し、基になるリンクトークンの有効性を証明してユーザー認証の使用を承認するために使用されます。

リンクトークンの利点
リンクトークンの仕様
リンクトークンのライフサイクル
SSIトークンの仕様
SSIトークンと安全な認証
使用される暗号化キー
リンクトークンを使用したユーザー認証

リンクトークンの利点

リンクトークンを使用する利点は以下のとおりです。

ユーザーが認証され、アカウントのリンクが承認されたことを明示できます。普通の識別子は、ユーザーの認証や承認を証明するには不十分です。
アカウントのリンクを付与する権限を維持しながら、AmazonでのユーザーID間の関連付けを保存・追跡するという重労働を軽減できます。
アカウントのリンクに関する詳しいコンテキスト情報（ソースデバイス情報など）をトークンの一部として取得できます。トークン自体は、トークン検証中に消費されます。取得できない場合、このデータを維持するためのカスタムソリューションを構築する必要があります。

リンクトークンの仕様

リンクトークンの仕様のバージョンは、文字列リテラルLINK-TOKEN-1.0を使用して識別されます。

リンクトークンには、ID管理システム内でアプリのユーザーを一意に識別するための識別子を含める必要があります。
リンクトークンの範囲をリンク先のAmazonユーザーに限定し、その特定のAmazonユーザーに登録されているデバイスにリンクトークンの使用を制限できるようにする必要があります。そのためには、AmazonユーザーID（AmazonUserId）をトークンに埋め込みます。AmazonユーザーIDは、シンプルサインインクライアントAPIのgetUserAndLinks()メソッドでアプリに公開されます。詳細については、SSIクライアントAPIを参照してください。
リンクトークンには、リンク検証キー（対応するSSIトークンの真正性と整合性の確認に使用する楕円曲線（EC）パブリックキー）が含まれている必要があります。リンク検証キーの詳細については、使用する暗号化キーを参照してください。
アカウントのリンクが設定された時刻や、アカウントのリンクが開始されたソースアプリやデバイスに関するメタデータなど、追加のコンテキストフィールドを含めることができます。
トークン内でエンコードされたデータ要素の機密性を維持するには、トークンのペイロードを暗号化します。暗号化と復号化の操作に使用される暗号化キーは開発者が管理し、Amazonとは共有しません。
トークン検証中にトークンの整合性と真正性を検証するには、トークンにデジタル署名する必要があります。デジタル署名に使用される暗号化キーはアプリの所有者によって管理され、Amazonと共有する必要はありません。
リンクトークンに有効期限はありません。リンクトークンの有効性は、ユーザーのアカウントリンクの現在のステータスに関連付けられています。
リンクトークンは、Amazonから見ると不透明型の文字列です。この仕様では、トークンの構築に固有のエンコードスキームは指定されていません。

リンクトークンのライフサイクル

リンクトークンに有効期限はありませんが、有効期間の短いSSIトークンによって使用が制限されます。ユーザーがアカウントのリンクを無効にするアクションを開始するまで、リンクトークンはシステムで有効です。ユーザーは、シンプルサインインをアカウントレベルでグローバルにオフにするか、特定のアプリごとにオフにすることで、アカウントのリンクを削除できます。これらの設定は、デバイスの設定メニューで管理することも、Amazonのウェブサイトからリモートで管理することもできます。ユーザーがAmazonの端末とのリンクの解除を開始すると、リンクが削除済みとしてマークされ、対応するリンクトークンがシンプルサインインサーバーで破棄されます。

SSIトークンの仕様

SSIトークンの仕様は、文字列リテラルSSI-TOKEN-1.0を使用して識別されます。

SSIトークンは、Amazonによって生成され、リンク済みアカウントを使用してアプリでユーザーを認証する際に、リンクトークンをAmazonからシステムに安全に送信するために使用します。
SSIトークンは、リンクトークンを内部にカプセル化します。また、SSIトークンには使用範囲を制限するための次のデータが含まれています。
- Directed ID： デバイスで現在アクティブなAmazonユーザーを識別します。
- タイムスタンプのフィールド： トークンの有効期間を指定するために使用します。この期間は、トークンが発行された時点から5分に設定されます。通常、これは進行中のサインインリクエストが完了するまでに十分な長さです。Amazonのサーバーと開発者のサーバー間で時計に差がある可能性も考慮されています。
このトークンは暗号化されていません。
このトークンには、Amazonがリンク署名キーを使用して署名します。このキーは、アカウントリンクの設定時にリンクトークンと共に発行されます。

このトークンは、署名付きJSON Web Token（JWT）としてエンコードされています。各フィールドの説明は以下のとおりです。

ヘッダー

{
  "alg": "ES384",
  "typ": "JWT",
  "schema": "SSI-TOKEN-1.0"
}

ペイロード

{  "iss": "https://ssi.amazon.com", // Amazon SSIサービスをトークンの発行者として識別します
  "aud": "<PARTNER_VENDOR_ID>", // このトークンの受信者を示します。 開発者のオンボーディング中にAmazonアプリストア開発者コンソールで割り当てられる一意のベンダーIDです。
  "linkInfo": {
     "linkToken": {
         "schema": "LINK-TOKEN-1.0",
         "token": "<LINK_TOKEN>" // 開発者によって発行されるリンクトークンです。
     },
     "amazonUser": "<AMZN_USER_ID>", // 元のデバイスで アクティブなユーザーのAmazonアカウントを表す開発者限定のDirected IDです。 対象のデバイスのみでリンクトークンが使用されていることを確認するために、開発者はこの値をリンクトークン内で取得されたAmazonユーザーIDと一致させます。
     "partnerUser": "<PARTNER_USER_ID>", // アカウントのリンク設定中に開発者によって提供されるユーザーアカウントを表すDirected IDです。
  },
  "nbf": 1589366574, // トークンの有効性 - 開始時刻 - エポックからの秒数
  "iat": 1589366874, // トークンの 発行時刻 - エポックからの秒数
  "exp": 1589367174, // トークンの有効性 - 終了時刻 - エポックからの秒数
  "jti": "<JWT_ID>" // トークンの一意の識別子
 }

トークンは次のようにシリアル化されます。

unsignedToken = base64UrlEncode(header) + '.' + base64UrlEncode(payload)
署名
- デジタル署名アルゴリズム： P-384およびSHA-384を使用するECDSA
- 署名の入力：unsignedToken
- 署名キー：linkSigningKey
token = unsignedToken + '.' + base64UrlEncode(signature)

SSIトークンと安全な認証

リンクトークンは、関連するIDとのリンクを表します。したがって、アカウントのリンクが有効ならリンクトークンも有効です。SSIトークンは、アカウントのリンクがまだ有効であることを明示する認証トークンとして機能し、対応するリンクトークンの使用を承認するために使用します。
SSIトークンは一時的なものであるため、基になるリンクトークンの使用は短時間に制限されます。リンク済みアカウントを使用して新たにサインインを試みるたびに、新しいSSIトークンを取得する必要があります。

使用される暗号化キー

このセクションでは、トークンの生成と検証で暗号化キーがどのように使用されるかを説明します。また、想定されるキーの所有権と管理も明示します。

AppStoreKeyPair：アプリの申請プロセスの一環として、Amazonアプリストアによってアプリごとに自動的にプロビジョニングされる2048ビットのRSAキーペア。このパブリックキーは、Amazonアプリストア開発者コンソールで共有されています。確認するには、開発者コンソールにログインし、[アプリファイルをアップロード] 画面の [関連情報] セクションで、[パブリックキーを表示] をクリックします。このキーを使用して、Amazonに安全に送信する必要があるペイロードを暗号化します。一度割り当てられたAppStoreKeyPairは、アプリの全期間を通じて変更されません。新しいバージョンのアプリが申請されても変更されることはありません。
LinkTokenEncryptionKeyとLinkTokenDecryptionKey：リンクトークンの暗号化および復号化にそれぞれ使用します。対称キー暗号化と非対称キー暗号化のどちらも使用可能です。これらのキーは開発者によって内部的に管理され、Amazonと共有されることはありません。
LinkTokenSigningKeyとLinkTokenVerificationKey：リンクトークンの署名および真正性と整合性の検証にそれぞれ使用します。非対称キーペアを使用したデジタル署名、シークレットキーを使用してMACで生成されたアドレスのどちらも使用可能です。開発者が内部的に管理し、Amazonと共有しません。

注： AES-GCMのような認証された暗号化スキームを使用すると、1つの非対称キーが次の4つのキーすべての役割を果たします： LinkTokenEncryptionKey、LinkTokenDecryptionKey、LinkTokenSigningKey、LinkTokenVerificationKey。

LinkKeyPairは、アカウントのリンク設定の一部として開発者が生成した楕円曲線（ECC）キーペア（サポートされる曲線：secp384r1/NIST P-384）です。リンク済みアカウントごとに異なるキーペアを生成する必要があります。SSIトークンの署名と検証には、LinkSigningKey（LinkKeyPairのプライベートキー部分）とLinkVerificationKey（LinkKeyPairのパブリックキー部分）を使用します。これらのキーは次のように使用されます。
- アカウントのリンク設定には次のことが含まれます。
  - LinkSigningKeyは、アプリ固有のAppStoreKeyPairのパブリックキーを使用して暗号化され、対応するLinkVerificationKeyがLinkToken内にフィールドとして追加されます。
  - アカウントのリンクを確立するには、リクエストにLinkTokenと暗号化されたLinkSigningKeyの両方を含めます。
  - Amazonは、AppStoreKeyPairの対応するプライベートキーを使用してLinkSigningKeyを復号化し、復号化したキーをSSIサーバー上のアカウントリンクオブジェクトの一部として保持します。
- ユーザーがシンプルサインインでサインインした場合に、後でアプリからリンク済みアカウントを問い合わせると、次のようになります。
  - Amazonでは、リンク済みアカウントごとにSSIトークンを生成し、対応するLinkSigningKeyを使用して署名します。
  - 対応するLinkVerificationKeyを使用してSSIトークン署名を検証します。これはLinkTokenの復号化とデコードによって取得されます。

ベストプラクティス

Amazonアプリストアでは、トークンの生成と検証にAmazonのライブラリを使用して、開発作業を大幅に簡素化することを推奨しています。SSIトークンライブラリには、提供されたデータと暗号化キーを使用してリンクトークンを生成および検証するためのデフォルトの実装が用意されています。リンクトークンが生成されるたびに、新しいリンクキーペアが自動的に生成されます。詳細については、SSIトークンライブラリを参照してください。

リンクトークンを使用したユーザー認証

シンプルサインインフローでリンク済みアカウントを使用してユーザーを認証するために、アプリはアカウントをリンクするときにAmazonと共有のリンクトークンを使用します。アプリがリンク済みアカウントを問い合わせると、Amazonはリンクトークンを署名済みSSIトークン内でラップし、アカウントのリンクがまだ有効であることを証明します。

注：認証にはSSIトークンの一部として取得したリンクトークンのみを使用する必要があります。ほかのリンクトークンではアカウントへのリンクの現在のステータスを証明できません。SSIトークンの一部として取得したリンクトークンは、それが範囲内（目的のデバイスなど）で使用されているかどうかも検証します。

認証の手順の概要は以下のとおりです。

SSIトークンが公開スキーマに準拠する有効に署名されたJWTかを確認します。
SSIトークンが有効期間内かを確認します（ssiToken.payload.nbf <= currentTime < ssiToken.payload.exp）。
SSIトークンをアンラップして、ペイロードからリンクトークンを抽出します。
次の手順に従って、リンクトークンを検証します。
- トークンを復号化する
- トークン署名を検証する
- トークンフィールドをデコードする
リンクトークンから抽出したLinkVerificationKeyを使用して、SSIトークン署名を検証します。
リンクトークンの範囲を指定しているAmazonユーザーと、現在アクティブなAmazonユーザーが一致しているかを確認して、リンクトークンのパーミッションを検証します。このためには、リンクトークン内でエンコードされたAmazonユーザーIDフィールドと、SSIトークンに存在するAmazonユーザーIDフィールド（ssiToken.payload>linkInfo>amazonUser）を比較します。
上記の手順がすべて正常に完了したら、リンクトークンが表すリンク済みアカウントを使用して認証を完了してください。エラーが発生した場合は、シンプルサインインフローを中止し、ほかの標準のサインインオプションにフォールバックします。

Last updated: 2023年10月2日