AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

Azure で自動 Queryable Encryption を使用する

このガイドでは、MongoDB Queryable Encryption 機能を実装し、ドキュメント フィールドを自動的に暗号化および復号化し、キー管理に Azure Key Vault KMSを使用するアプリケーションを構築する方法について説明します。

このガイドの手順を完了すると、次のものが作成されます。

  • Azure Key Vault によって管理されるカスタマー マスター キー

  • カスタマー マスター キーを使用して暗号化されたフィールドを持つドキュメントを挿入する動作するクライアント アプリケーション

Tip

CMK(カスタマー マスター キー)

CMK の詳細については、暗号化のキーと Key Vaults のドキュメントをお読みください。

このガイドのコードを完了して実行するには、Queryable Encryption互換ドライバーと依存関係のインストールページに示されているように開発環境を設定する必要があります。

Tip

詳細: フルアプリケーション

このサンプル アプリケーションの完全なコードを確認するには、プログラミング言語に対応するタブを選択し、表示されたリンクに従ってください。 各サンプル アプリケーション リポジトリにはREADME.mdファイルが含まれており、環境を設定しアプリケーションを実行する方法を学習できます。

1

Azure Active Directory にアプリケーションを登録するには、Microsoft の公式の「 Microsoft ID プラットフォームにアプリケーションを登録するクイック スタート 」に従います。

重要

認証情報の記録

次の認証情報を必ず記録してください。

  • テナント ID

  • clientId

  • クライアントシークレット

このチュートリアルの後半で kmsProvidersオブジェクトを構築するには、これらの認証情報が必要です。アクセス トークンや自動認証情報取得を使用して認証することもできます。Azureで利用可能なすべての認証情報形式については、kmsProviders オブジェクト を参照してください。

2

新しいAzure Key Vaultインスタンスとカスタマー マスター キーを作成するには、Microsoft の公式の セット に従い、 Azure portal クイック スタートを使用してAzure Key Vault からキーを取得します。

重要

認証情報の記録

次の認証情報を必ず記録してください。

  • キー名

  • キー識別子(このガイドの後半ではkeyVaultEndpointと参照されます)

  • キー バージョン

このチュートリアルの後半では、 dataKeyOptsオブジェクトを構築するためにこれらが必要になります。

キーに対してクライアント アプリケーションのwrapとunwrap権限を付与します。

1

このチュートリアルのコード サンプルでは、次の変数を使用して Queryable Encryption ワークフローを実行します。

  • kmsProviderName - CMK の保存に使用している KMS。 このチュートリアルでは、この変数を"azure"に設定します。

  • uri - MongoDB 配置接続 URI。 MONGODB_URI環境変数で接続 URI を設定するか、値を直接置き換えます。

  • keyVaultDatabaseName - データ暗号化キー(DEK)が保存される MongoDB のデータベース。 この変数を"encryption"に設定します。

  • keyVaultCollectionName - DEK が保存される MongoDB のコレクション。 この変数を"__keyVault"に設定します。

  • keyVaultNamespace - DEK が保存される MongoDB の名前空間。 この変数に、ピリオドで区切られたkeyVaultDatabaseName変数とkeyVaultCollectionName変数の値を設定します。

  • encryptionDatabaseName -暗号化されたデータが保存される MongoDB のデータベース。 この変数を"medicalRecords"に設定します。

  • encryptedCollectionName - 暗号化されたデータが保存される MongoDB のコレクション。 この変数を"patients"に設定します。

次のコードを使用して、これらの変数を宣言できます。

// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local"const kmsProviderName = "<Your KMS Provider Name>";const uri = process.env.MONGODB_URI; // Your connection URIconst keyVaultDatabaseName = "encryption";const keyVaultCollectionName = "__keyVault";const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`;const encryptedDatabaseName = "medicalRecords";const encryptedCollectionName = "patients";

重要

キーヴォールトコレクションの名前空間権限

Key Vault コレクションはencryption.__keyVault名前空間にあります。 アプリケーションが MongoDB への接続に使用するデータベースユーザーが、この名前空間に対する 読み取り /書き込み権限を持っていることを確認します。

Tip

環境変数

このチュートリアルのサンプル コードは、設定する必要がある環境変数を参照します。 あるいは、コード内で値を直接置き換えることもできます。

これらの環境変数を設定する方法については、Github のサンプルアプリケーションに含まれる README.md ファイルを参照してください。

2

次の構造を持つ Azure KMS認証情報を含む変数を作成します。 このチュートリアルの「 Azure でアプリケーションを登録する 」の手順で記録した Azure Key Vault の認証情報を使用します。

kmsProviderCredentials = { azure: { tenantId: process.env["AZURE_TENANT_ID"], // Your Azure tenant ID clientId: process.env["AZURE_CLIENT_ID"], // Your Azure client ID clientSecret: process.env["AZURE_CLIENT_SECRET"], // Your Azure client secret },};

次の構造を持つ、CMK の認証情報を含む変数を作成します。 このチュートリアルの「 カスタマー マスター キーの作成」ステップで記録したカスタマー マスター キーの詳細を使用します。

customerMasterKeyCredentials = { keyVaultEndpoint: process.env["AZURE_KEY_VAULT_ENDPOINT"], // Your Azure Key Vault Endpoint keyName: process.env["AZURE_KEY_NAME"], // Your Azure Key Name};

次のオプションを含むautoEncryptionOptionsオブジェクトを作成します。

  • キーヴォールト コレクションの名前空間

  • Azure KMS 認証情報を含むkmsProviderCredentialsオブジェクト

const autoEncryptionOptions = { keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials,};

注意

自動暗号化オプション

自動暗号化オプションは、暗号化共有ライブラリに構成情報を提供し、暗号化されたフィールドにアクセスするときにアプリケーションの動作を変更します。

自動暗号化共有ライブラリの詳細については、「 Queryable Encryption のための自動暗号化共有ライブラリ」ページを参照してください。

コレクション内のデータの暗号化と復号化に使用されるクライアントを作成するには、接続 URI と 自動暗号化オプションを使用して新しいMongoClientをインスタンス化します。

const encryptedClient = Mongo(uri, autoEncryptionOptions);

フィールドを暗号化するには、暗号化スキーマに追加します。 フィールドでクエリを有効にするには、「クエリ」プロパティを追加します。 暗号化スキーマは、次のように作成します。

const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], },};

注意

前のコード例では、「ssn」フィールドと「 Billing 」フィールドの両方が暗号化されていますが、クエリは「ssn」フィールドのみです。

暗号化ヘルパー メソッドの API にアクセスするには、 ClientEncryptionをインスタンス化します。

const clientEncryption = encryptedClient.getClientEncryption()

ClientEncryptionクラスからアクセスされる暗号化ヘルパー メソッドを使用して、暗号化されたコレクションを作成します。 このメソッドは、暗号化されたフィールドのデータ暗号化キーを自動的に生成し、暗号化されたコレクションを作成します。

await clientEncryption.createEncryptedCollection( encryptedDatabaseName, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, });
3

ユーザの個人情報を説明するサンプルドキュメントを作成します。 次の例に示すように、暗号化されたクライアントを使用して、 patientsコレクションに挿入します。

const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, },}; const encryptedCollection = encryptedClient.getDB(encryptedDatabaseName).getCollection(encryptedCollectionName); const insertResult = await encryptedCollection.insertOne(patientDocument);
4

次のコード サンプルでは、暗号化されたフィールドに対して検索クエリを実行し、復号化されたデータを出力します。

const findResult = await encryptedCollection.findOne({ "patientRecord.ssn": "987-65-4320",});console.log(findResult);

上記のコード サンプルの出力は、次のようになります。

{ "_id": { "$oid": "648b384a722cb9b8392df76a" }, "name": "Jon Doe", "record": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111" } }, "__safeContent__": [ { "$binary": { "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=", "subType": "00" } } ]}

警告

MongoDB_ENUS_JAJP フィールドを変更しないでください

__safeContent__フィールドは Queryable Encryption に必須です。 このフィールドの内容は変更しないでください。

Queryable Encryptionの仕組みについては、 Queryable Encryption の基礎 を参照してください。

このガイドで言及されているトピックについて詳しくは、次のリンクを参照してください。

  • Queryable Encryption コンポーネントの詳細については、リファレンスページを参照してください。

  • カスタマー マスター キーとデータ暗号化キーの仕組みについては、「暗号化キーとキーヴォールト」ページを参照してください。

  • KMS プロバイダーが Queryable Encryption キーを管理する方法については、 KMS プロバイダーのページで確認してください。