IAM 访问鉴权插件为 API 网关提供基于 IAM 的请求认证和权限控制能力。启用该插件后，API 网关先验证调用方身份的真实性，再依据 IAM 权限策略判断该身份是否有权访问当前网关资源，两个阶段均通过后请求才会转发到后端服务。

背景信息

身份与访问管理（Identity and Access Management，IAM）用于管理调用身份及其权限。API 网关的 IAM 访问鉴权插件支持长期 AK/SK、STS 临时凭证和 IAM API Key，并支持生成预签名 URL。其中，Access Key ID（AK）用于标识调用方，Secret Access Key（SK）用于生成请求签名，安全令牌服务（Security Token Service，STS）用于签发短期凭证。

IAM 访问鉴权包含身份认证和权限校验两步。插件先校验凭证或签名，再根据绑定层级生成当前资源的 TRN。TRN 是 IAM 策略用于唯一标识资源的字符串。只有调用身份的策略明确允许对该 TRN 执行apig:Invoke，请求才会转发到后端服务。

前提条件

已创建网关实例，操作详情参见创建实例。

已创建服务，操作详情参见创建服务。

已创建路由，操作详情参见创建路由。

已创建对应的 IAM 用户、用户组或角色，操作详情参见用户管理、用户组管理和角色管理。

已获取 IAM 用户的 AK/SK 或 API Key。操作详情参见 API 密钥（Access Key 与 API Key）。

已获取 STS 临时凭证。操作详情参见临时凭证最佳实践。

使用限制

同一请求同时命中多个绑定时，生效优先级为：路由 > 服务 > 网关。高优先级配置整体覆盖低优先级配置，不合并字段。

操作步骤

步骤一：创建 IAM 访问鉴权插件

登录 API 网关控制台。

在顶部导航栏，选择目标地域。

在左侧导航栏实例管理下拉框中选择目标实例后，选择插件中心 > 认证鉴权 > IAM 访问鉴权。

单击创建插件，配置插件规则。

配置项	说明
生效级别	选择插件的生效级别，包括：实例级别：插件在实例内生效，需要指定生效的目标实例。服务级别：插件在服务内生效，需要指定生效的目标实例和目标服务。路由级别：插件在路由内生效，需要指定生效的目标实例、目标服务和目标路由。
所属服务	选择插件所属服务。
所属路由	选择插件所属路由。
高级配置
支持 APIKey 作为授权信息	开启后，将支持通过 API Key 进行认证鉴权。说明当您选择通过 API Key 的方式接入时，需开启该配置。
鉴权成功后删除凭证再转发	开启后，鉴权成功会删除请求里的凭证信息后进行转发。说明对于不可信场景，使用 API Key、AK/SK、STS 临时凭证和预签名 URL 的方式接入时，凭证信息会直接暴露在请求中，建议您开启该配置，降低凭证信息泄露风险。

单击确定，完成插件创建。

步骤二：配置 IAM 权限策略

登录 IAM 控制台。

在左侧导航栏选择权限策略，然后点击新建自定义策略。

在新建自定义策略页面，选择 JSON编辑器，配置策略名和 IAM 权限策略。IAM 权限策略示例，请参见 IAM 权限策略示例。

单击提交，完成自定义策略创建。

步骤三：权限策略授权

在权限策略页面，找到新建的 IAM 权限策略，单击操作列的授权。

在添加权限页面的授权身份区域，选择目标用户、用户组或角色。

单击提交，完成策略授权。

IAM 权限策略示例

为调用方身份配置 IAM 策略，可以配置的字段有效果（Effect）、操作（Action）、资源（Resource）以及条件（Condition），结构示例如下。

效果（Effect）配置

效果（Effect）是每则策略声明的必需元素，包含着这条权限声明的作用效果是允许（Allow）还是显式拒绝（Deny）。注意：Deny 的优先级高于 Allow，当身份对某些操作存在 Deny 权限时，再次赋予这些操作的 Allow 权限将无法生效，需要将相应的 Deny 声明去除或更改为 Allow。

操作（Action）配置

操作（Action）此处固定配置为apig:Invoke。

资源（Resource）配置

资源（Resource）元素内包含着权限声明定义的资源范围，使用 TRN 表达式定义。以下示例为账号210000****在cn-beijing地域的资源层级 TRN，其中网关实例 ID 为gdb6****，服务 ID 为snl1****以及路由 ID 为rdb3***。

Resource 通配规则。

trn:apig:cn-beijing:210000****:gateway/gdb6****只匹配网关实例本身。

trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****/*只匹配服务snl1****下的所有路由。

如需同时放行服务与其下的所有路由，应同时配置两个 Resource。

{
"Resource": [
"trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****",
"trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****/route/*"
]
}

条件（Condition）配置

如需进一步缩小权限范围，可以使用 Condition 限制请求地域、来源 IP、网关所属项目、调用身份或失效时间。当配置多个 Condition Key 时，需同时满足请求才能转发。

限制目的	Operator	Condition Key
请求地域	StringEquals	volc:RequestedRegion
来源 IP	IpAddress	volc:SourceIp
网关项目	StringEquals	volc:ResourceTag/volc:iam:ProjectPath
IAM 用户或角色	TrnEquals、TrnNotEquals、StringLike	volc:PrincipalTrn
失效时间	DateLessThan	volc:CurrentTime

权限策略场景示例

示例一：最小权限策略

示例二：仅允许内网 IP 段调用

示例三：限制指定 Role 和失效时间

示例四：组合多个 Condition

以下示例为最小权限策略允许调用方访问服务snl1****。

插件接入使用

插件支持以下三种调用方凭证和一种预签名方式，可按场景任选其一。

使用 AK/SK 认证

Go 调用方可使用火山引擎 Go SDK 的 base 包生成 V4 签名。签名前需确定请求 Method、URL、Query、业务 Header 和 Body，签名后不得再修改。将 Region 替换为网关所在地域，生产环境的 Signing Service 固定为apig。

使用 STS 临时凭证

通过 STS AssumeRole 获取同一次响应中的 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration，然后在签名凭证中设置 SessionToken。详情请参见 AssumeRole - 角色扮演。

STS 请求需同时满足角色身份策略、服务控制策略（SCP）和会话策略（Session Policy）。Session Policy 只能缩小角色权限，不能单独授予apig:Invoke。

使用 IAM API Key

IAM API Key 默认不启用。仅当启用 AllowApiKey 时，请求头中的如下配置才会被插件接受。

API Key 关联的 IAM 身份仍需具备目标资源的apig:Invoke权限。API Key 不需要 V4 签名，也不能代替 STS SessionToken。

使用预签名 URL

使用同一 SDK 的Credentials.SignUrl生成预签名参数，并将返回值写入req.URL.RawQuery。

预签名 URL 默认有效期为 15 分钟，最长为 7 天。该方式使用X-NotSignBody，不保护实际请求 Body，建议用于没有敏感 Body 的 GET 或 HEAD 请求。

以下示例假设服务域名为scv4***.volceapi.com，原始业务请求如下：

使用 GO SDK 生成预签名 URL。

假设签名时间为 2026-10-16T12:00:00Z，有效期为 300 秒，生成的请求结构如下。

最终 URL 可以直接作为 GET 请求地址，调用方无需再添加 Authorization 请求头，可直接执行。

结果验证

查看配置

配置完成后，在插件列表中，查看已配置的 IAM 访问鉴权插件，若插件状态为已启用，表示插件生效。

认证测试

以下示例使用 IAM API Key 认证方式，仅携带正确 IAM API Key 认证信息的访问请求，能够通过 API 网关访问。

携带正确 IAM API Key 执行以下命令进行访问。 <IAM_API_KEY>需替换为正确的已授权用户的 API KEY。

curl -i \
-H "Authorization: Bearer <IAM_API_KEY>" \
"http://api.example.com"

预期结果如下，表示请求通过 IAM 访问鉴权。

HTTP/1.1 200 OK
content-type: text/plain

当未携带或携带错误 IAM API Key 访问时，预期结果如下，表示缺少凭证、凭证无效、签名时间过期或签名不匹配。

HTTP/1.1 401 Unauthorized
content-type: text/plain

IAM authentication failed.

当携带有效凭证但对端用户不具备目标 Resource 的apig:Invoke权限、命中 Deny 权限策略时，预期结果如下。

HTTP/1.1 403 Forbidden
content-type: text/plain

IAM authentication failed.