背景

独自開発アプリケーションを Identity as a Service （IDaaS）と統合して、IDaaS の組織とアカウントをアプリケーションに同期できます。

アプリケーションアカウントを IDaaS に同期する方法の詳細については、「アプリケーション開発用の API 操作」をご参照ください。

アプリケーションの同期を設定する方法の詳細については、「プロビジョニングでアプリケーションの IDaaS アカウントを同期する」をご参照ください。このトピックでは、アカウント同期を実装するためにアプリケーションを IDaaS と統合する方法について説明します。

依存関係の一貫性: 関係者は、マーケティングまたは検証のためにアプリケーションの ID データに依存する場合があります。そのため、IDaaS アカウントの変更を速やかに同期する必要があります。たとえば、従業員がオンボーディングされると、IDaaS にアカウントが作成されます。スケジュールどおりに作業を進めるには、同時に HR アプリケーションにもアカウントを作成する必要があります。この場合、アカウントの作成イベントをサブスクライブできます。
リアルタイム要件: アプリケーションはユーザー操作に迅速に応答する必要があります。たとえば、ユーザーがシステムにログオンして携帯電話番号を変更した後、アカウントの更新イベントを使用して、アプリケーションでユーザーの携帯電話番号を更新する必要があります。

イベントコールバックメカニズム

上記の例は 2 つの単純なシナリオです。開発者は、さまざまな要件に基づいてさまざまなイベントをサブスクライブし、それに応じてデータを処理できます。

IDaaS は、IDaaS の変更をアプリケーションに同期するための便利で安全な方法を提供します。アプリケーションを IDaaS と迅速に統合して、アプリケーションが同期リクエストを受信できるようにすることができます。

この方法は、イベントコールバックメカニズムを使用して実装されます。

IDaaS では、フォローするイベント（アカウント作成イベントなど）を設定できます。イベントが発生すると、HTTP POST を使用して、イベントサブスクライバーに同期リクエストが自動的に送信されます。

イベントメカニズムは、次の 2 つの部分で構成されています。

イベントのサブスクライブ: IDaaS コンソールにログオンし、フォローする IDaaS イベントを設定します。
イベントコールバックの受信: 開発者は、必要に応じてアカウント同期を実装するために、アプリケーションを IDaaS と統合する必要があります。

イベントのサブスクライブ

IDaaS でアプリケーションを作成した後、[プロビジョニング] をクリックしてアカウント同期を設定します。

詳細については、「プロビジョニングでアプリケーションの IDaaS アカウントを同期する」をご参照ください。

アプリケーションを 1 つ以上のイベントにサブスクライブできます。次の図は、フォローできるイベントを示しています。

選択したイベントが発生すると、IDaaS はアプリケーションにリクエストを送信します。

コールバックの受信

選択したイベントが発生すると、IDaaS は設定された 同期リクエストを受信するための URL に POST リクエストを送信します。

次のコードは、リクエストパラメータを設定する方法の例を示しています。

Content-Type: application/json;charset=utf-8

// IDaaS からの POST リクエストの本文の例。アプリケーションはパラメータを取得した後、署名を確認します。
{
 "event":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

すべてのパラメータは、JSON Web Token （JWT）形式の event フィールドに渡されます。これには署名が含まれています。詳細については、「RFC 7515: JSON Web Signature (JWS)」をご参照ください。

イベント形式

さまざまな言語の汎用オープンソースツールを使用して、JWT 情報を解析する必要があります。

テスト目的で、https://jwt.io/ のフィールドに JWT 形式の値を貼り付けて、コンテンツを表示することもできます。

event 値は、header と payload の 2 つの部分で構成されています。

header の例:

{
    "kid": "KEYH1zR7XLCGcHw1hzhkCqVjnuyaAJUf6yMR",
    "typ": "JWT",
    "alg": "RS256"
}

payload の例:

{
  "iss":"urn:alibaba:idaas:app:event", 
  "sub":"idaas-121313", 
  "aud":"app_12131313",
  "exp":1640966400, 
  "iat":1640966400, 
  "jti": "cNetm9OD5bXqfVfdvqGMYw",
  "dataEncrypted":false,
  "cipherData":"",    
  "plainData":{
    "aliUid":1231313,  // Alibaba Cloud アカウントの ID。
    "instanceId":"instance ID",  // インスタンスの ID。
    "eventVersion":"V1.0",  // イベントのバージョン番号。
    "eventData":[
      {
        "eventId":"",     // イベントの ID。
        "eventType":"",   // イベントのタイプ。
        "eventTime":121313,  // イベントが発生した時刻。
        "bizId":"business ID",  // ビジネスの ID。ビジネスが組織の場合、値は組織の ID です。
        "bizData":{}       // 特定のデータの詳細。このフィールド値はイベントタイプによって異なります。詳細については、アドレス帳イベントを参照してください。
      }
    ]   
  }
}

次の表に、含まれるフィールドを示します。

	パラメータ	位置	タイプ	説明
header	alg	header	String	固定値: RS256。使用される SHA-256 RSA 署名。
header	kid	header	String	IDaaS によって発行された公開鍵と秘密鍵のペアの ID。 kid の公開鍵は署名検証に使用されます。 IDaaS では、同期のために公開鍵と秘密鍵のペアをローテーションできます。同期された公開鍵と秘密鍵のペアは変更されません。
payload	iss	payload	String	固定値: urn:alibaba:idaas:app:event イベント通知が IDaaS によって開始されたことを示します。
	sub	payload	String	IDaaS インスタンスの ID。
	aud	payload	String	IDaaS アプリケーションの ID。
	exp	payload	Long	イベントの有効期限。単位: ミリ秒。デフォルト値は作成時刻の 30 分後です。現在の時刻が有効期限より後の場合、リクエストの解析時にエラーが発生し、アプリケーションはイベントが期限切れであると判断します。
	iat	payload	Long	イベントの作成時刻。単位: ミリ秒。現在の時刻が作成時刻より前の場合、リクエストの解析時にエラーが発生し、アプリケーションはイベントが無効であると判断します。
	data_encrypted	payload	Boolean	イベントデータが転送のために暗号化されているかどうかを示します。
	cipher_data	payload	String	暗号化が有効になっている場合、このフィールドは空ではありません。このフィールドは、イベントデータの暗号化された暗号文です。コンテンツを表示するには、復号化する必要があります。
	plain_data	payload	Object	暗号化が無効になっている場合、このフィールドは空ではありません。このフィールドには、すべてのイベントデータが含まれています。

署名検証

イベント情報が IDaaS によって発行されたことを確認するには、JWT 署名を検証する必要があります。署名検証により、リクエストの偽造を防ぎます。

同期ページで、公開鍵エンドポイント を取得して、JWT 署名とアプリケーションに送信されたイベントのソースを検証できます。署名検証には、プログラミング言語のオープンソース JWT ツールキットを使用することをお勧めします。

データの復号化 (オプション)

イベント同期データの暗号化転送がサポートされています。暗号化されたフィールドは、payload の cipher_data フィールドに渡されます。

{
    ...
    "cipher_data": "ZePq7ckODWnL54vqZc3kTw0vF7tjvIRZjqqy/gZm9oTEt71WMufD9swlmHzZkniSqyDGQpkmMRLCXz9gzRJ4BY2RroLUPQW8ZDPSfmJKEf2m2w6wY1twoRlnHLoFCVhravsvN0afBqmxd3eK5tHd05Ze6MLOXS3fqxqH61dGAm2mwecvAFPRrKVeg6JXBYUvA2Uu6dmCOP3y938kFdhodD13O05MBIqWghq569wYvVjKMFMcnsZqmGGKXN0vRFhg+SR16sr24b1X/gQDbNqyMDICB9k3QMe09dOodwNEwvgxbf1v4PbyCRX1P9UO74nDQaWROWZFplE7qP/JMy3pBr0pxW+hJS9u/Zpvj/hvLlhBTAZkmhAKDKxlrYztqrgJbr4VOUv8mlqxWjDK4I7VZugODJMSwi1HdjXL+wlMzPMOeH8rkDFU+b5VH3dsxg3hZ64Ukd7exB62QyyeIJpfk0d57xw8UACiSsXadexQYpJPDycVdmJ7FAmIhxbJ8I6w9Kcv9U5sKybUz1YA8tONAw=="
    ...
}

この機能を有効にすると、暗号化キーを入力するか、暗号化キーを生成できます。IDaaS がイベントコールバックリクエストを送信する前に、IDaaS はこのキーを使用して転送前にすべてのリクエストデータを暗号化します。

IDaaS は対称暗号化に AES-256 アルゴリズムを使用し、JSON Web Encryption (JWE) 形式でイベントを暗号化します。

アプリケーションは、同期データを取得するために復号化に同じキーを使用する必要があります。

詳細については、「Java を使用してユーザー同期を実装するためのアプリケーションの統合」をご参照ください。

レスポンス

アプリケーションは、IDaaS の仕様に従ってイベントの処理結果を返す必要があります。IDaaS は結果を記録し、返された情報に基づいてデータを処理します。

成功レスポンス

リクエストが処理された場合、アプリケーションは次の形式で eventId と結果を返す必要があります。

返されるフィールド	データ型	説明
successEvents	Array	同期が成功しました。
skippedEvents	Array	同期はスキップされました。(例: アプリケーションはアカウント削除イベントを受信しましたが、ユーザーはアプリケーションシステムに存在しません。)
failedEvents	Array	同期に失敗しました。
retriedEvents	Array	同期は最大 5 回再試行されます。
-eventId	String	IDaaS のイベントの ID。このフィールドが送信されないか、無効な eventId が送信された場合、再試行がトリガーされます。
-eventCode	String	返されたエラーコード。IDaaS はトラブルシューティングのために結果を記録します。eventCode はカスタマイズできます。
-eventMessage	String	返されたエラーメッセージ。IDaaS はトラブルシューティングのために結果の原因を記録します。eventMessage はカスタマイズできます。

成功レスポンスの例

{
    "successEvents": [
        {
            "eventId": "イベントの ID",
            "eventCode": "SUCCESS",
            "eventMessage": "SUCCESS"
        }
    ],
    "skippedEvents": [
        {
            "eventId": "イベントの ID",
            "eventCode": "返されたエラーコード",
            "eventMessage": "返されたエラーメッセージ"
        }
    ],
    "failedEvents": [
        {
            "eventId": "イベントの ID",
            "eventCode": "返されたエラーコード",
            "eventMessage": "返されたエラーメッセージ"
        }
    ],
    "retriedEvents": [
        {
            "eventId": "イベントの ID",
            "eventCode": "返されたエラーコード",
            "eventMessage": "返されたエラーメッセージ"
        }
    ]
}

重要

アプリケーションは、リクエストを受信した後、10 秒以内に HTTP 200 ステータスコードでリクエストに応答する必要があります。そうでない場合、IDaaS は同期が失敗したと判断し、それぞれ 1 秒、5 秒、10 秒、10 秒、10 秒の間隔で最大 5 回イベントのプッシュを再試行します。

失敗レスポンス

処理に失敗した場合、アプリケーションは HTTP 403、429、または 500 ステータスコードを返す必要があります。

処理に失敗した場合、次のパラメータが返されます。

パラメータ	データ型	説明
error	String	返されたエラーコード。
error_description	String	返されたエラーメッセージ。

一般的に、次のエラーコードが返されます。

エラーコード	HTTP ステータスコード	説明
invalid_token	403	JWS トークンが無効です。
too_many_request	429	ビジネスがビジー状態でこのエラーコードを返した場合、IDaaS はスロットリングポリシーを使用します。
internal_error	500	内部エラーを示します。IDaaS は同期を自動的に再試行します。

エラーレスポンスの例

{
     "error": "invalid_token",
     "error_description": "JWS トークンが無効です。"
}