SCIM同步接口 – 飞天云信开发文档

获取accessToken

HTTP Method：GET
请求地址：https://serverurl/SCIM/v2/token

接口功能：获取SCIM API访问令牌，SCIM API 目前采用 OAuth2.0 进行授权认证，采用 client_credentials 模式。

请求参数：

参数名	必选	类型	参数说明
client_id	是	String	客户端ID
client_secret	是	String	客户端秘钥

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述
access_token	是	String	访问令牌
refresh_token	是	String	刷新令牌
expires_in	是	Int	访问令牌有效期

成功示例：

{
   "errcode":200,
   "errmsg":"获取成功",
   "access_token": "25dd7965de493fa356a4cf7d53a034b217ffd7e8",
   "refresh_token": "2ead837826ab85f9681f23bccb959a23617f68ce",
   "expires_in": 7200
}

刷新accessToken

HTTP Method：GET
请求地址：https://serverurl/SCIM/v2/token/refreshToken

接口功能：使用刷新令牌换取新访问令牌。

请求参数：

参数名	必选	类型	参数说明
refresh_token	是	String	刷新令牌

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述
access_token	是	String	访问令牌
refresh_token	是	String	刷新令牌
expires_in	是	Int	访问令牌有效期

成功示例：

{
    "errcode":200,
    "errmsg":"获取成功",
    "access_token": "25dd7965de493fa356a4cf7d53a034b217ffd7e8",
    "refresh_token": "2ead837826ab85f9681f23bccb959a23617f68ce",
}

创建机构

HTTP Method：POST
请求地址：https://serverurl/SCIM/v2/Organizations
Header Content-Type：application/json

接口功能：创建组织机构。

请求参数：

参数名	必选	类型	参数说明
externalId	否	String	外部源ID
displayName	是	String	组织机构名，同一层级下唯一
code	否	String	组织机构编码，不为空时唯一
parent	是	String	父组织机构 id
description	否	String	描述

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述
id	否	String	机构ID

成功示例：

{
    "errcode":200,
    "errmsg": "created",
    "id": "52E4E27B313267C1288944EE6DA4AAD556C23A9EC06B4F04AF53"
}

删除机构

HTTP Method：DELETE
请求地址：https://serverurl/SCIM/v2/Organizations/{orgId}

接口功能：删除组织机构。

请求参数：

参数名	必选	类型	参数说明
orgId	是	String	组织机构ID，创建时的ID。该参数放到URL中{orgId}位置

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述

成功示例：

{
    "errcode":200,
    "errmsg":"deleted"
}

更新机构

HTTP Method：PUT
请求地址：https://serverurl/SCIM/v2/Organizations/{orgId}
Header Content-Type：application/json

接口功能：更新组织机构。

请求参数：

参数名	必选	类型	参数说明
orgId	是	String	组织机构ID，创建时的ID。该参数放到URL中{orgId}位置
displayName	否	String	组织机构名，同一层级下唯一
code	否	String	组织机构编码，不为空时唯一
parent	否	String	父组织机构 id
description	否	String	描述

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述

成功示例：

{
    "errcode":200,
    "errmsg":"updated"
}

获取机构信息

HTTP Method：GET
请求地址：https://serverurl/SCIM/v2/Organizations/{orgId}

接口功能：获取组织机构信息。

请求参数：

参数名	必选	类型	参数说明
orgId	是	String	机构ID，创建时的ID。该参数放到URL中{orgId}位置

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述
meta	是	Object	SCIM元数据信息，格式为： `{ "created":"2022-03-12T15:36:40.000+08:00", "resourceType": "Organization,"version":"2.0" }`
schemas	是	StringArray	scim 的 schema，返回字符串数组固定值：urn:ietf:params:scim:schemas:core:2.0:Organization
externalId	是	String	外部源ID
code	是	String	机构编码，不为空时唯一
displayName	是	String	机构名，同一层级下唯一
order	是	Int	机构同一层级顺序
parent	是	String	父机构 id
id	是	String	组织机构ID

成功示例：

{
    "errcode":200,
    "errmsg":"ok",
    "meta": {
		"created": "2022-03-12T14:06:34.000+08:00",
		"resourceType": "Organization",
		"version": "2.0"
	},
	"schemas": [
		"urn:ietf:params:scim:schemas:core:2.0:Organization"
	],
	"externalId": "278375e3-ead0-4f61-b27c-b4462e4b2115",
	"code": "3650417845",
	"displayName": "测试有限公司",
	"order": 1,
	"id": "3650417845",
	"parent": "0"
}

查询机构列表

HTTP Method：GET
请求地址：https://serverurl/SCIM/v2/Organizations?startIndex=1&count=10&filter=displayName eq 测试有限公司

接口功能：根据分页信息和过滤条件查询组织机构信息。返回结果在同一层级不保证顺序，不存在递归查询。业务端在使用时，需要全量拉取到所有的组织机构，并根据 parent 来确定组织机构之间的父子关系、order 来确定同一层级的组织机构之间的顺序。

请求参数：

参数名	必选	类型	参数说明
startIndex	否	Int	开始下标。默认：1
count	否	Int	每一页查询记录数。默认：100；最大 100
filter	否	String	查询条件，仅支持机构名、更新时间单一条件查询，不支持复杂的逻辑条件查询。操作符仅支持 eq、gt，filter 条件符合SCIM语法

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述
totalResults	是	Int	总记录数
itemsPerPage	是	Int	每页大小，等于入参的 count
startIndex	是	Int	入参的 startIndex
schemas	是	StringArray	SCIM的Schemas，返回字符串数组固定值：[“urn:ietf:params:scim:api:messages:2.0:ListResponse”]
Resources	是	Array	返回的资源数组

Resources数据结构
Resources	参数名	必选	类型	参数说明
	id	是	String	组织机构ID
	externalId	是	String	外部ID
	meta	是	Object	SCIM元数据信息，格式为： `{ "created":"2022-03-12T15:36:40.000+08:00", "version": "2.0", "resourceType": "Organization" }`
	schemas	是	StringArray	SCIM的 Schemas，返回字符串数组固定值：[“urn:ietf:params:scim:schemas:core:2.0:Organization “]
	code	是	String	机构编码，不为空时唯一
	displayName	是	String	机构名，同一层级下唯一
	order	是	Int	机构同一层级顺序
	parent	是	String	父机构 id

成功示例：

{
    "errcode": 200,
    "errmsg": "ok",
    "totalResults":1,
    "itemsPerPage":10,
    "startIndex":1,
    "schemas":[
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources":[
        {
            "id":"3650417845",
            "externalId": "d9ee38d3-86a6-4eca-b9bb-09860c4209b3",
            "meta":{
                "created":"2022-03-12T14:06:34.000+08:00",
                "resourceType":"Organization",
                "version": "2.0",
            },
            "schemas":[
                "urn:ietf:params:scim:schemas:core:2.0:Organization"
            ],
            "code":"3650417845",
            "displayName":"测试有限公司",
            "order":1,
            "parent":"0"
        }
    ]
}

创建用户

HTTP Method：POST
请求地址：https://serverurl/SCIM/v2/Users
Header Content-Type：application/json

接口功能：创建用户信息。

请求参数：

参数名	必选	类型	参数说明
externalId	否	String	外部源ID
userName	是	String	用户名（唯一标识）
displayName	否	String	用户姓名
password	否	String	密码
active	否	Boolean	用户状态，true标识用户正常、false标识用户停用，默认为true
emails	否	Array	邮箱，格式为：[{“value”:”test@youx.com”}]
phoneNumbers	否	Array	手机号，格式为：[{“value”:”18800001111″}]
organization	是	Array	所属机构ID，创建机构中创建的ID，格式为：[“11″,”22”]
extensions	否	Object	扩展属性，json格式

extensions数据结构：

参数名	必选	类型	参数说明
multiValued	否	Boolean	此属性是否多值，true代表多值，false代表单值
type	否	String	属性类型，可选值：string、int、boolean…
value	是	Object	属性值

请求示例：

{
    "externalId":"1",
    "userName":"zhangsan",
    "displayName":"张三",
    "password":"ECQD123455667",
    "emails":[
        {
            "value":" zhangsan@safe.com"
        }
    ],
    "phoneNumbers":[
        {
            "value":"18800001111"
        }
    ],
    "organization":[
        755
    ],
    "extensions":{
        "staffCard":{
            "multiValued":false,
            "type":"string",
            "value":"1088"
        },
        "staffEntryDate":{
            "multiValued":false,
            "type":"string",
            "value":"2022-03-08"
        }
    }
}

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述
id	否	String	用户ID

成功示例：

{
    "errcode":200,
    "errmsg":"created",
    "id": "52E4E27B313267C1288944EE6DA4AAD556C23A9EC06B4F04AF53"
}

删除用户

HTTP Method：DELETE
请求地址：https://serverurl/SCIM/v2/Users/{userId}

接口功能：删除用户。

请求参数：

参数名	必选	类型	参数说明
userId	是	String	用户ID，创建时的ID。该参数放到URL中{userId}位置

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述

成功示例：

{
    "errcode":200,
    "errmsg":"deleted"
}

更新用户

HTTP Method：PUT
请求地址：https://serverurl/SCIM/v2/Users/{userId}
Header Content-Type：application/json

接口功能：更新用户信息。

请求参数：

参数名	必选	类型	参数说明
userId	是	String	用户ID，创建时的ID。该参数放到URL中{userId}位置
userName	否	String	用户名（唯一标识）
displayName	否	String	用户姓名
password	否	String	密码
active	否	Boolean	用户状态，true标识用户正常、false标识用户停用
emails	否	Array	邮箱，格式为：[{“value”:”test@youx.com”}]
phoneNumbers	否	Array	手机号，格式为：[{“value”:”18800001111″}]
organization	否	Array	所属机构ID，创建机构中创建的ID，格式为：[“11″,”22”]
extensions	否	Object	扩展属性，json格式

extensions数据结构：

参数名	必选	类型	参数说明
multiValued	否	Boolean	此属性是否多值，true代表多值，false代表单值
type	否	String	属性类型，可选值：string、int、boolean…
value	是	Object	属性值

请求示例：

{
    "displayName": "张三",
    "userName":"zhangsan",
    "emails": [
        {
            "value": "zhangsan@safe.com"
        }
    ],
    "phoneNumbers": [
        {
            "value": "18800001111",
        }
    ],
     "organization": [3],
     "extensions":{
        "staffCard":{
            "multiValued":false,
            "type":"string",
            "value":"1088"
        },
        "staffEntryDate":{
            "multiValued":false,
            "type":"string",
            "value":"2022-03-08"
        }
    }
}

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述

成功示例：

{
     "errcode":200,
     "errmsg":"updated"
}

获取用户信息

HTTP Method：GET
请求地址：https://serverurl/SCIM/v2/Users/{userId}

接口功能：获取用户信息。

请求参数：

参数名	必选	类型	参数说明
userId	是	String	用户ID，创建时的ID。该参数放到URL中{userId}位置。

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述
id	是	String	用户ID
externalId	是	String	外部ID
meta	是	Object	SCIM元数据信息，格式为： `{ "created":"2022-03-12T15:36:40.000+08:00", "version": "2.0", "resourceType": "User" }`
schemas	是	StringArray	SCIM 的 Schemas，返回字符串数组固定值：[“urn:ietf:params:scim:schemas:core:2.0:User”]
userName	是	String	用户名
displayName	否	String	用户姓名
emails	否	Array	邮箱，格式为：[{“value”:”zhangsan@mail.com”}]
phoneNumbers	否	Array	手机号，格式为：[{“value”:”18800001111″}]
organization	是	Array	所属机构ID，创建机构中创建的ID，格式为：[“11″,”22”]
extensions	否	Object	扩展属性，json格式

extensions数据结构：

参数名	必选	类型	参数说明
multiValued	否	Boolean	此属性是否多值，true代表多值，false代表单值
type	否	String	属性类型，可选值：string、int、boolean…
value	是	Object	属性值

成功示例：

{
   "errcode":200,
   "errmsg":"ok",
   "id": "7656",
	"externalId": "1",
	"meta": {
		"created": "2022-03-12T15:36:40.000+08:00",
		"version": "2.0",
		"resourceType": "User"
	},
	"schemas": [
		"urn:ietf:params:scim:schemas:core:2.0:User",
	],
	"userName": "zhangsan",
	"displayName": "张三",
	"active": true,
	"emails": [
		{
			"value": "zhangsan@mail.com"
		}
	],
	"phoneNumbers": [
		{
			"value": "18800001111"
		}
	],
	"organization": [
		"11", "22"
	],
   "extensions" :{
        "staffCard":{
            "multiValued":false,
            "type":"string",
            "value":"1088"
        },
        "staffEntryDate":{
            "multiValued":false,
            "type":"string",
            "value":"2022-03-08"
        }
    }

}

查询用户列表

HTTP Method：GET
请求地址：https://serverurl/SCIM/v2/Users?startIndex=1&count=10&filter=userName eq zhangsan

接口功能：根据分页信息和过滤条件查询用户信息。默认按照 createTime 降序查询。

请求参数：

参数名	必选	类型	参数说明
startIndex	否	Int	开始下标。默认：1
count	否	Int	每一页查询记录数。默认：100；最大 100
filter	否	String	查询条件，仅支持用户名、手机号、邮箱、组织机构、更新时间单一条件查询，不支持复杂的逻辑条件查询。操作符仅支持 eq、gt，filter 条件符合SCIM语法

响应结果：

参数名	必选	类型	参数说明
errcode	是	Int	响应码，具体参见附录：响应码
errmsg	是	String	结果描述
totalResults	是	Int	总记录数
itemsPerPage	是	Int	每页大小，等于入参的 count
startIndex	是	Int	入参的 startIndex
schemas	是	StringArray	SCIM的Schemas，返回字符串数组固定值：[“urn:ietf:params:scim:api:messages:2.0:ListResponse”]
Resources	是	Array	返回的资源数组

Resources数据结构
Resources	参数名	必选	类型	参数说明
	id	是	String	用户ID
	externalId	是	String	外部ID
	meta	是	Object	SCIM元数据信息，格式为： `{ "created":"2022-03-12T15:36:40.000+08:00", "version": "2.0", "resourceType": "User" }`
	schemas	是	StringArray	SCIM的 Schemas，返回字符串数组固定值：[“urn:ietf:params:scim:schemas:core:2.0:User”]
	userName	是	String	用户名
	displayName	否	String	用户姓名
	emails	否	Array	邮箱，格式为：[{“value”:”zhangsan@mail.com”}]
	phoneNumbers	否	Array	手机号，格式为：[{“value”:”18800001111″}]
	organization	是	Array	所属机构ID，创建机构中创建的ID，格式为：[“11″,”22”]
	extensions	否	Object	扩展属性，json格式

成功示例：

{
   "errcode":200,
   "errmsg":"ok",
	"totalResults": 1,
	"itemsPerPage": 10,
	"startIndex": 1,
	"schemas": [
		"urn:ietf:params:scim:api:messages:2.0:ListResponse"
	],
	"Resources": [
		{
			"id": "7678",
			"externalId": "1",
			"meta": {
				"created": "2022-03-14T10:41:32.000+08:00",
				"version": "2.0",
				"resourceType": "User"
			},
			"schemas": [
				"urn:ietf:params:scim:schemas:core:2.0:User",
			],
			"userName": "zhangsan",
			"displayName": "张三",
			"active": true,
			"emails": [
				{
					"value": "zhangsan@mail.com"
				}
			],
			"phoneNumbers": [
				{
					"value": "18800001111"
				}
			],
			"organization": [
				"11", "22"
			],
		"extensions": {
        		"staffCard":{
            	                "multiValued":false,
            	                "type":"string",
            	                "value":"1088"
        		},
      	  		"staffEntryDate":{
           	 		"multiValued":false,
           	 		"type":"string",
            		        "value":"2022-03-08"
        		}
   		 	}
		},
	    …
	]
}

SCIM同步接口响应码

HTTP Status Code

响应码	描述信息
200	操作成功
201	创建成功
204	删除成功
400	未发现授权信息，如：无效的令牌、参数合法性校验
403	域名无效
404	资源不存在，如：用户不存在、组织机构不存在
409	资源已存在，如：用户名已被占用、外部ID已被占用
418	消费者提供的模式未知
500	发生意外异常

业务响应码

响应码	描述信息
200	操作成功（所有成功）
400	未发现授权信息，如：无效的令牌、参数合法性校验
403	域名无效
404	资源不存在，如：用户不存在、组织机构不存在
409	资源已存在，如：用户名已被占用、外部ID已被占用
418	消费者提供的模式未知
500	发生意外异常