背景介紹

IDaaS 支持自研應用對接，實現(xiàn) IDaaS 到應用的組織/賬戶同步。

若希望實現(xiàn)應用到 IDaaS 的賬戶同步，請參考 應用開發(fā) API 說明。

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

• 一致性依賴：可能有一系列相關方，依賴于您的應用中的身份數(shù)據(jù)，進行營銷或驗證，由此希望能夠及時地從 IDaaS 同步賬戶的變化。例如在用戶入職時，在 IDaaS 中創(chuàng)建賬戶，HR 應用需要近乎同時創(chuàng)建賬戶，才不會耽擱入職流程。可以通過訂閱 賬戶創(chuàng)建 事件實現(xiàn)。

• 實時性要求：您的應用需要及時響應用戶的操作。例如用戶登錄系統(tǒng)后修改了手機后，你的應用需要及時更新該用戶的手機號，可以通過訂閱 賬戶更新 事件實現(xiàn)。

事件回調機制說明

以上是兩個簡單的使用場景，開發(fā)者可以根據(jù)不同需求，訂閱不同的事件，進行不同的處理。

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

這套機制通過事件回調機制實現(xiàn)。

在 IDaaS 中，您需要配置關注的事件（例如賬戶創(chuàng)建），當對應事件觸發(fā)后，將自動向事件訂閱者通過 HTTP POST 發(fā)送同步請求。

事件分為兩個部分：

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

• 接收事件：需要開發(fā)者按照要求，進行對接。

訂閱事件

在 IDaaS 中創(chuàng)建應用后，可以前往【賬戶同步】菜單，進行應用賬戶同步配置。

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

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

當事件發(fā)生時，IDaaS 將向應用發(fā)出請求。

接收回調

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

請求參數(shù)參考如下：

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

//IDaaS post 請求body體示例。應用拿到參數(shù)后進行驗簽
{
 "event":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

所有參數(shù)均在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,  //事件實際發(fā)生的事件
        "bizId":"業(yè)務數(shù)據(jù)id",  //業(yè)務數(shù)據(jù)id。若是組織，則為組織id
        "bizData":{}       //具體的數(shù)據(jù)詳情，不同事件類型該字段不同。可參考通訊錄事件
      }
    ]   
  }
}

其中包含的字段具體如下：

數(shù)據(jù)驗簽

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

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

數(shù)據(jù)解密（可選）

IDaaS 支持對推送的事件數(shù)據(jù)進行加密傳輸，加密后字段將在payload中cipher_data字段傳遞。

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

開啟該特性后，您可以自主填寫加密密鑰，也可由 IDaaS 生成密鑰。IDaaS 發(fā)出事件回調請求前，會使用該密鑰將請求數(shù)據(jù)全部加密后傳輸。

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

應用需要使用同樣的密鑰解密，才能獲取同步數(shù)據(jù)。

開發(fā)對接可以參考 Java 應用接入賬戶同步示例。

響應返回

應用需負責按照 IDaaS 規(guī)范，返回事件處理結果。IDaaS 將記錄結果，并依照返回信息進行后續(xù)處理。

執(zhí)行成功

若請求處理一切正常，必須返回 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": "錯誤描述"
        }
    ]
}

執(zhí)行失敗

若處理失敗，返回 HTTP 狀態(tài)碼必須是 4XX 或者 5XX。

處理失敗后返回的參數(shù)如下：

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

異常返回結果示例

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