{"id":3188,"date":"2021-07-29T08:58:26","date_gmt":"2021-07-29T15:58:26","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=3188"},"modified":"2022-03-30T22:31:04","modified_gmt":"2022-03-31T05:31:04","slug":"always-encrypted","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/always-encrypted\/","title":{"rendered":"A tour of Always Encrypted for Azure Cosmos DB"},"content":{"rendered":"

Always encrypted for Azure Cosmos DB provides encryption support on the client-side to protect sensitive data by encrypting data such as credit card numbers or national identification numbers, before it gets transferred over the wire to be stored in Azure Cosmos DB. Always encrypted allows clients to protect JSON property values which are deemed sensitive, by means of client encryption policies which can be configured on the containers just like any other policy such as indexing policy etc.<\/p>\n

How to start using always encrypted<\/h2>\n

Let us try to run the sample code. Encrypting data using always encrypted requires an initial setup as always encrypted relies on Azure Key Vault (when the KeyEncryptionKeyResolver<\/em>\u00a0selected is Azure Key Vault – I will get to that in a bit) to store wrapped data encryption keys which are encrypted using a customer-provided key encryption key created (and stored) in Azure Key Vault. In this case, Azure Key Vault provides all the required services to wrap (Encrypt) and unwrap (Decrypt) the data encryption key in use.<\/p>\n

Step 1: Enable client application access<\/h4>\n

When you have an application that connects to your Azure Cosmos DB instance, you can create an identity for the app. This identity is known as a service principal. Access to resources is restricted by the roles assigned to the service principal, giving you control over which resources can be accessed and at which level.<\/p>\n

Let us look at how to use the portal to create the service principal in the Azure portal. Let us focus on a single-tenant application where the application is intended to run within only one organization.<\/p>\n

    \n
  1. Sign into your Azure Account through the\u00a0Azure portal<\/a>.<\/li>\n
  2. Select Azure Active Directory\/App registrations.<\/li>\n
  3. Select New registration.<\/li>\n
  4. Name the application. Select a supported account type, which determines who can use the application.<\/li>\n<\/ol>\n

    There you go, now you have your app registered.<\/p>\n

    \"Graphical<\/p>\n

    Step 2: Get tenant and app ID values for signing in<\/h4>\n

    You would need these two IDs to create an instance of the ClientCertificateCredential<\/em> class (which is a token credential that can provide an OAuth Token) with the details needed to authenticate against Azure Active Directory with a certificate, when using certificate-based authentication. This is how Azure Key Vault would allow the set of operations like wrapping and unwrapping of data encryption keys. To get those values, use the following steps:<\/p>\n

      \n
    1. Select\u00a0Azure Active Directory\/App registrations\u00a0in Azure AD, select your application.<\/li>\n
    2. Copy the Directory (tenant) ID and store it in your application app settings.<\/li>\n<\/ol>\n

      \"Graphical<\/p>\n

      \"Graphical<\/p>\n

      Step 3: Authentication: Two options<\/h4>\n

      Let’s look at couple of authentication methods available for service principals: password-based authentication (application secret) and certificate-based authentication. We recommend using a certificate so this is shown as part of the sample code, but you can also create an application secret to get a token via ClientCredential<\/em><\/p>\n

      Option 1: Upload a certificate.<\/h5>\n

      You can use an existing certificate if you have one. Optionally, you can create a self-signed certificate for\u00a0testing purposes only<\/em>. To generate a certificate, you can use Azure Key Vault.<\/p>\n

      To generate the certificate using Azure Key Vault:<\/h5>\n
        \n
      1. On the Key Vault properties pages, select\u00a0Certificates.<\/li>\n
      2. Click on\u00a0Generate\/Import.<\/li>\n
      3. On the\u00a0Create a certificate\u00a0screen choose the following values:<\/li>\n<\/ol>\n