本文概述了阿里云应用身份服务(EIAM)的开发参考,涵盖核心功能、使用场景及接入指南,帮助开发者快速集成统一身份管理与单点登录能力。
背景介绍
IDaaS支持自研应用对接,实现IDaaS到应用的组织/账户同步。若希望实现应用到IDaaS的账户同步,请参考应用开发API说明。
应用同步配置请参考:账户同步-IDaaS同步到应用。本篇文档介绍应用按照IDaaS规范完成账户同步对接。
一致性依赖:可能有一系列相关方,依赖于您的应用中的身份数据,进行营销或验证,由此希望能够及时地从IDaaS同步账户的变化。例如在用户入职时,在IDaaS中创建账户,HR应用需要近乎同时创建账户,才不会耽搁入职流程。可以通过订阅账户创建事件实现。
实时性要求:您的应用需要及时响应用户的操作。例如用户登录系统后修改了手机后,你的应用需要及时更新该用户的手机号,可以通过订阅账户更新事件实现。
事件回调机制说明
以上是两个简单的使用场景,开发者可以根据不同需求,订阅不同的事件,进行不同的处理。
为了满足客户的快速对接需求,我们提供了一套由IDaaS定义的、集成便捷、传输安全的IDaaS到应用同步方式,应用可以快速对接,接收同步请求。
这套机制通过事件回调机制实现。
在IDaaS中,您需要配置关注的事件(例如账户创建),当对应事件触发后,将自动向事件订阅者通过HTTP POST
发送同步请求。
事件分为两个部分:
订阅事件:在IDaaS管理控制台完成,配置关注的IDaaS事件。
接收事件:需要开发者按照要求,进行对接。
订阅事件
在IDaaS中创建应用后,可以前往账户同步菜单,进行应用账户同步配置。
具体配置方式,请参考IDaaS同步到应用-SCIM。
在下方配置中,您可以勾选当前应用关注的回调事件。
当事件发生时,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":{} //具体的数据详情,不同事件类型该字段不同。可参考通讯录事件
}
]
}
}
其中包含的字段具体如下:
参数名称 | 参数位置 | 参数类型 | 参数说明 | |
header | alg | header | String | 固定值:RS256 代表采用SHA-256的RSA签名 |
kid | header | String | IDaaS颁发的公私钥对key ID。 验签时需要使用该 IDaaS暂不支持同步用公私钥轮转,同步公私钥信息不会变化。 | |
payload | iss | payload | String | 固定值: 代表是由IDaaS发起的事件订阅通知。 |
sub | payload | String | 客户的IDaaS实例ID | |
aud | payload | String | 客户的IDaaS应用ID | |
exp | payload | Long |
若当前时间超过过期时间,应用解析时应该报错,判断过期。 | |
iat | payload | Long |
| |
data_encrypted | payload | Boolean | 事件数据是否为加密传输。 | |
cipher_data | payload | String | 开启加密时不为空。该字段是加密后密文事件数据,需解密后查看内容。 | |
plain_data | payload | Object | 关闭加密时不为空。包含所有事件数据。 |
数据验签
请先对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 | Array | 同步成功,返回该事件 |
skippedEvents | Array | 同步跳过(场景举例:应用接收到删除账户事件,但账户在应用系统中已不存在,则可以返回跳过。) |
failedEvents | Array | 同步失败,返回该事件 |
retriedEvents | Array | 同步重试,若返回,该事件将重试。最大重试次数5次 |
-eventId | String | 事件ID,必须返回IDaaS当次事件ID。 不发送或传输错误 |
-eventCode | String | 错误码,IDaaS将记录结果,便于排查问题。您可自定义 |
-eventMessage | String | 错误描述,IDaaS将记录结果原因,便于排查问题。您可自定义 |
正常返回结果示例:
{
"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 |
|
too_many_request | 429 | 业务方处理繁忙返回该错误后,idaas会进行流控策略进行降级处理 |
internal_error | 500 | 内部错误,idaas会自动重试 |
异常返回结果示例
{
"error": "invalid_token",
"error_description": "jws token校验不合法"
}