aws-sdk-java-v2-secrets-manager

AWS SDK for Java 2.x - AWS Secrets Manager

概要

このスキルを使用すると、Java サービスから AWS Secrets Manager を使ってアプリケーションのシークレットを管理できます。

本番環境で重要となる運用フローに重点を置いています。

• シークレットを安全に取得してデシリアライズする方法
• ローカルキャッシュを追加するタイミング
• 値をログや設定ファイルに漏らさずに、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. アプリケーション設定ごとに再利用可能なクライアントを 1 つ作成する

環境に特別な要件がない限り、リージョンを明示し、デフォルトの認証情報プロバイダーチェーンを使用する単一の 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