チュートリアル: Azure Key Vault を使用して Azure Cosmos DB 資格情報を格納して使用する

  • [アーティクル]

適用対象: NoSQL MongoDB Cassandra Gremlin Table

重要

Azure Cosmos DB にアクセスする場合、システム割り当てマネージド ID を使用することをお勧めします。 マネージド ID ソリューションと証明書ベースのソリューションのどちらもニーズを満たしていない場合は、この記事の Azure Key Vault ソリューションを使用してください。

Azure Cosmos DB をデータベースとして使用している場合は、SDK、API エンドポイント、主キーまたは 2 次キーを使用して、データベース、コンテナー、項目に接続します。

エンドポイント URI と機密性の高い読み取り/書き込みキーを直接アプリケーション コードまたは構成ファイル内に保存することはお勧めしません。 このデータはホスト内の環境変数から読み取ることが理想的です。 Azure App Service では、Azure Cosmos DB アカウントのランタイム資格情報を開発者が安全でないクリア テキスト形式で保存しなくても、アプリ設定を使用することで、それらの資格情報を挿入できます。

Azure Key Vault では、資格情報への Azure App Service マネージド アクセスなどのサービスを提供しながらこれらの資格情報を安全に保存できるようにして、このベスト プラクティスへの取り組みをさらに進めます。 Azure App Service では、Azure Key Vault から資格情報を安全に読み取り、それらの資格情報を実行中のアプリケーションに挿入します。

開発者は、このベスト プラクティスを利用して、開発中に Azure Cosmos DB エミュレーターや Azure Cosmos DB を無料で試すといったツールの資格情報を保存できます。 それにより、運用チームが、実行時に正しい運用設定が挿入されるようにすることができます。

このチュートリアルでは、次の作業を行う方法について説明します。

  • Azure Key Vault インスタンスを作成する
  • Azure Cosmos DB 資格情報をシークレットとしてキー コンテナーに追加する
  • Azure App Service リソースを作成して登録し、"読み取りキー" アクセス許可を付与する
  • キー コンテナーのシークレットを App Service リソースに挿入する

注意

このチュートリアルとサンプル アプリケーションでは、Azure Cosmos DB for NoSQL アカウントを使用します。 同じ手順のうち、多くは他の API を使用して実行できます。

前提条件

開始する前に: Azure Cosmos DB の資格情報を取得する

開始する前に、既存のアカウントの資格情報を取得します。

  1. 既存の Azure Cosmos DB for NoSQL アカウントの Azure portal ページに移動します。

  2. Azure Cosmos DB for NoSQL アカウント ページで、[キー] ナビゲーション メニュー オプションを選択します。

    Azure Cosmos DB SQL API アカウント ページのスクリーンショット。ナビゲーション メニューで [キー] オプションが強調表示されています。

  3. URI フィールドと PRIMARY KEY フィールドの値を記録します。 これらの値は、このチュートリアルで後ほど使用します。

    Azure Cosmos DB SQL API アカウントの各種資格情報を含む [キー] ページのスクリーンショット。

Azure Key Vault リソースを作成する

まず、NoSQL 用 API の資格情報を保存する新しいキー コンテナーを作成します。

  1. Azure portal にサインインします。

  2. [リソースの作成] > [セキュリティ] > [Key Vault] の順に選択します。

  3. [キー コンテナーの作成] ページで、次の情報を入力します。

    設定 説明
    サブスクリプション この Azure Cosmos アカウントに使用する Azure サブスクリプションを選択します。
    リソース グループ リソース グループを選択するか、 [新規作成] を選択し、新しいリソース グループの一意の名前を入力します。
    キー コンテナー名 グローバルに一意のキー コンテナー名を入力します。
    リージョン Azure Cosmos DB アカウントをホストする地理的な場所を選択します。 データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。
    [価格レベル] [Standard] を選択します。

  4. 残りの設定は既定値のままにします。

  5. [確認と作成] を選択します。

  6. 指定した設定を確認し、[作成] を選択します。 アカウントの作成には数分かかります。 ポータル ページに "デプロイが完了しました" と表示されるまで待ってから移動します。

Azure Cosmos DB アクセス キーの Key Vault への追加

ここで、Azure Cosmos DB の資格情報をシークレットとしてキー コンテナーに格納します。

  1. [Go to resource] (リソースに移動) を選択して、Azure Key Vault リソース ページに移動します。

  2. Azure Key Vault リソース ページで、[シークレット] ナビゲーション メニュー オプションを選択します。

  3. メニューから [生成/インポート] を選択します。

    キー コンテナー メニューの [生成/インポート] オプションのスクリーンショット。

  4. [Create a secret] (シークレットの作成) ページで、次の情報を入力します。

    設定 説明
    Upload options 手動
    名前 cosmos-endpoint
    シークレット値 このチュートリアルで先ほどコピーした URI を入力します。

    Azure portal の [Create a secret] (シークレットの作成) ダイアログのスクリーンショット。URI シークレットの詳細が表示されています。

  5. [作成] を選択して、新しい cosmos-endpoint シークレットを作成します。

  6. もう一度メニューから [生成/インポート] を選択します。 [Create a secret] (シークレットの作成) ページで、次の情報を入力します。

    設定 説明
    Upload options 手動
    名前 cosmos-readwrite-key
    シークレット値 このチュートリアルで先ほどコピーした主キーを入力します。

    Azure portal の [Create a secret] (シークレットの作成) ダイアログのスクリーンショット。主キー シークレットの詳細が表示されています。

  7. [作成] を選択して、新しい cosmos-readwrite-key シークレットを作成します。

  8. シークレットを作成すると、それらが [シークレット] ページ内のシークレットの一覧に表示されます。

    キー コンテナーのシークレットの一覧のスクリーンショット。

  9. 各キーを選択し、最新バージョンを選択して、シークレット識別子をコピーします。 cosmos-endpoint と cosmos-readwrite-key シークレットの識別子は、このチュートリアルで後ほど使用します。

    ヒント

    シークレット識別子は、https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version-id> の形式になります。 たとえば、キー コンテナーの名前が msdocs-key-vault、キーの名前が cosmos-readwrite-key、バージョンが 83b995e363d947999ac6cf487ae0e12e の場合、シークレット識別子は https://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e になります。

    cosmos-readwrite-key という名前のキー コンテナー シークレットのシークレット識別子のスクリーンショット。

Azure Web アプリを作成して Azure Key Vault に登録する

このセクションでは、新しい Azure Web アプリを作成し、サンプル アプリケーションをデプロイし、その後に Web アプリのマネージド ID を Azure Key Vault に登録します。

  1. cosmos-db-nosql-dotnet-sample-web-environment-variables テンプレートを使用して、新しい GitHub リポジトリを作成します。

  2. Azure portal で [リソースの作成] > [Web] > [Web アプリ] を選択します。

  3. [Web アプリの作成] ページで、[基本情報] タブに次の情報を入力します。

    設定 説明
    サブスクリプション この Azure Cosmos アカウントに使用する Azure サブスクリプションを選択します。
    リソース グループ リソース グループを選択するか、 [新規作成] を選択し、新しいリソース グループの一意の名前を入力します。
    名前 グローバルに一意の Web アプリ名を入力します。
    発行 [コード] を選択します。
    ランタイム スタック [.NET 6 (LTS)] を選択します。
    オペレーティング システム [Windows] を選択します。
    [リージョン] Azure Cosmos DB アカウントをホストする地理的な場所を選択します。 データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。

  4. 残りの設定は既定値のままにします。

  5. [次へ: デプロイメント] を選択します。

  6. [デプロイメント] タブで、次の情報を入力します。

    設定 説明
    継続的なデプロイ [有効化] を選択します。
    GitHub アカウント [承認] を選択します。 GitHub アカウント承認プロンプトに従って、新しく作成した GitHub リポジトリを読み取る Azure アクセス許可を付与します。
    組織 新しい GitHub リポジトリの組織を選択します。
    リポジトリ 新しい GitHub リポジトリの名前を選択します。
    ブランチ [main](メイン) を選択します。

  7. [確認と作成] を選択します。

  8. 指定した設定を確認し、[作成] を選択します。 アカウントの作成には数分かかります。 ポータル ページに "デプロイが完了しました" と表示されるまで待ってから移動します。

  9. Web アプリケーションが最初に Web アプリにデプロイされるまで、場合によってはさらに数分待つ必要があります。 Azure Web アプリ リソース ページで、[参照] を選択して、アプリの既定の状態を確認します。

    資格情報のない既定の状態の Web アプリケーションのスクリーンショット。

  10. [ID] ナビゲーション メニュー オプションを選択します。

  11. [ID] ページで、[システムが割り当て済み] のマネージド ID で [オン] を選択し、[保存] を選択します。

    [ID] ページでシステム割り当てマネージド ID が有効になっているスクリーンショット。

Azure Key Vault シークレットを Azure Web App アプリ設定として挿入する

最後に、キー コンテナーに保存されているシークレットを Web アプリ内のアプリ設定として挿入します。 これにより、このアプリ設定で、資格情報をクリア テキストで保存することなく、実行時に資格情報がアプリケーションに挿入されます。

  1. Azure portal でキー コンテナー ページに戻ります。 ナビゲーション メニューで [アクセス ポリシー] を選択します。

  2. [アクセス ポリシー] ページで、メニューから [作成] を選択します。

    [アクセス ポリシー] メニューの [作成] オプションのスクリーンショット。

  3. [アクセス ポリシーを作成する] ページの [アクセス許可] タブで、[シークレットのアクセス許可] の [取得] オプションを選択します。 [次へ] を選択します。

    [シークレットのアクセス許可] で [取得] アクセス許可が有効になっているスクリーンショット。

  4. [プリンシパル] タブで、このチュートリアルで先ほど作成した Web アプリの名前を選択します。 [次へ] を選択します。

    アクセス許可に割り当てられている Web アプリ マネージド ID のスクリーンショット。

    注意

    この例のスクリーンショットでは、Web アプリの名前は msdocs-dotnet-web です。

  5. [次へ] をもう一度選択して [アプリケーション] タブをスキップします。[確認 + 作成] タブで、指定した設定を確認し、[作成] を選択します。

  6. Azure portal で Web アプリ ページに戻ります。 ナビゲーション メニューから [構成] を選択します。

  7. [構成] ページで、[新しいアプリケーション設定] を選択します。 [アプリケーション設定の追加/編集] ダイアログで、次の情報を入力します。

    設定 内容
    名前 CREDENTIALS__ENDPOINT
    キー このチュートリアルで先ほど作成した、キー コンテナー内の cosmos-endpoint シークレットのシークレット識別子を取得します。 識別子は、@Microsoft.KeyVault(SecretUri=<secret-identifier>) の形式で入力します。

    ヒント

    環境変数の値に、1 つのアンダースコアではなく 2 つのアンダースコア (__) があることを確認します。 二重アンダースコアは、すべてのプラットフォームで .NET によってサポートされるキー区切り記号です。 詳細については、環境変数の構成に関するページを参照してください。

    注意

    たとえば、シークレット識別子が https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07 の場合、参照は @Microsoft.KeyVault(SecretUri=https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07) になります。

    キー コンテナー シークレットを参照する新しいアプリ設定を含む [アプリケーション設定の追加/編集] ダイアログのスクリーンショット。

  8. [OK] を選択して新しいアプリ設定を保持します

  9. [新しいアプリケーション設定] をもう一度選択します。 [アプリケーション設定の追加/編集] ダイアログで、次の情報を入力し、[OK] を選択します。

    設定 内容
    名前 CREDENTIALS__KEY
    キー このチュートリアルで先ほど作成した、キー コンテナー内の cosmos-readwrite-key シークレットのシークレット識別子を取得します。 識別子は、@Microsoft.KeyVault(SecretUri=<secret-identifier>) の形式で入力します。

  10. [構成] ページに戻り、[保存] を選択して Web アプリのアプリ設定を更新します。

    [構成] ページのメニューの [保存] オプションのスクリーンショット。

  11. Web アプリが新しいアプリ設定で再起動するまで数分待ちます。 この時点で、新しいアプリ設定には、それらがキー コンテナーの参照であることが示されています。

    Web アプリの 2 つのアプリ設定にキー コンテナーの参照であることが指定されているスクリーンショット。

  12. ナビゲーション メニューで [概要] を選択します。 [参照] を選択して、アプリに資格情報が設定されていることを確認します。

    有効な Azure Cosmos DB for NoSQL アカウント資格情報を含む Web アプリケーションのスクリーンショット。

次のステップ