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