资源授权服务(IAM)

更新时间:2023-07-18 07:11:19下载pdf

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

功能说明

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

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

功能优势

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

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

访问方式

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

IAM 整体流程如下图:

资源授权服务(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 的使用流程主要分为 授权管理鉴权接入 两步。

授权管理

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

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

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

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

鉴权接入

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

策略鉴权规则

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

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

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

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

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

    资源授权服务(IAM)

约束限制

一个云项目中,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)实践