文档

账户同步接入概述

更新时间:

背景介绍

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 值包含两大部分,headerpayload.

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":{}       //具体的数据详情,不同事件类型该字段不同。可参考通讯录事件
      }
    ]   
  }
}

其中包含的字段具体如下:

参数名称

参数位置

参数类型

参数说明

header

alg

header

String

固定值:RS256

代表采用SHA-256的RSA签名

kid

header

String

IDaaS 颁发的公私钥对 key 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

event 的过期时间,单位 ms,默认为创建时间之后 30 分钟。

若当前时间超过过期时间,应用解析时应该报错,判断过期。

iat

payload

Long

event 的创建时间,单位 ms。若当前时间早于创建时间,应用解析时应该报错,判断无效。

data_encrypted

payload

Boolean

事件数据是否为加密传输。

cipher_data

payload

String

开启加密时不为空。

该字段是加密后密文事件数据,需解密后查看内容。

plain_data

payload

Object

关闭加密时不为空。

包含所有事件数据。

数据验签

请先对 JWT 验签,确认对应 event 事件信息是由 IDaaS 签发。若不进行验证,任何人都将可以仿造请求。

您可以通过同步菜单中的验签公钥端点,获取到验签 JWT 使用的公钥信息,并使用其对发送给应用的事件内容进行有效来源验证。我们推荐您使用对应开发语言的开源 JWT 工具包进行验签工作。不在此赘述。

数据解密(可选)

IDaaS 支持对推送的事件数据进行加密传输,加密后字段将在payloadcipher_data字段传递。

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

开启该特性后,您可以自主填写加密密钥,也可由 IDaaS 生成密钥。IDaaS 发出事件回调请求前,会使用该密钥将请求数据全部加密后传输。

IDaaS 会使用 AES-256 算法对称加密,并采用 JWE 格式对事件进行加密。

应用需要使用同样的密钥解密,才能获取同步数据。

开发对接可以参考 Java 应用接入账户同步示例

响应返回

应用需负责按照 IDaaS 规范,返回事件处理结果。IDaaS 将记录结果,并依照返回信息进行后续处理。

执行成功

若请求处理一切正常,必须返回 eventId 及对应的结果,格式如下:

返回字段

数据类型

描述

successEvents

Array

同步成功,返回该事件

skippedEvents

Array

同步跳过(场景举例:应用接收到删除账户事件,但账户在应用系统中已不存在,则可以返回跳过。)

failedEvents

Array

同步失败,返回该事件

retriedEvents

Array

同步重试,若返回,该事件将重试。最大重试次数5次

-eventId

String

事件 ID,必须返回 IDaaS 当次事件 ID。

不发送或传输错误 eventId 将触发重试。

-eventCode

String

错误码,IDaaS 将记录结果,便于排查问题。您可自定义 eventCode。

-eventMessage

String

错误描述,IDaaS 将记录结果原因,便于排查问题。您可自定义 eventMessage。

正常返回结果示例:

{
    "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": "错误描述"
        }
    ]
}
重要

收到请求后,需要在 10 秒内以 HTTP 200 状态码响应该请求,否则 IDaaS 会视此次推送失败并以1s、5s、10s、10s、10s 的间隔重新推送事件,最多重试 5 次。

执行失败

若处理失败,返回 HTTP 状态码必须是 4XX 或者 5XX。

处理失败后返回的参数如下:

参数名称

数据类型

描述

error

String

错误码

error_description

String

错误描述

针对通用,建议参考如下错误码返回:

错误码

HTTP状态码

描述

invalid_token

403

jws token校验不合法

too_many_request

429

业务方处理繁忙返回该错误后,idaas会进行流控策略进行降级处理

internal_error

500

内部错误,idaas会自动重试

异常返回结果示例

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

  • 本页导读 (0)
文档反馈