Identity as a Service:アカウント同期連携の概要

背景情報

Identity as a Service (IDaaS) は、カスタムアプリケーションとの連携をサポートしており、IDaaS からご利用のアプリケーションに組織とアカウントを同期できます。ご利用のアプリケーションから IDaaS にアカウントを同期する方法については、「アプリケーション開発の API リファレンス」をご参照ください。

アプリケーションの同期設定については、「アカウント同期 - IDaaS からアプリケーションへの同期」をご参照ください。このトピックでは、IDaaS の仕様に従ってアカウント同期のためにアプリケーションを連携する方法について説明します。

• アカウントの変更は、IDaaS から迅速に同期する必要があります。たとえば、従業員のオンボーディング中に IDaaS でアカウントが作成された場合、人事アプリケーションは、オンボーディングプロセスの遅延を防ぐために、ほぼ同時に対応するアカウントを作成する必要があります。これを実現するには、アカウント作成イベントをサブスクライブします。

• ご利用のアプリケーションは、ユーザーの操作に迅速に応答する必要があります。たとえば、ユーザーがログイン後に携帯電話番号を更新した場合、ご利用のアプリケーションはこの変更をすぐに反映する必要があります。そのためには、アカウント更新イベントをサブスクライブします。

イベントコールバックの仕組み

上記は 2 つの簡単なユースケースです。特定のニーズに応じて、さまざまなイベントをサブスクライブして処理できます。

IDaaS は、データをアプリケーションに同期するための標準化された安全で便利なメソッドを提供します。このメソッドにより、ご利用のアプリケーションは最小限の設定で同期リクエストを受信できます。

このシステムは、イベントコールバックの仕組みに基づいて構築されています。

IDaaS では、アカウント作成など、モニターしたいイベントを設定します。指定されたイベントが発生すると、IDaaS は自動的にイベントのサブスクライバーに HTTP POST リクエストを送信します。

このプロセスは、主に 2 つの部分で構成されます。

• イベントのサブスクライブ： IDaaS コンソールでモニターしたいイベントを設定します。

• イベントの受信： 仕様に従って受信イベントデータを処理するようにアプリケーションを開発します。

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

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

詳細な設定手順については、「IDaaS からアプリケーションへの同期 - SCIM」をご参照ください。

コールバックイベントの設定では、アプリケーションでサブスクライブしたいイベントを選択できます。サブスクライブしたイベントが発生すると、IDaaS はご利用のアプリケーションにリクエストを送信します。

コールバックの受信

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

次のコードは、リクエストのサンプルを示しています。

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

// IDaaS からの POST リクエストの本文の例。ご利用のアプリケーションは、パラメーター受信後に署名を検証します。
{
 "event":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

すべてのパラメーターは event フィールドで渡されます。このフィールドの値は、RFC 7515 JWS で指定されている署名付きの JSON Web トークン (JWT) です。

イベントフォーマット

JWT を解析するには、ご利用のプログラミング言語用の標準的なオープンソースライブラリを使用する必要があります。

テスト目的で、JWT の値を https://jwt.io/ のようなツールに貼り付けて、その内容を検査できます。

event の値は、header と payload で構成されます。

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 data ID",  // ビジネスデータ ID。組織の場合、これは組織 ID です。
        "bizData":{}       // 詳細データ。このフィールドはイベントタイプによって異なります。詳細については、アドレス帳イベントのリファレンスをご参照ください。
      }
    ]   
  }
}

次の表に、イベントのフィールドを示します。

署名検証

まず、JWT 署名を検証して、event が IDaaS によって発行されたことを確認します。この検証をスキップすると、悪意のあるアクターがリクエストを偽造する可能性があります。

同期メニューの [公開鍵エンドポイント] から JWT 署名の検証に使用する公開鍵情報を取得し、それを使用してアプリケーションに送信されたイベントコンテンツが有効なソースからのものであることを検証できます。署名検証を実行するには、開発言語用のオープンソース JWT ツールキットを使用することを推奨します。

データ復号 (任意)

IDaaS はイベントデータの暗号化伝送をサポートしています。有効にすると、暗号化されたデータは payload の cipherData フィールドで渡されます。

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

この機能を有効にした後、独自の暗号鍵を提供するか、IDaaS に生成させることができます。イベントコールバックを送信する前に、IDaaS はこのキーを使用してリクエストデータ全体を暗号化します。

IDaaS は、AES-256 対称暗号化アルゴリズムと JSON Web Encryption (JWE) フォーマットを使用してイベントを暗号化します。

ご利用のアプリケーションは、同じキーを使用してデータを復号する必要があります。

開発例については、「アカウント同期のための Java アプリケーション連携例」をご参照ください。

応答フォーマット

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

成功応答

リクエストが正常に処理された場合は、HTTP 200 ステータスコードと、eventId および処理結果を含むレスポンスボディを返す必要があります。フォーマットは次のとおりです。

成功応答のサンプル：

{
    "successEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "SUCCESS",
            "eventMessage": "SUCCESS"
        }
    ],
    "skippedEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "A skip code",
            "eventMessage": "A skip message"
        }
    ],
    "failedEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "An error code",
            "eventMessage": "An error message"
        }
    ],
    "retriedEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "An error code",
            "eventMessage": "An error message"
        }
    ]
}

失敗応答

処理が失敗した場合は、4xx または 5xx の範囲の HTTP ステータスコードを返す必要があります。

失敗時にレスポンスボディで返すパラメーターは次のとおりです。

一般的な失敗シナリオには、次のエラーコードを使用することを推奨します。

失敗応答のサンプル：

{
     "error": "invalid_token",
     "error_description": "The JWS token is invalid."
}