背景介绍

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校验不合法"
}