アカウントシステムプロダクト
このガイドでは、k-IDのアカウントシステムプロダクト(Account System Product、ASP)機能の実装方法を説明します。この機能を使うと、組織の中心となるアカウントプロダクトやプラットフォームプロダクトが、組織内の他のプロダクトに代わって認証チャレンジやセッションを作成できます。使用するのはアカウントシステムプロダクトのAPIキーと任意のヘッダーだけで、プロダクトごとにAPIキーを管理する必要はありません。
機能
- 単一のAPIキー: アカウントシステムプロダクトは、プロダクトをまたぐすべての呼び出しに自身のAPIキーを使用します。プロダクトごとのキー管理は不要です。
- プロダクト固有の同意: 他のプロダクト向けにチャレンジを作成すると、保護者にはそのプロダクトのデータ通知、権限、ブランディングのみが表示されます。
- 組織単位のスコープ: 代理で操作できるのは同じ組織内のプロダクトのみです。組織をまたぐ利用は拒否されます。
- 完全な可視性: アカウントシステムプロダクトと対象プロダクトの両方がWebhookを受信し、誰がフローを開始したか、どのプロダクトの代理かを示すフィールドが含まれます。
フローの概要
アカウントシステムプロダクトは、サポート対象のエンドポイント(/age-gate/check、/challenge/send-email、/challenge/generate-otp)のいずれかに、Kid-Target-Product-Idヘッダーに対象プロダクト(アカウントシステムプロダクトではないプロダクト)のIDを設定してリクエストを送信します。APIは、両方のプロダクトが同じ組織に属していること、および呼び出し元がアカウントシステムプロダクトであることを検証します。保護者に表示されるのは対象プロダクトの設定(通知、権限、ブランディング)のみで、アカウントシステムプロダクトの設定は表示されません。各Webhookイベント(たとえばチャレンジの状態変更)は、アカウントシステムプロダクトと対象プロダクトの両方に送信されます。アカウントシステムプロダクト側のペイロードにはonBehalfOfProductIdが、対象プロダクト側のペイロードにはinitiatedByProductIdが含まれます。
前提条件
- アカウントシステムプロダクトのフラグ: 認証用またはアカウント用のプロダクトで、Compliance Studioのアカウントシステムプロダクトトグルが有効になっている必要があります(情報タブ → プロダクトの詳細)。組織でこのオプションが利用できない場合は、k-IDにお問い合わせください。
- 対象プロダクト: 代理で操作するプロダクトは同じ組織に属し、アカウントシステムプロダクトトグルが無効になっている必要があります。このヘッダーは、アカウントシステムプロダクトではないプロダクトに対してのみ使用できます。
- APIキー: アカウントシステムプロダクト(トグルを有効にしたプロダクト)のAPIキーを使用してください。対象プロダクトのAPIキーは使用しないでください。
ステップ1:Compliance Studioでアカウントシステムプロダクトを有効にする
Compliance Studioで、アカウントシステムプロダクトとして指定するプロダクト(たとえば中心となるアカウントプロダクトや認証プロダクト)のアカウントシステムプロダクト設定を有効にします。代理で操作する対象プロダクトは既存の設定のままで構いません。対象プロダクト用に新しいプロダクトやAPIキーを作成する必要はありません。
アカウントシステムプロダクトを有効にする手順
- Compliance Studioの左サイドバーでマイプロダクトを開き、アカウントシステムプロダクトとして動作させるプロダクト(他のプロダクトに代わってチャレンジやセッションを作成するプロダクト)を選択します。
- そのプロダクトの情報タブを開きます。
- プロダクトの詳細セクションにアカウントシステムプロダクトが表示されます(初期状態は無効)。ページ右上の編集をクリックします。
- 編集フォームの最下部にあるアカウントシステムプロダクトセクションまでスクロールします。説明文は 「このプロダクトが他のプロダクトに代わってチャレンジとセッションを作成できる場合に有効にしてください。」 です。
- アカウントシステムプロダクトトグルをオンにします。
- テスト環境にプッシュをクリックして設定を保存し、適用します。
これで、そのプロダクトのAPIキーをKid-Target-Product-Idヘッダーと組み合わせて、同じ組織内の他のプロダクトに代わって操作を実行できるようになります。
ステップ2:対象プロダクトのヘッダーを付けてAPIを呼び出す
アカウントシステムプロダクトが他のプロダクトの代理として操作(年齢ゲートのチェックやチャレンジの作成など)を実行する場合は、自身のプロダクトで送るものと同じリクエストに、次のヘッダーを追加します:
| ヘッダー | 値 | 必須 |
|---|---|---|
Kid-Target-Product-Id | アカウントシステムプロダクトではないプロダクトのID(対象プロダクトのk-IDプロダクトID、正の整数) | 他のプロダクトの代理として操作する場合は必須 |
AuthorizationヘッダーにはアカウントシステムプロダクトのAPIキーを使用します。リクエストは対象プロダクトのコンテキストで実行されますが、認証にはアカウントシステムプロダクトのキーが使われます。
例:ゲームの代理で年齢ゲートをチェックする
アカウントシステムプロダクトが、特定のゲーム(プロダクトID 12345)にユーザーがアクセスできるかを、そのゲームのAPIキーを管理せずにチェックします:
POST /api/v1/age-gate/check
Content-Type: application/json
Authorization: Bearer ACCOUNT_SYSTEM_PRODUCT_API_KEY
Kid-Target-Product-Id: 12345
{
"jurisdiction": "US-CA",
"dateOfBirth": "2015-03-20"
}通常のフローと同様に、チャレンジが必要な場合はレスポンスにURLが含まれることがあります。このURLで開始されるチャレンジは、アカウントシステムプロダクトではなく対象プロダクト(ここでは12345)のものです。保護者がURLを開くと、アカウントシステムプロダクトではなく対象プロダクトの設定(通知、権限、ブランディング)が表示されます。
例:プロダクトの代理でチャレンジメールを送信する
ヘッダーを含めることで、他のプロダクトに属するチャレンジの保護者同意メールを送信できます:
POST /api/v1/challenge/send-email
Content-Type: application/json
Authorization: Bearer YOUR_ACCOUNT_SYSTEM_API_KEY
Kid-Target-Product-Id: 12345
{
"challengeId": "challenge-uuid",
"email": "parent@example.com"
}メールはプロダクト12345のコンテキストで送信され、保護者がフローを完了する際にはそのプロダクトの設定が表示されます。
Kid-Target-Product-Idをサポートするエンドポイント
呼び出し元がアカウントシステムプロダクトの場合に、任意のKid-Target-Product-Idヘッダーを受け付けるのは次のエンドポイントのみです:
ヘッダーを省略した場合、リクエストは通常の統合と同様に、自身のプロダクト(アカウントシステムプロダクト)に対して適用されます。
マルチプロダクト承認
アカウントシステムプロダクトはマルチプロダクト承認と組み合わせて使用できます。よくある構成は、アカウントシステムプロダクトを対象プロダクト(たとえばゲーム)の必須プロダクトに設定する方法です。この場合、アカウントシステムプロダクトのAPIキーと、そのゲームを指定したKid-Target-Product-Idで/age-gate/checkを呼び出すと、保護者に表示される同意フローにゲームとアカウントシステムプロダクトの両方を含めることができ、保護者はゲームとプラットフォームを一度に承認できます。設定はCompliance Studioの対象プロダクト側で行います。複数プロダクト承認の設定で、アカウントシステムプロダクトをそのプロダクトの必須プロダクトに指定してください。すべてのオプション(必須プロダクト、バンドリング、動的バンドリング)については、マルチプロダクト承認ガイドを参照してください。
ステップ3:プロダクトをまたぐフローのWebhookを処理する
アカウントシステムプロダクトが他のプロダクトの代理でフローを開始すると、各Webhookイベントは2つのエンドポイントの両方に送信されます。1つはアカウントシステムプロダクトのWebhook URL、もう1つは対象プロダクト(アカウントシステムプロダクトではないプロダクト)のWebhook URLです。これはフローの完了時だけでなく、チャレンジのライフサイクル全体を通じてすべてのイベント(たとえば状態変更)で行われます。
- アカウントシステムプロダクトのWebhook:
onBehalfOfProductId(代理で操作した対象プロダクトのID)を含みます。 - 対象プロダクトのWebhook:
initiatedByProductId(フローを開始したアカウントシステムプロダクトのID)を含みます。
イベントのペイロードには次のフィールドが含まれるため、プロダクトをまたぐフローを区別できます:
| フィールド | 含まれるWebhook | 説明 |
|---|---|---|
onBehalfOfProductId | アカウントシステムプロダクトのWebhook | 代理で操作したプロダクトのID(対象プロダクト)。 |
initiatedByProductId | 対象プロダクトのWebhook | フローを開始したプロダクトのID(アカウントシステムプロダクト)。 |
例:Challenge.StateChange(アカウントシステム側)
プロダクト12345の代理で開始したフローについて、アカウントシステムプロダクトのWebhookがチャレンジの状態変更を受信した場合:
{
"eventType": "Challenge.StateChange",
"data": {
"id": "9d6b056e-7d62-4a9e-907a-3d0f6f1d1b9a",
"productId": 12345,
"status": "PASS",
"onBehalfOfProductId": 12345,
"sessionId": "b6d1a7c2-8f34-4c83-bf0b-3a6d4a2f9d31",
"approverEmail": "parent@example.com",
"kuid": "7a1f2c3d-4e5f-6789-abcd-ef0123456789"
}
}ここではproductIdとonBehalfOfProductIdの両方が対象プロダクトを指します。ハンドラーはonBehalfOfProductIdを使って、この同意がどのプロダクトに対するものかを判断できます。
例:Challenge.StateChange(対象プロダクト側)
対象プロダクトのWebhookは、initiatedByProductIdにアカウントシステムプロダクトのプロダクトIDが設定された同じイベントを受信します:
{
"eventType": "Challenge.StateChange",
"data": {
"id": "9d6b056e-7d62-4a9e-907a-3d0f6f1d1b9a",
"productId": 12345,
"status": "PASS",
"initiatedByProductId": 99999,
"sessionId": "b6d1a7c2-8f34-4c83-bf0b-3a6d4a2f9d31",
"approverEmail": "parent@example.com",
"kuid": "7a1f2c3d-4e5f-6789-abcd-ef0123456789"
}
}99999はアカウントシステムプロダクトのプロダクトIDです。対象プロダクトのペイロードでは、productIdは対象プロダクト自身のIDで、initiatedByProductIdはどのアカウントシステムプロダクトがフローを開始したかを示します。同じチャレンジに関する他のWebhookイベントタイプ(たとえばセッション関連のイベント)にも、同じ二重配信とフィールドのパターンが適用されます。ペイロードの詳細はWebhookとChallenge.StateChangeを参照してください。
セキュリティと検証
- 組織のチェック: 対象プロダクトは、アカウントシステムプロダクトと同じ組織に属している必要があります。他の組織のプロダクトに対するリクエストは
400 Bad Requestで拒否されます。 - ASPからASPへの操作は不可: 対象プロダクトにアカウントシステムプロダクトを指定することはできません。このようなリクエストは拒否されます。
- APIキー:
Kid-Target-Product-Idと組み合わせて使用できるのは、アカウントシステムプロダクトのAPIキーのみです。他のプロダクトのキーでこのヘッダーを使用すると403 Forbiddenが返されます。 - ヘッダーの形式:
Kid-Target-Product-Idは正の整数である必要があります。無効な値の場合は400 Bad Requestが返されます。
代表的なフロー
-
統合アカウントと複数のゲーム
プラットフォームがアカウントシステムプロダクトです。ユーザーがゲームを起動すると、サーバーはKid-Target-Product-IdにそのゲームのプロダクトIDを設定してk-ID APIを呼び出します。保護者にはそのゲームの同意リクエストのみが表示され、アカウントシステムプロダクトとゲームの両方がWebhookを受信します。 -
中央認証サービス
認証サービスがアカウントシステムプロダクトです。同じ組織内の複数のクライアントプロダクト(たとえばゲームやアプリ)に対して、チャレンジの作成や年齢ゲートのチェックを行います。各クライアントプロダクトは、それぞれ独自のCompliance Studioの設定とWebhook URLを保持します。 -
セッションとチャレンジの一貫性
関連するエンドポイントで同じヘッダーを使用することで、同じ対象プロダクトに対してチャレンジを作成し、セッションを取得できます。これにより、アカウントシステムプロダクトを単一の統合ポイントとしつつ、各プロダクトのコンプライアンスとUXを独立したまま保てます。
次のステップ
- Compliance Studioで、アカウントシステムプロダクトと対象プロダクトを設定します。
- APIリファレンスで、使用するエンドポイントのリクエストとレスポンスの形式を確認します。
- アカウントシステムプロダクトと対象プロダクトの両方にWebhookを設定し、必要に応じて
onBehalfOfProductId/initiatedByProductIdを処理します。 - マルチプロダクトの同意フロー(たとえば必須プロダクトやバンドリング)については、マルチプロダクト承認を参照してください。