使用 AWS SDK for Java 2.x 操作 IAM 的完整实践指南

• 示例工程
• 教程
• 后端

AWS Identity and Access Management（IAM）是 AWS 中用于安全控制账户内资源访问的核心服务，通过它你可以集中管理用户、角色、策略与权限。本指南以javav2/example_code/iam目录下的官方示例文档为骨架，系统梳理了如何使用 AWS SDK for Java 2.x 完成 IAM 的用户创建、角色扮演、策略管理、访问密钥管理等核心操作，并深入讲解 IAM Policy Builder API 的对象化策略构建方式。读完本文，你将能够独立运行 Hello 示例、完整的基础入门场景（创建用户并假设角色）以及全部 16 个单动作示例，理解其底层实现原理与测试验证方式。

示例概览与代码组织

IAM 示例位于 javav2/example_code/iam 目录，这是一个标准的 Maven 工程，源码集中在src/main/java/com/example/iam包下。该目录的 README.md 按功能把示例划分为四大类：

此外，示例还配套了 Makefile、run_example.sh、checkstyle.xml 与 pom.xml，覆盖构建、运行与代码风格检查的完整开发链路。

环境准备（Prerequisites）

在运行任何示例之前，需要先完成环境配置。整体前置要求记录在 javav2 目录的 README 中，核心要点如下：

• 本地获取本仓库代码（克隆、Fork 或下载 zip）。
• 安装 Apache Maven（版本高于 3.0）。
• 所有 Java v2 示例均依赖 Java SDK 的默认凭证提供链（default credentials provider chain）获取 AWS 凭证。你可以通过以下任一方式配置：
  • 在~/.aws/config中配置 IAM Identity Center SSO 设置；
  • 在~/.aws/credentials中配置临时凭证。
• 默认区域配置：若未设置区域，SDK 默认使用us-east-1。值得注意的是，IAM 客户端在示例中普遍显式指定Region.AWS_GLOBAL，因为 IAM 是全局服务。

IAM 工程自身的 pom.xml 基于 AWS SDK BOM（software.amazon.awssdk:bom:2.35.10）统一管理依赖版本，编译目标为 Java 21，并显式引入iam、iam-policy-builder、s3、sts、secretsmanager、dynamodb、accessanalyzer等模块，同时以 JUnit 5 作为测试框架。

快速开始：Hello IAM 示例

HelloIAM.java 是最简单的入门示例，它通过IamClient.listPolicies()列出当前账户下的全部托管策略，展示 SDK 客户端构建与调用的最小模式：

Region region = Region.AWS_GLOBAL; IamClient iam = IamClient.builder() .region(region) .build(); ListPoliciesResponse response = iam.listPolicies(); List<Policy> polList = response.policies(); polList.forEach(policy -> { System.out.println("Policy Name: " + policy.policyName()); });

代码要点：

• IamClient通过 Builder 模式构建，区域固定为Region.AWS_GLOBAL（IAM 为全局服务，无区域维度）。
• listPolicies()是无参调用，返回的ListPoliciesResponse通过policies()取出策略列表，再用forEach逐个打印策略名称。
• 客户端构建的凭证来源由 SDK 默认凭证链自动解析，无需在代码中硬编码凭证。

基础场景：创建用户并假设角色（Learn the basics）

IAMScenario.java 是本文档标注的 Basics 示例，完整演示了 IAM 中最具代表性的权限流转链路。它需要 5 个命令行参数：

Usage: <username> <policyName> <roleName> <roleSessionName> <bucketName> Where: username - The name of the IAM user to create. policyName - The name of the policy to create. roleName - The name of the role to create. roleSessionName - The name of the session required for the assumeRole operation. bucketName - The name of the Amazon S3 bucket from which objects are read.

该场景按以下 6 步推进：

1. 创建一个无任何权限的 IAM 用户：调用createUser创建用户，随后借助IamWaiter轮询等待用户就绪（见createIAMUser方法中iamWaiter.waitUntilUserExists的用法）。
2. 创建授予 S3 权限的策略：策略文档（PolicyDocument）以 JSON 字符串形式内嵌在源码中，内容为允许s3:*作用于所有资源（Resource: "*"）。创建后同样通过IamWaiter.waitUntilPolicyExists等待策略生效。
3. 创建角色：角色的assumeRolePolicyDocument（信任策略）以 JSON 声明sts:AssumeRole动作，并将上一步创建的用户的 ARN 填入Principal.AWS，从而允许该用户扮演此角色。源码中在创建角色前有 30 秒的TimeUnit.SECONDS.sleep(30)等待，用于应对 IAM 的最终一致性。
4. 授予用户权限：通过attachRolePolicy将策略附加到角色；实现中会先调用listAttachedRolePolicies检查策略是否已附加，避免重复绑定（见attachIAMRolePolicy方法）。
5. 通过 STS 获取临时凭证并访问 S3：核心方法assumeRole展示了两段凭证链：
   • 先用新创建用户的AwsBasicCredentials构建StsClient，调用stsClient.assumeRole(roleRequest)换取临时凭证；
   • 再用返回的临时凭证（AwsSessionCredentials，含 accessKeyId、secretAccessKey、sessionToken）构建S3Client，执行listObjects列出指定 bucket 的对象。
6. 清理资源：依次调用deleteAccessKey、detachRolePolicy+deletePolicy+deleteRole、deleteUser删除全部临时资源。源码注释强调：先分离策略、再删除策略、最后删除角色。

这一场景揭示了 IAM 权限体系的完整闭环：用户（身份）→ 策略（权限定义）→ 角色（权限载体）→ 信任策略（谁可以扮演）→ STS 临时凭证（安全交付），对理解跨账号授权与最小权限原则极具参考价值。

单动作示例：16 个独立函数调用

文档列出以下 16 个单动作示例，每个文件对应一个 IAM API 调用，均位于 src/main/java/com/example/iam 下：

这些示例遵循一致的编码范式，从中可以提炼出三个重要的实现细节：

1. Waiter 轮询确保资源最终一致。IAM 服务存在最终一致性，因此 CreateUser.java 与 CreatePolicy.java 都在创建操作后调用IamWaiter.waitUntilUserExists/waitUntilPolicyExists，确保后续操作可安全依赖已创建的资源：

IamWaiter iamWaiter = iam.waiter(); CreateUserResponse response = iam.createUser(request); GetUserRequest userRequest = GetUserRequest.builder() .userName(response.user().userName()) .build(); WaiterResponse<GetUserResponse> waitUntilUserExists = iamWaiter.waitUntilUserExists(userRequest);

2. 列表接口处理分页。ListUsers.java 演示了基于marker的经典分页循环：当response.isTruncated()为true时，取出response.marker()作为下一页请求的marker参数继续拉取，直到遍历完全部用户；同时还会打印每个用户的permissionsBoundary信息，这是 IAM 权限边界审计的常用手段。

3. 幂等与防御性检查。AttachRolePolicy.java 在附加策略前先调用listAttachedRolePolicies遍历已附加策略，若目标策略已存在则直接返回，避免重复绑定导致的不一致。

场景示例：IAM Policy Builder API

IamPolicyBuilderExamples.java 是文档指定的第二个场景示例，核心价值在于展示 AWS SDK for Java 2.x 提供的对象化策略构建器（software.amazon.awssdk.policybuilder.iam包）。相比手工拼接 JSON 字符串，该 API 用类型安全的对象模型构建 IAM 策略，编译期即可发现结构错误。

该示例共演示 5 种策略构建方式：

1. 创建并上传策略（createAndUploadPolicyExample）

用 Builder 构建允许dynamodb:PutItem的策略并调用iam.createPolicy上传，然后通过IamPolicyWriter输出美化后的 JSON：

IamPolicy policy = IamPolicy.builder() // 'version' defaults to "2012-10-17". .addStatement(IamStatement.builder() .effect(IamEffect.ALLOW) .addAction("dynamodb:PutItem") .addResource("arn:aws:dynamodb:us-east-1:" + accountID + ":table/exampleTableName") .build()) .build(); iam.createPolicy(r -> r.policyName(policyName).policyDocument(policy.toJson())); return policy.toJson(IamPolicyWriter.builder().prettyPrint(true).build());

2. 基于现有策略派生新策略（createNewBasedOnExistingPolicyExample）

先从 IAM 拉取已有策略的默认版本（getPolicy→defaultVersionId→getPolicyVersion），对 JSON 文档 URL 解码后用IamPolicy.fromJson解析回对象；由于IamPolicy的组件均为不可变（immutable），再通过copy方法生成新实例并追加dynamodb:GetItem动作，最终上传为新策略。这是"在既有策略上增量扩展权限"的推荐做法。

3. 多条件策略（multipleConditionsExample）

对一张 DynamoDB 表配置 7 个数据面动作，并叠加两类条件运算符：

• IamConditionOperator.STRING_EQUALS.addPrefix("ForAllValues:")结合dynamodb:Attributes，限制只能访问指定列集合；
• IamConditionOperator.STRING_EQUALS.addSuffix("IfExists")结合dynamodb:Select，当请求携带该键时要求值必须为SPECIFIC_ATTRIBUTES。

4. 时间窗口策略（timeBasedPolicyExample）

用DATE_GREATER_THAN与DATE_LESS_THAN两个条件限定aws:CurrentTime，实现"仅在 2020-04-01 至 2020-06-30 期间允许读取 DynamoDB 数据"的访问控制窗口。

5. 指定 Principal 与跨账户授权（specifyPrincipalsExample / allowCrossAccountAccessExample）

• specifyPrincipalsExample构建一个资源策略，默认对所有人DENY访问 S3 存储桶，但通过ARN_NOT_EQUALS条件排除指定用户 ARN；
• allowCrossAccountAccessExample通过IamPrincipalType.AWS指定账号111122223333为 Principal，允许其对桶执行s3:PutObject，并配合s3:x-amz-acl条件要求bucket-owner-full-control，这是典型的跨账号写入授权模式。

此外，示例中获取当前账号 ID 的方式值得借鉴——通过StsClient.getCallerIdentity().account()动态解析，避免硬编码账号号。

测试验证：Access Analyzer 校验策略合法性

工程在 src/test/java/com/example/iam/IamPolicyBuilderExamplesTest.java 中为上述 5 个构建方法提供了 JUnit 5 集成测试（@Tag("IntegrationTest")）。测试的亮点是：

• 对生成的身份策略（PolicyType.IDENTITY_POLICY）与资源策略（PolicyType.RESOURCE_POLICY）调用AWS Access Analyzer 的validatePolicy做语法与语义校验，断言findings().size()为 0，即策略必须通过权威校验才算测试通过；
• createAndUploadPolicyExample/createNewBasedOnExisingPolicyExample测试会真实上传策略到 IAM 服务，由服务端在createPolicy时检查语法，随后删除策略完成清理。

这从测试层面印证了 Policy Builder 生成 JSON 的合法性与可部署性。

场景示例：构建并管理弹性服务（Build and manage a resilient service）

文档列出的另一场景是跨服务用例 resilient_service 的 Main.java，它展示如何构建一个返回图书、电影、歌曲推荐的负载均衡 Web 服务，并演示服务在故障下的响应与重构过程。该场景的主要操作包括：

• 使用 Amazon EC2 Auto Scaling 组，基于启动模板创建 EC2 实例并将实例数维持在指定范围内；
• 使用 Elastic Load Balancing 处理与分发 HTTP 请求；
• 监控 Auto Scaling 组中实例的健康状态，仅向健康实例转发请求；
• 在每个 EC2 实例上运行 Python Web 服务器处理 HTTP 请求，返回推荐结果并响应健康检查；
• 用 DynamoDB 表模拟推荐服务；
• 通过更新 AWS Systems Manager 参数控制 Web 服务器对请求与健康检查的响应行为。

该用例展示了 IAM 角色与权限在实际生产架构（弹性伸缩 + 负载均衡 + 故障注入）中的落地方式，可作为研究 IAM 在真实系统集成场景的延伸参考。

构建与运行方式

使用 Maven 构建

在 javav2/example_code/iam 目录下执行：

mvn package

Maven 会自动下载 AWS SDK for Java 的依赖并完成编译打包，产物为target/sdk-iam-examples-1.0.jar（名称由 pom 与 Makefile 共同约定）。若本机安装了make，也可直接执行：

make

使用脚本运行示例

工程提供了 run_example.sh，用法是以类名作为第一个参数，后续参数作为该类的命令行参数（用引号包裹）：

./run_example.sh CreateUser "my-test-user" ./run_example.sh IAMScenario "scenario-user" "scenario-policy" "scenario-role" "scenario-session" "my-bucket"

脚本内部通过mvn exec:java -Dexec.mainClass="com.example.iam.$className" -Dexec.args="$@"执行指定的主类。

运行 JUnit 测试

测试整体说明见 javav2 目录 README 的 Tests 章节，在 IAM 工程目录执行：

mvn test

测试类使用 JUnit 5，运行时会真实操作 AWS 资源（上传、删除策略，调用 Access Analyzer），可能产生账户费用，建议在测试专用账户中运行。

安全与成本提示

IAM 示例的 README.md 明确给出了以下注意事项，实践时应严格遵守：

• 运行示例可能产生 AWS 账户费用，具体见 AWS 定价与免费套餐说明；
• 运行测试同样可能产生费用；
• 遵循最小权限原则（grant least privilege）：授予的权限应以完成任务所需的最小集合为上限；
• 本仓库代码未在所有 AWS 区域经过测试，请以 AWS 区域服务清单为准。

额外资源

文档末尾为开发者列出了三类官方参考资料（均为 AWS 官方文档，非仓库链接）：

• IAM 用户指南（IAM User Guide）
• IAM API 参考（IAM API Reference）
• SDK for Java 2.x 的 IAM 包参考（software.amazon.awssdk.services.iam）

这些资料可与本文的源码示例相互印证，帮助理解每个 API 的完整请求/响应模型与权限边界。

• 示例工程
• 教程
• 后端