背景介紹

IDaaS 支援自研應用對接，實現 IDaaS 到應用的組織/賬戶同步。

若希望實現應用到 IDaaS 的賬戶同步，請參考 應用開發 API 說明。

應用同步配置請參考：賬戶同步 - IDaaS 同步到應用。本篇文檔介紹應用按照 IDaaS 規範完成賬戶同步對接。

• 一致性依賴：可能有一系列相關方，依賴於您的應用中的身份資料，進行營銷或驗證，由此希望能夠及時地從 IDaaS 同步賬戶的變化。例如在使用者入職時，在 IDaaS 中建立賬戶，HR 應用需要近乎同時建立賬戶，才不會耽擱入職流程。可以通過訂閱 賬戶建立 事件實現。

• 即時性要求：您的應用需要及時響應使用者的操作。例如使用者登入系統後修改了手機後，你的應用需要及時更新該使用者的手機號，可以通過訂閱 賬戶更新 事件實現。

事件回調機制說明

以上是兩個簡單的使用情境，開發人員可以根據不同需求，訂閱不同的事件，進行不同的處理。

為了滿足客戶的快速對接需求，我們提供了一套由 IDaaS 定義的、整合便捷、傳輸安全的 IDaaS 到應用同步方式，應用可以快速對接，接收同步請求。

這套機制通過事件回調機制實現。

在 IDaaS 中，您需要配置關注的事件（例如賬戶建立），當對應事件觸發後，將自動向事件訂閱者通過 HTTP POST 發送同步請求。

事件分為兩個部分：

• 訂閱事件：在 IDaaS 管理主控台完成，配置關注的 IDaaS 事件。

• 接收事件：需要開發人員按照要求，進行對接。

訂閱事件

在 IDaaS 中建立應用後，可以前往【賬戶同步】菜單，進行應用賬戶同步配置。

具體配置方式，請參考賬戶同步 - IDaaS 同步到應用。

在下方配置中，您可以勾選當前應用關注的回調事件。

當事件發生時，IDaaS 將嚮應用發出請求。

接收回調

當事件發生時，IDaaS 會向配置的同步接收地址發送 POST 請求。

請求參數參考如下：

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

//IDaaS post 請求body體樣本。應用拿到參數後進行驗簽
{
 "event":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

所有參數均在event欄位中傳遞，傳遞的內容是包含簽名的 JWT 格式（參考 RFC 7515 JWS)，

事件格式

您需要使用各語言的通用開源工具，對 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,  //阿里雲帳號Uid
    "instanceId":"執行個體ID",  //執行個體id
    "eventVersion":"V1.0",  //版本號碼
    "eventData":[
      {
        "eventId":"",     //事件id
        "eventType":"",   //事件類型
        "eventTime":121313,  //事件實際發生的事件
        "bizId":"業務資料id",  //業務資料id。若是組織，則為組織id
        "bizData":{}       //具體的資料詳情，不同事件類型該欄位不同。可參考通訊錄事件
      }
    ]   
  }
}

其中包含的欄位具體如下：

資料驗簽

請先對 JWT 驗簽，確認對應 event 事件資訊是由 IDaaS 簽發。若不進行驗證，任何人都將可以仿造請求。

您可以通過同步菜單中的驗簽公開金鑰端點，擷取到驗簽 JWT 使用的公開金鑰資訊，並使用其對發送給應用的事件內容進行有效來源驗證。我們推薦您使用對應開發語言的開源 JWT 工具包進行驗簽工作。不在此贅述。

資料解密（可選）

IDaaS 支援對推送的事件數目據進行加密傳輸，加密後欄位將在payload中cipher_data欄位傳遞。

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

開啟該特性後，您可以自主填寫加密金鑰，也可由 IDaaS 產生密鑰。IDaaS 發出事件回調請求前，會使用該密鑰將請求資料全部加密後傳輸。

IDaaS 會使用 AES-256 演算法對稱式加密，並採用 JWE 格式對事件進行加密。

應用需要使用同樣的密鑰解密，才能擷取同步資料。

開發對接可以參考 Java 應用接入賬戶同步樣本。

響應返回

應用需負責按照 IDaaS 規範，返回事件處理結果。IDaaS 將記錄結果，並依照返回資訊進行後續處理。

執行成功

若請求處理一切正常，必須返回 eventId 及對應的結果，格式如下：

正常返回結果樣本：

{
    "successEvents": [
        {
            "eventId": "事件ID",
            "eventCode": "SUCCESS",
            "eventMessage": "SUCCESS"
        }
    ],
    "skippedEvents": [
        {
            "eventId": "事件ID",
            "eventCode": "跳過code",
            "eventMessage": "跳過描述"
        }
    ],
    "failedEvents": [
        {
            "eventId": "事件ID",
            "eventCode": "錯誤code",
            "eventMessage": "錯誤描述"
        }
    ],
    "retriedEvents": [
        {
            "eventId": "事件ID",
            "eventCode": "錯誤code",
            "eventMessage": "錯誤描述"
        }
    ]
}

執行失敗

若處理失敗，返回 HTTP 狀態代碼必須是 4XX 或者 5XX。

處理失敗後返回的參數如下：

針對通用，建議參考如下錯誤碼返回：

異常返回結果樣本

{
     "error": "invalid_token",
     "error_description": "jws token校正不合法"
}