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`，请求才会转发到后端服务。 ## 前提条件 * 已创建网关实例，操作详情参见 [创建实例](https://www.volcengine.com/docs/6569/85693)。 * 已创建服务，操作详情参见 [创建服务](https://www.volcengine.com/docs/6569/85695#.5Yib5bu65pyN5Yqh)。 * 已创建路由，操作详情参见 [创建路由](https://www.volcengine.com/docs/6569/179038)。 * 已创建对应的 IAM 用户、用户组或角色，操作详情参见 [用户管理](https://docs.volcengine.com/docs/IAM/Usermanagement-9?lang=zh)、[用户组管理](https://docs.volcengine.com/docs/IAM/Usergroupmanagement-1?lang=zh) 和 [角色管理](https://docs.volcengine.com/docs/IAM/RoleManagement?lang=zh)。 * 已获取 IAM 用户的 AK/SK 或 API Key。操作详情参见 [API 密钥（Access Key 与 API Key）](https://docs.volcengine.com/docs/IAM/APIAccessKeyManagement?lang=zh#.5Li6LWFwaS3lr4bpkqXmt7vliqDmnYPpmZA=)。 * 已获取 STS 临时凭证。操作详情参见 [临时凭证最佳实践](https://docs.volcengine.com/docs/6257/2100113?lang=zh)。 ## 使用限制同一请求同时命中多个绑定时，生效优先级为：路由 \> 服务 \> 网关。高优先级配置整体覆盖低优先级配置，不合并字段。 ## 操作步骤 ### 步骤一：创建 IAM 访问鉴权插件 1. 登录 [API 网关控制台](https://console.volcengine.com/veapig)。 2. 在顶部导航栏，选择目标地域。 3. 在左侧导航栏 **实例管理** 下拉框中选择目标实例后，选择 **插件中心 \> 认证鉴权 \>** **IAM 访问鉴权**。 4. 单击 **创建插件**，配置插件规则。 |配置项 |说明 | |---|---| |生效级别 |选择插件的生效级别，包括：

* **实例级别**：插件在实例内生效，需要指定生效的目标实例。

* **服务级别**：插件在服务内生效，需要指定生效的目标实例和目标服务。

* **路由级别**：插件在路由内生效，需要指定生效的目标实例、目标服务和目标路由。 | |所属服务 |选择插件所属服务。 | |所属路由 |选择插件所属路由。 | |高级配置 || |支持 APIKey 作为授权信息 |开启后，将支持通过 API Key 进行认证鉴权。

> **说明**

> 当您选择通过 API Key 的方式接入时，需开启该配置。
| |鉴权成功后删除凭证再转发 |开启后，鉴权成功会删除请求里的凭证信息后进行转发。

> **说明**

> 对于不可信场景，使用 API Key、AK/SK、STS 临时凭证和预签名 URL 的方式接入时，凭证信息会直接暴露在请求中，建议您开启该配置，降低凭证信息泄露风险。
| 5. 单击 **确定**，完成插件创建。 ### 步骤二：配置 IAM 权限策略 1. 登录 [IAM 控制台](https://console.volcengine.com/iam)。 2. 在左侧导航栏选择 **权限策略**，然后点击 **新建自定义策略**。 3. 在 **新建自定义策略** 页面，选择 **JSON编辑器**，配置 **策略名** 和 IAM 权限策略。IAM 权限策略示例，请参见 [IAM 权限策略示例](https://docs.volcengine.com/docs/apig/iam-access-authentication?lang=zh&TagIDs=2%2C286#cinCPbAB)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_69b87bc161c28f4be09c65f581ce36e6.png) 4. 单击 **提交**，完成自定义策略创建。 ### 步骤三：权限策略授权 1. 在 **权限策略** 页面，找到新建的 IAM 权限策略，单击 **操作** 列的 **授权**。 2. 在 **添加权限** 页面的 **授权身份** 区域，选择目标用户、用户组或角色。 3. 单击 **提交**，完成策略授权。 ## IAM 权限策略示例为调用方身份配置 IAM 策略，可以配置的字段有效果（Effect）、操作（Action）、资源（Resource）以及条件（Condition），结构示例如下。 ```JSON { "Statement": [ { "Effect": "Allow", "Action": "apig:Invoke", "Resource": "trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****", "Condition": { "IpAddress": { "volc:SourceIp": "10.**.**.**/8" } } } ] } ``` ### 效果（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***`。 ```Plain Text trn:apig:cn-beijing:210000****:gateway/gdb6**** trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1**** trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****/route/rdb3*** ``` Resource 通配规则。 * `trn:apig:cn-beijing:210000****:gateway/gdb6****`只匹配网关实例本身。 * `trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****/*`只匹配服务`snl1****`下的所有路由。 * 如需同时放行服务与其下的所有路由，应同时配置两个 Resource。 ```JSON { "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 | ### 权限策略场景示例 > **说明** > 以下部分示例均基于最小权限策略，在 Condition 字段中按需组合 Operator 与 Condition Key。 **示例一：最小权限策略** 以下示例为最小权限策略允许调用方访问服务`snl1****`。 ```JSON { "Statement": [ { "Effect": "Allow", "Action": "apig:Invoke", "Resource": "trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****" } ] } ``` **示例二：仅允许内网 IP 段调用** 仅当网关识别到的请求来源 IP 位于`10.**.**.**/8`网段时进行转发。 ```JSON { "Statement": [ { "Effect": "Allow", "Action": "apig:Invoke", "Resource": "trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****", "Condition": { "IpAddress": { "volc:SourceIp": "10.**.**.**/8" } } } ] } ``` **示例三：限制指定 Role 和失效时间** 仅允许指定 IAM 用户或基础 Role 身份调用，并在 UTC 截止时间后失效。STS 场景填写基础 Role TRN，不包含 SessionName。 ```JSON { "Statement": [ { "Effect": "Allow", "Action": "apig:Invoke", "Resource": "trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****", "Condition": { "TrnEquals": { "volc:PrincipalTrn": "trn:iam::210000****:role/apig-client" }, "DateLessThan": { "volc:CurrentTime": "2026-12-31T23:59:59Z" } } } ] } ``` **示例四：组合多个 Condition** 当请求地域为`cn-beijing`、网关所属项目为`project-a`，且网关识别到的来源 IP 位于`10.**.**.**/8`时进行转发。 ```JSON { "Statement": [ { "Effect": "Allow", "Action": "apig:Invoke", "Resource": "trn:apig:cn-beijing:210000****:gateway/gdb6****/service/snl1****", "Condition": { "StringEquals": { "volc:RequestedRegion": "cn-beijing", "volc:ResourceTag/volc:iam:ProjectPath": "/default/" }, "IpAddress": { "volc:SourceIp": "10.**.**.**/8" } } } ] } ``` ## 插件接入使用插件支持以下三种调用方凭证和一种预签名方式，可按场景任选其一。 ### 使用 AK/SK 认证 Go 调用方可使用 [火山引擎 Go SDK 的 base 包](https://pkg.go.dev/github.com/volcengine/volcengine-go-sdk/volcengine/base) 生成 V4 签名。签名前需确定请求 Method、URL、Query、业务 Header 和 Body，签名后不得再修改。将 Region 替换为网关所在地域，生产环境的 Signing Service 固定为`apig`。 ```Go credential := base.Credentials{ AccessKeyID: "", SecretAccessKey: "", Region: "cn-beijing", Service: "apig", } req.Host = req.URL.Host req = credential.Sign(req) ``` ### 使用 STS 临时凭证通过 STS AssumeRole 获取同一次响应中的 AccessKeyId、SecretAccessKey、SessionToken 和 Expiration，然后在签名凭证中设置 SessionToken。详情请参见 [AssumeRole - 角色扮演](https://docs.volcengine.com/docs/IAM/AssumeRole?lang=zh)。 STS 请求需同时满足角色身份策略、服务控制策略（SCP）和会话策略（Session Policy）。Session Policy 只能缩小角色权限，不能单独授予`apig:Invoke`。 ```Go credential := base.Credentials{ AccessKeyID: "", SecretAccessKey: "", SessionToken: "", Region: "cn-beijing", Service: "apig", } req.Host = req.URL.Host req = credential.Sign(req) ``` ### 使用 IAM API Key IAM API Key 默认不启用。仅当启用 AllowApiKey 时，请求头中的如下配置才会被插件接受。 API Key 关联的 IAM 身份仍需具备目标资源的`apig:Invoke`权限。API Key 不需要 V4 签名，也不能代替 STS SessionToken。 ```Bash Authorization: Bearer ``` ### 使用预签名 URL 使用同一 SDK 的`Credentials.SignUrl`生成预签名参数，并将返回值写入`req.URL.RawQuery`。预签名 URL 默认有效期为 15 分钟，最长为 7 天。该方式使用`X-NotSignBody`，不保护实际请求 Body，建议用于没有敏感 Body 的 GET 或 HEAD 请求。以下示例假设服务域名为`scv4***.volceapi.com`，原始业务请求如下： ```HTTP GET /orders?limit=10 HTTP/1.1 Host: scv4***.volceapi.com ``` 使用 GO SDK 生成预签名 URL。 ```Go credential := base.Credentials{ AccessKeyID: "", SecretAccessKey: "", Region: "cn-beijing", Service: "apig", } req, err := http.NewRequest( http.MethodGet, "https://scv4***.volceapi.com/orders?limit=10", nil, ) if err != nil { panic(err) } req.Host = req.URL.Host req.URL.RawQuery = credential.SignUrl(req) fmt.Println(req.URL.String()) ``` 假设签名时间为 2026\-10\-16T12:00:00Z，有效期为 300 秒，生成的请求结构如下。 ```HTTP GET /orders?limit=10&X-Algorithm=HMAC-SHA256&X-Credential=AKLT%2F20261016%2Fcn-beijing%2Fapig%2Frequest&X-Date=20261016T120000Z&X-Expires=300&X-NotSignBody=&X-SignedHeaders=host&X-SignedQueries=X-Algorithm%3BX-Credential%3BX-Date%3BX-Expires%3BX-NotSignBody%3BX-SignedHeaders%3BX-SignedQueries%3Blimit&X-Signature= HTTP/1.1 Host: scv4***.volceapi.com ``` 最终 URL 可以直接作为 GET 请求地址，调用方无需再添加 Authorization 请求头，可直接执行。 ```Bash curl -i 'https://scv4***.volceapi.com/orders?limit=10&X-Algorithm=HMAC-SHA256&X-Credential=...&X-Date=...&X-Expires=300&X-NotSignBody=&X-SignedHeaders=host&X-SignedQueries=...&X-Signature=...' ``` ## 结果验证 ### 查看配置配置完成后，在插件列表中，查看已配置的 IAM 访问鉴权插件，若插件状态为 **已启用**，表示插件生效。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5f641c7d9fe04f9dc130e112c9700373.png) ### 认证测试以下示例使用 IAM API Key 认证方式，仅携带正确 IAM API Key 认证信息的访问请求，能够通过 API 网关访问。 1. 携带正确 IAM API Key 执行以下命令进行访问。` `需替换为正确的已授权用户的 API KEY。 ```Bash curl -i \ -H "Authorization: Bearer " \ "http://api.example.com" ``` 预期结果如下，表示请求通过 IAM 访问鉴权。 ```Bash HTTP/1.1 200 OK content-type: text/plain ``` 2. 当未携带或携带错误 IAM API Key 访问时，预期结果如下，表示缺少凭证、凭证无效、签名时间过期或签名不匹配。 ```Bash HTTP/1.1 401 Unauthorized content-type: text/plain IAM authentication failed. ``` 3. 当携带有效凭证但对端用户不具备目标 Resource 的`apig:Invoke`权限、命中 Deny 权限策略时，预期结果如下。 ```Bash HTTP/1.1 403 Forbidden content-type: text/plain IAM authentication failed. ```