账户同步接入概述

本文概述了阿里云应用身份服务(EIAM)的开发参考,涵盖核心功能、使用场景及接入指南,帮助开发者快速集成统一身份管理与单点登录能力。

背景介绍

IDaaS支持自研应用对接,实现IDaaS到应用的组织/账户同步。若希望实现应用到IDaaS的账户同步,请参考应用开发API说明

应用同步配置请参考:账户同步-IDaaS同步到应用。本篇文档介绍应用按照IDaaS规范完成账户同步对接。

  • 一致性依赖:可能有一系列相关方,依赖于您的应用中的身份数据,进行营销或验证,由此希望能够及时地从IDaaS同步账户的变化。例如在用户入职时,在IDaaS中创建账户,HR应用需要近乎同时创建账户,才不会耽搁入职流程。可以通过订阅账户创建事件实现。

  • 实时性要求:您的应用需要及时响应用户的操作。例如用户登录系统后修改了手机后,你的应用需要及时更新该用户的手机号,可以通过订阅账户更新事件实现。

事件回调机制说明

以上是两个简单的使用场景,开发者可以根据不同需求,订阅不同的事件,进行不同的处理。

为了满足客户的快速对接需求,我们提供了一套由IDaaS定义的、集成便捷、传输安全的IDaaS到应用同步方式,应用可以快速对接,接收同步请求。

这套机制通过事件回调机制实现。

IDaaS中,您需要配置关注的事件(例如账户创建),当对应事件触发后,将自动向事件订阅者通过HTTP POST发送同步请求。

事件分为两个部分:

  • 订阅事件:在IDaaS管理控制台完成,配置关注的IDaaS事件。

  • 接收事件:需要开发者按照要求,进行对接。

订阅事件

IDaaS中创建应用后,可以前往账户同步菜单,进行应用账户同步配置。

具体配置方式,请参考IDaaS同步到应用-SCIM

在下方配置中,您可以勾选当前应用关注的回调事件。

image

当事件发生时,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-256RSA签名

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