资源授权服务（IAM）

云开发 资源授权服务（Identity and Access Management，简称 IAM）是涂鸦提供的 OpenAPI 资源权限管理服务，可以帮助您安全、精细化地管控云服务行为和资源的访问权限。

功能说明

您可以使用 IAM 提供的用户接入和授权功能，给员工或应用程序创建 IAM 授权用户，并授予用户能满足实际工作所需要的权限。例如：

• 给检修员只授权指定设备的查看、指令下发等行为权限。
• 给施工员授予空间下创建子空间、添加设备、创建联动场景等行为权限。

功能优势

使用 IAM 可以实现云项目中的资源进行精细化行为控制：

• 简单和便利的 IAM 用户接入方式。
• 基于 行为 的精细化权限管控。
• 基于 资源 的精细化权限管控。
• 基于 角色 的批量用户权限管理。

访问方式

IAM 功能支持通过 REST API 以编程方式访问和管理 IAM 权限，可管理的 API 能力范围以调用 可用 action 列表（GET /v2.0/cloud/iam/policy/action） 接口返回信息为准，也可参考下文 行为列表。

IAM 整体流程如下图：

基本概念

名词	常见字段	说明
授权	authorize	指管理员将用户完成具体工作需要的权限授予用户，授权通过角色关联的策略和资源生效。用户获得具体的权限后可对目标资源进行相应的行为，例如，管理云项目下的设备，进行设备指令下发等。
角色	role	指一种贴近实际场景的授权能力，例如 施工员、检修员 等。不同角色需要使用到的服务能力及资源是不同的，因此可以定义不同角色，将相应的权限授予对应的角色，实现同类角色的用户批量授权。
行为	action	指最小服务能力的定义，例如 创建空间行为，空间删除行为，指令下发行为等，具体行为定义，可以参考下文 行为列表。
效果	effect	用于定义行为中的操作是否允许执行： Allow 表示允许执行 Deny 表示不允许执行 任何情况都遵循 Deny 优先的原则。
策略	policy	限定了一组允许或者拒绝的行为能力，因此定义时需要区分效果是允许的行为（allow_action）还是拒绝的行为（deny_action）。允许的行为表示定义的行为为可执行行为，拒绝的行为表示定义的行为会被拒绝执行的行为。例如： 定义一个包含了允许创建空间行为、允许设备属性查看行为、不允许空间删除行为的策略，同时策略定义时支持模糊匹配方式批量添加行为，例如所有行为，则使用 *。 空间相关所有行为，则使用 space:*。 设备相关所有信息查询的行为，则使用 device:get:*。 最后在管理权限时，将策略关联到资源，形成对应的权限。
资源	space device *	指行为需要操作的实际对象。目前 IAM 中开放的资源包含： 空间资源（space） 设备资源（device） 全局资源（*） 在使用 给角色关联权限点（POST:/v2.0/cloud/iam/role/{role_id}/permission） 接口添加资源时，需要根据资源类型来区分分别传哪些资源编号： 如果是空间资源，则资源 ID 为空间编号（space_id）。 如果是设备资源，则资源 ID 为设备 ID（device_id）。 如果是全局资源，则资源 ID 为星号（*），表示所有的空间资源及设备资源。
权限	permission	可以进行授权操作的最小单位，权限由 策略 和 资源 组成，限定用户可以执行的行为及操作对象，可以将单个或者多个权限授权给一个角色或多个角色。
IAM 用户	user	指在云项目结构下，您将自有系统内的员工等成员通过唯一标识编号，添加成为可在项目内执行已授权行为或访问项目下已授权资源的用户。

以上概念的逻辑关系如下图所示：

IAM 使用流程

根据 IAM 的设计方案，IAM 的使用流程主要分为 授权管理 和 鉴权接入 两步。

授权管理

当前 IAM 的权限管理功能只开放给了开发者，因此需要使用开发者账号进行权限的设计、管理及授权。

您通过 令牌接口 获取 开发者 Token 令牌 后使用以下各权限接口进行权限的管理。

您需要按照以下步骤实现权限的管理：

• 创建角色：根据实际的场景需要创建对应的角色，例如：施工员、维修员等。
• 创建策略：根据不同角色需要的行为来生成对应的策略。
• 角色关联策略及资源：将角色的行为策略及资源信息关联到角色。
• 给用户添加角色：将用户关联到具体的角色，实现对用户行为和资源的访问控制。

鉴权接入

为实现对用户行为和资源的访问控制，系统需要区分每次请求归属的 IAM 用户。因此，在用户发起请求前，您需要先获取 用户 Token 令牌。与获取 开发者 Token 令牌 的区别为，接口内新增了用户唯一标示编号（targetUid），此用户标识编号需要与权限管理内给用户添加角色使用的用户编号（user_id）保持一致，否则当前用户将没有任何权限。

策略鉴权规则

当 IAM 用户发起资源请求时，当前用户关联的角色内所有的权限信息会被查询，然后根据权限获取所有的行为，再根据对应的效果进行鉴权。鉴权规则如下：

1. IAM 用户发起对资源的访问请求。

2. 系统查找当前 IAM 用户请求关联的所有策略，优先处理 Deny 类型的策略行为，如果找到适用于此请求的拒绝策略，则返回 Deny 决定。

3. 如果系统未找到拒绝策略，则继续寻找适用于请求的任何允许策略，如果找到了允许策略，系统将返回允许决定。

4. 如果找不到允许策略，最终默认决定为拒绝，此时鉴权流程结束。

   

约束限制

一个云项目中，IAM 功能涉及的约束限制如下表所示：

限制项	限制值
IAM 用户数	暂无限制
每个项目下可创建角色数	100 个
一个角色可关联用户数	200 个
一个用户可关联的角色数	10 个
每个项目下可自定义创建策略数	100 个
一个角色可关联的权限数	10 个
可接入 IAM 的用户标识（targetUid）长度	最小 1 位，最大 32 位，只允许数字、字母

IAM 管理接口

分类	API	说明
策略	POST:/v2.0/cloud/iam/policy	创建策略
策略	PUT:/v2.0/cloud/iam/policy/{policy_id}	修改策略信息
策略	DELETE:/v2.0/cloud/iam/policy/{policy_id}	删除策略
策略	GET:/v2.0/cloud/iam/policy/list	查询项目开发者下的策略列表
策略	GET:/v2.0/cloud/iam/policy/action	查询策略可用 action 列表
角色	POST:/v2.0/cloud/iam/role	创建角色
角色	GET:/v2.0/cloud/iam/role/{role_id}	查询角色
角色	PUT:/v2.0/cloud/iam/role/{role_id}	修改角色信息
角色	DELETE:/v2.0/cloud/iam/role/{role_id}	删除角色
角色	POST:/v2.0/cloud/iam/role/{role_id}/permission	给角色关联权限点(资源和策略)
角色	DELETE:/v2.0/cloud/iam/role/{role_id}/permission/{permission_id}	解除角色关联的权限点(资源和策略)
角色	GET:/v2.0/cloud/iam/role/{role_id}/permission	查询角色关联的权限点列表(资源和策略)
角色	GET:/v2.0/cloud/iam/role/list	查询项目 tenantCode 下的角色列表
授权	POST:/v2.0/cloud/iam/role/{role_id}/user/{user_id}	给用户关联角色
授权	DELETE:/v2.0/cloud/iam/role/{role_id}/user/{user_id}	解除用户关联角色
授权	GET:/v2.0/cloud/iam/role/user/{user_id}	查询用户的角色列表

行为列表

已开放的行为列表如下，对于新开放还未维护的行为编码可以通过调用 可用 action 列表（GET /v2.0/cloud/iam/policy/action） 接口获取并使用。行为编码对应的接口具体使用方式请参考 云服务开放 API 能力。

类型	服务名称	API 路径	行为（action）
空间	创建空间	POST:/v2.0/cloud/space/creation	space:create
空间	删除空间	DELETE:/v2.0/cloud/space/{space_id}	space:remove
空间	查询空间	GET:/v2.0/cloud/space/{space_id}	space:get
空间	修改空间信息	PUT:/v2.0/cloud/space/{space_id}	space:modify
空间	查询空间子节点列表	GET:/v2.0/cloud/space/child	space:list:child
空间	查询空间设备列表	GET:/v2.0/cloud/space/{space_id}/resource	space:list:resource
空间	判断两个空间的关系	GET:/v2.0/cloud/space/relation	space:relation
设备控制	获得物模型属性配置	GET:/v2.0/cloud/thing/{device_id}/shadow/properties	device:get:shadow
设备控制	自定义修改物模型属性配置	POST:/v2.0/cloud/thing/{device_id}/shadow/properties	device:modify:shadow
设备控制	物模型属性值下发	POST:/v2.0/cloud/thing/{device_id}/shadow/properties/issue	device:issue:shadow
设备控制	查询期望属性	GET:/v2.0/cloud/thing/{device_id}/shadow/properties/desired	device:get:shadowDesired
设备控制	设置期望属性	POST:/v2.0/cloud/thing/{device_id}/shadow/properties/desired	device:set:shadowDesired
设备控制	调用动作	POST:/v2.0/cloud/thing/{device_id}/shadow/actions	device:execute:shadow
设备控制	查询物模型	GET:/v2.0/cloud/thing/{device_id}/model	device:get:model
设备群组	新增设备群组	POST:/v2.0/cloud/thing/group	devicegroup:create
设备群组	修改群组名称	PUT:/v2.0/cloud/thing/group/{group_id}/{name}	devicegroup:modify
设备群组	查询群组信息	GET:/v2.0/cloud/thing/group/{group_id}	devicegroup:get
设备群组	删除群组	DELETE:/v2.0/cloud/thing/group/{group_id}	devicegroup:remove
设备群组	添加群组内设备	PUT:/v2.0/cloud/thing/group/{group_id}/devices	devicegroup:add:device
设备群组	删除群组内设备	DELETE:/v2.0/cloud/thing/group/{group_id}/devices	devicegroup:remove:device
设备群组	查询群组列表	GET:/v2.0/cloud/thing/group	devicegroup:list
设备群组	查询群组支持的物模型属性	GET:/v2.0/cloud/thing/group/{group_id}/properties	devicegroup:get:property
设备群组	设置群组物模型属性	POST:/v2.0/cloud/thing/group/properties	devicegroup:modify:property
设备群组	查询群组下设备列表	GET:/v2.0/cloud/thing/group/{group_id}/devices	devicegroup:list:device
设备群组	查询设备所在群组	GET:/v2.0/cloud/thing/group/device/{device_id}	device:get:deviceGroup
设备管理	查询设备详情	GET:/v2.0/cloud/thing/{device_id}	device:get
设备管理	批量查询设备	GET:/v2.0/cloud/thing/batch	device:list
设备管理	修改设备基础属性	POST:/v2.0/cloud/thing/{device_id}/attribute	device:modify:deviceAttribute
设备管理	移除设备	DELETE:/v2.0/cloud/thing/{device_id}	device:remove
设备管理	恢复设备出厂设置	POST:/v2.0/cloud/thing/{device_id}/reset	device:reset
设备管理	冻结/解冻设备	POST:/v2.0/cloud/thing/{device_id}/freeze	device:freeze
设备管理	设备转移	POST:/v2.0/cloud/thing/{device_id}/transfer	device:transfer
设备管理	获取设备冻结状态	GET:/v2.0/cloud/thing/{device_id}/state	device:get:state
设备管理	查询设备日志	GET:/v2.0/cloud/thing/{device_id}/logs	device:get:log
设备管理	获取设备属性上报日志	GET:/v2.0/cloud/thing/{device_id}/report-logs	device:get:reportLog
设备管理	执行 OTA 升级	POST:/v2.0/cloud/thing/{device_id}/firmware/{channel}	device:execute:ota
设备管理	查询升级进度	GET:/v2.0/cloud/thing/{device_id}/firmware/{channel}/progress	device:get:otaProgress
设备管理	检测升级	GET:/v2.0/cloud/thing/{device_id}/firmware	device:check:otaFirmware
场景联动	场景联动规则新增	POST:/v2.0/cloud/scene/rule	scene:create:rule
场景联动	场景联动规则修改	PUT:/v2.0/cloud/scene/rule/{rule_id}	scene:modify:rule
场景联动	场景联动规则删除	DELETE:/v2.0/cloud/scene/rule	scene:remove:rule
场景联动	场景联动规则单个查询	GET:/v2.0/cloud/scene/rule/{rule_id}	scene:get:rule
场景联动	查询场景联动规则列表	GET:/v2.0/cloud/scene/rule	scene:list:rule
场景联动	启/禁用场景联动规则	PUT:/v2.0/cloud/scene/rule/state	scene:modify:ruleState
场景联动	触发场景联动规则	POST:/v2.0/cloud/scene/rule/{rule_id}/actions/trigger	scene:execute:rule
设备定时	设备新增定时任务	POST:/v2.0/cloud/timer/device/{device_id}	device:create:timer
设备定时	设备修改定时任务	PUT:/v2.0/cloud/timer/device/{device_id}	device:modify:timer
设备定时	单个定时任务启停	PUT:/v2.0/cloud/timer/device/{device_id}/state	device:modify:timerState
设备定时	删除设备对应所有定时任务	DELETE:/v2.0/cloud/timer/device/{device_id}	device:removeAll:timer
设备定时	查询设备所有定时任务	GET:/v2.0/cloud/timer/device/{device_id}	device:list:timer
设备定时	批量删除设备定时	DELETE:/v2.0/cloud/timer/device/{device_id}/batch	device:batchRemove:timer

最佳实践

更多详情，请参考 云开发资源授权（IAM）实践。