aws-sdk-java-v2-secrets-manager

AWS SDK for Java 2.x - AWS Secrets Manager

概述

使用此技能，通过 AWS Secrets Manager 管理 Java 服务的应用程序机密。

重点关注生产环境中重要的运维流程：

• 如何安全地检索和反序列化机密
• 何时添加本地缓存
• 如何在 Spring Boot 中集成机密访问，同时避免将机密值泄露到日志或配置文件中

较长的 API 说明和详细的设置内容请参阅随附的参考资料。

适用场景

在以下情况下使用此技能：

• 将硬编码的密码、API 密钥或令牌替换为托管机密
• 在运行时加载数据库凭证或第三方 API 凭证
• 添加缓存以降低 Secrets Manager 的延迟和 API 成本
• 处理 AWSCURRENT 和 AWSPENDING 等机密版本阶段
• 将机密访问接入 Spring Boot Bean 或配置服务
• 为应用程序做好轮换准备，或设置 Lambda 轮换工作流

典型触发短语包括 java secrets manager、spring boot secret、aws secret cache、load db credentials from secrets manager 和 rotate secret。

说明

1. 编写访问代码前，先确定机密的模型

确定：

• 机密名称和路径约定
• 值是纯文本还是结构化 JSON
• 哪个应用程序边界允许读取机密
• 调用方是否需要在每次请求时获取最新值，还是可以接受缓存

对于数据库连接详情等包含多个字段的凭证，优先使用 JSON 机密。

2. 每个应用程序配置创建一个可复用的客户端

使用单个 SecretsManagerClient，明确指定区域，并使用默认凭证提供程序链，除非环境要求采用更具体的配置。

在配置代码中创建客户端，而不要在业务服务中创建。

3. 在边界层检索并反序列化

在集成边界处：

• 使用 GetSecretValueRequest 获取机密
• 将 JSON 反序列化为类型化对象或经过验证的映射
• 将 AWS 异常转换为应用程序级错误
• 绝不记录 secretString()，也不要将其包含在抛出的异常消息中

4. 仅在确实能解决问题时添加缓存

在以下情况下使用缓存：

• 频繁读取机密
• 启动或请求处理的延迟很重要
• 重复查询的成本不可忽视

清楚说明缓存 TTL 的预期，尤其是在机密会轮换时。

5. 针对轮换和分阶段版本进行设计

如果机密会轮换：

• 通过精简的服务层读取，以便集中管理缓存失效和重试行为
• 了解哪些调用方必须在验证工作流期间兼容 AWSPENDING
• 测试应用程序在缓存过期前的窗口期或轮换部分失败时的行为

6. 验证端到端行为

发布前：

• 验证 IAM 权限和 KMS 访问权限
• 测试机密不存在、区域错误和解密失败等情况
• 确认机密不会出现在日志、指标或调试端点中
• 验证数据库或 API 客户端在凭证轮换时能正确刷新

示例

示例 1：可复用的客户端和类型化机密查询

@Configuration
public class SecretsConfiguration {

    @Bean
    SecretsManagerClient secretsManagerClient() {
        return SecretsManagerClient.builder()
            .region(Region.of("eu-south-2"))
            .credentialsProvider(DefaultCredentialsProvider.create())
            .build();
    }
}

@Service
public class SecretsService {

    private final SecretsManagerClient client;
    private final ObjectMapper objectMapper;

    public SecretsService(SecretsManagerClient client, ObjectMapper objectMapper) {
        this.client = client;
        this.objectMapper = objectMapper;
    }

    public DatabaseSecret loadDatabaseSecret(String secretId) throws JsonProcessingException {
        GetSecretValueResponse response = client.getSecretValue(
            GetSecretValueRequest.builder().secretId(secretId).build()
        );
        return objectMapper.readValue(response.secretString(), DatabaseSecret.class);
    }
}

示例 2：缓存高频机密查询

public class CachedSecretsService {

    private final SecretCache cache;

    public CachedSecretsService(SecretsManagerClient client) {
        this.cache = new SecretCache(client);
    }

    public String apiToken(String secretId) {
        return cache.getSecretString(secretId);
    }
}

仅当应用程序能够接受所选的缓存刷新行为时，才使用此模式。

最佳实践

• 使用分层机密名称，使其与领域和环境边界相匹配。
• 优先使用类型化 JSON 反序列化，避免在代码库各处散布字符串解析逻辑。
• 将机密检索放在基础设施服务中，而不是控制器或实体中。
• 复用 SDK 客户端和缓存实例。
• 将最小权限 IAM、KMS 权限与 CloudTrail 可见性结合使用。
• 在代码和运维文档中明确轮换行为。

约束和警告

• 不要记录机密值、序列化后的机密对象或已解密的载荷片段。
• 根据 TTL 和刷新行为，缓存值在轮换期间或之后可能仍然过时。
• IAM 策略、KMS 策略、区域不匹配或版本已删除，都可能导致机密访问失败；请明确处理这些情况。
• 并非所有机密结构或集成都支持自动轮换。
• 大型或频繁变更的机密可能不适合进行积极的内存缓存。

参考资料

• references/api-reference.md
• references/caching-guide.md
• references/spring-boot-integration.md

相关技能

• aws-sdk-java-v2-core
• aws-sdk-java-v2-kms
• spring-boot-dependency-injection