Cosmos Mongo API Client Encryption

Introduction

This repository provides a code sample in .NET and Java on how to use MongoDB Client-Side Field Level Encryption with Azure Cosmos DB Mongo API 4.2 (Supported features for version 4.2).

References

1. MongoDB Explict Encryption
2. MongoDB Automatic Decryption
3. MongoDB Encryption Key Management
4. MongoDB Fields and Encryption Types
5. MongoDB Use Automatic Client-Side Field Level Encryption with Azure

Requirements

It's recommended to create all the resources within the same region.

• Create a service principal and secret. Store TenantId, ClientId and the secret temporarely for next step reuse.

• Create a Function App. Choose the Runtime stack accordingly (sample code provided in .NET 6 or Java 11).

• Create a Key Vault.

• Create a Cosmos DB Mongo API account.

• Clone this repository.

Configuration

• Enable system-assigned idenity on your Function App.

• Configure Key Vault

  • Assign access policies
    • Assign Get, Create and Rotate Key Permissions and Get Secret Permissions to your Function Managed Identity
    • Assign Unwrap Key and Wrap Key Key Permissions to your service principal
  • Create Secrets
    • encryptionPrincipalTenantId: Service principal Tenant Id.
    • encryptionPrincipalClientId: Service principal Client/Application Id.
    • encryptionPrincipalClientSecret: Service principal Secret.
    • mongoOrderConnectionString: Primary Connection String of your Cosmos DB Mongo API (Get MongoDB connection string).
    • mongoVaultConnectionString: Same value as mongoOrderConnectionString.

• Create a database and collections.

  • Create orders collection: select Sharded, provide customerId as the Shard key, select Autoscale and provide 1000 as Collection Max RU/s.
  • Create keys collection: select Unsharded, select Autoscale and provide 1000 as Collection Max RU/s.

• Configure application settings

  • collectionName: orders
  • databaseName: <database name>
  • encryptionPrincipalTenantId: @Microsoft.KeyVault(VaultName=<key vault name>;SecretName=encryptionPrincipalTenantId)
  • encryptionPrincipalClientId: @Microsoft.KeyVault(VaultName=<key vault name>;SecretName=encryptionPrincipalClientId)
  • encryptionPrincipalClientSecret: @Microsoft.KeyVault(VaultName=<key vault name>;SecretName=encryptionPrincipalClientSecret)
  • mongoOrderConnectionString: @Microsoft.KeyVault(VaultName=<key vault name>;SecretName=mongoOrderConnectionString)
  • mongoVaultConnectionString: @Microsoft.KeyVault(VaultName=<key vault name>;SecretName=mongoVaultConnectionString)
  • mongoVaultNamespace: <database name>.keys
  • orderKeyName: OrdersCMK
  • vaultEndpoint: <key vault name>.vault.azure.net (do not include https://)

• Deploy Function application to Azure (Deploy using VS Code).

Running the sample

You can call Function APIs from Azure Portal or your favorite tool.

1. Call CreateKey function

   curl --request PUT 'https://<function app name>.azurewebsites.net/api/createkey/OrdersCMK?code=<function code>'
   

2. Check Key Vault Key and keys collection on Cosmos

   Cosmos DB key reference

   

   Key Vault key reference

   

3. Call CreateOrder function

   curl --request POST 'https://<function app name>.azurewebsites.net/api/orders/create?code=<function code>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
       "customerId": 1,
       "customerName": "John Doe",
       "shippingAddress": "John Doe's address",
       "amount": 200.00,
       "itens": 2
   }'
   

4. Call GetOrders function with different autoDecrypt values

   -- Returns Orders by CustomerId with Auto Decryption
   curl --request GET 'https://<function app name>.azurewebsites.net/api/orders?code=<function code>&customerId=1&autoDecrypt=true'
   
   -- Returns Orders by CustomerId without Auto Decryption
   curl --request GET 'https://<function app name>.azurewebsites.net/api/orders?code=<function code>&customerId=1&autoDecrypt=false'
   
   -- Returns Orders by CustomerName with Auto Decryption
   curl --request GET 'https://<function app name>.azurewebsites.net/api/orders?code=<function code>&customerName=John Doe&autoDecrypt=true'
   
   -- Returns Orders by CustomerName without Auto Decryption
   curl --request GET 'https://<function app name>.azurewebsites.net/api/orders?code=<function code>&customerName=John Doe&autoDecrypt=false'
   

5. Call RotateKey function

   curl --request PUT 'https://<function app name>.azurewebsites.net/api/rotatekey/OrdersCMK?code=<function code>'
   

6. Check new version of Key Vault Key and keys collection on Cosmos

   Cosmos DB key reference (new version)

   

   Key Vault key reference (new version)

   

7. Call GetOrders function with different autoDecrypt values

   -- Returns Orders by CustomerId with Auto Decryption
   curl --request GET 'https://<function app name>.azurewebsites.net/api/orders?code=<function code>&customerId=1&autoDecrypt=true'
   
   -- Returns Orders by CustomerId without Auto Decryption
   curl --request GET 'https://<function app name>.azurewebsites.net/api/orders?code=<function code>&customerId=1&autoDecrypt=false'
   
   -- Returns Orders by CustomerName with Auto Decryption
   curl --request GET 'https://<function app name>.azurewebsites.net/api/orders?code=<function code>&customerName=John Doe&autoDecrypt=true'
   
   -- Returns Orders by CustomerName without Auto Decryption
   curl --request GET 'https://<function app name>.azurewebsites.net/api/orders?code=<function code>&customerName=John Doe&autoDecrypt=false'
   

View Execution statistics

How to Contribute

If you find any errors or have suggestions for changes, please be part of this project!

1. Create your branch: git checkout -b my-new-feature
2. Add your changes: git add .
3. Commit your changes: git commit -m '<message>'
4. Push your branch to Github: git push origin my-new-feature
5. Create a new Pull Request 😄