{"id":1950,"date":"2018-11-27T00:00:00","date_gmt":"2018-11-27T00:00:00","guid":{"rendered":"https:\/\/azure.microsoft.com\/blog\/azure-cosmos-db-and-multi-tenant-systems"},"modified":"2023-05-11T15:35:47","modified_gmt":"2023-05-11T22:35:47","slug":"azure-cosmos-db-and-multi-tenant-systems","status":"publish","type":"post","link":"https:\/\/azure.microsoft.com\/en-us\/blog\/azure-cosmos-db-and-multi-tenant-systems\/","title":{"rendered":"Azure Cosmos DB and multi-tenant systems"},"content":{"rendered":"

In this blog post, we will discuss how to build a multi-tenant system on Azure Cosmos DB. Azure Cosmos DB itself is a multi-tenant PaaS offering on Microsoft Azure. Building a multi-tenant system on another multi-tenant system can be challenging, but Azure provides us all the tools to make our task easy. An example of a multi-tenant system would be a company providing background check services that any other company can use in their HR system. For the purposes of this blog post we are going to use this example and continue from the point of view of company providing background checks as a service. We will refer to this company as \u201cpublisher.\u201d<\/p>\n

Let\u2019s begin to discuss how you can build a multi-tenant system that will store sensitive user data. Data isolation and security is the most important aspect of any system. We must design the system so that each tenant\u2019s data is isolated from one another<\/strong>. The data stored in any given tenant should be divided into compartments so one tenant breach cannot flow into another tenant. This would be similar to compartmentalizing the hull of a ship to reduce floodability<\/a>.<\/p>\n

To increase the isolation and protection of customer data in a multi-tenant system, we should build the system with only one approved service that can have just in time (JIT) access to tenant data. We need to set up a different system principal for each customer\u2019s data partition so that the scope of access for any principal is segmented by customer. We don\u2019t want a service to have access to all tenant data, that is a big security risk. What we want is the service to get the access permission for one tenant JIT. The benefit of this approach is tenants can rotate their certificates and keys anytime.<\/p>\n

Every tenant can manage their data using the publisher’s front-end service (FES), but they cannot directly manipulate their own data in Azure Cosmos DB collections. This isolation will remove the need for every tenant to have access to master and read-only keys. All the data access will happen through a service and no one will access Azure Cosmos DB unless directly on the portal or through code. The publisher application, which manages the customer data, is hosted in a different Azure Active Directory tenant and subscription, which is separate from that of the customer\u2019s tenant and data.<\/p>\n

However, the tenant will own all the collections and data without having direct access to the data. This simplifies the billing for all data storage and throughput that the tenant is directly billed, but is a tricky requirement. Let\u2019s see how you can manage this requirement.<\/p>\n

The main actors of this solution are Azure Managed Applications<\/a>, Daemon Application<\/a>, Azure Cosmos DB<\/a>, Azure Key Vault<\/a> and Azure Active Directory<\/a> (AAD). The following paragraphs will help us understand each of the mentioned solutions.<\/p>\n

An Azure Managed Application is like a service catalog in the marketplace, but with one key difference. In a managed application, the resources are provisioned in a resource group that is managed by the publisher of the app. The resource group is present in the consumer’s subscription, but an identity in the publisher’s tenant has access to the resource group in the customer subscription. As the publisher, you specify the cost of ongoing support for the solution<\/a>.<\/p>\n

\"Customer<\/p>\n

Managed applications reduce barriers to consumers using your solutions. They do not need expertise in cloud infrastructure to use your solution. Consumers have limited access to the critical resources. They don’t need to worry about making a mistake when managing it. Managed applications enable customers to adopt your solution without needing expertise in the underlying Azure infrastructure.<\/p>\n

Managed applications enable you to establish an ongoing relationship with your consumers. You define the terms for managing the application, and all charges are handled through Azure billing.<\/p>\n

Although customers deploy these managed applications in their subscriptions, they do not have to maintain, update, or service them. You can ensure that all customers are using approved versions. Customers do not have to develop application specific domain knowledge to manage these applications. They automatically acquire application updates without the need to worry about troubleshooting and diagnosing issues with the applications. The advantages of an Azure Managed Application is billing, separation of data between different tenants, easy maintenance, among other benefits. For more details, read more about Azure Managed Applications<\/a>.<\/p>\n

After deploying a tenant managed application, create a daemon application. Follow the instructions on how to create an AAD application and service principal<\/a> that can access resources. This daemon application has its own identity and access to tenant subscription. This application is the bridge between the customer tenant application and the service provider (publisher).<\/p>\n

It is important to understand a few things. First, user interaction is not possible with a daemon application, which requires the application to have its own identity. An example of a daemon application is a batch job, or an operating system service running in the background. This type of application requests an access token by using its application identity and presenting its application ID, credentials (password or certificate), and application ID URI to AAD. After a successful authentication, the daemon receives an access token which represents the identity of the application from AAD and is then used to call the web API.<\/p>\n

The magic of Azure Managed Applications is that the publisher can access the customer subscription resources it managed as if these resources are located within a subscription in the publisher\u2019s AAD tenant. The customer tenant subscription resources are visible to the customer in their own Azure subscription, but are not accessible due to an Azure Resource Lock. Only the publisher has full access to the managed application resources in the customer\u2019s subscription.<\/p>\n

After creating the daemon application, you need to register it in the identity and access (IAM) of Azure Cosmos DB instance, which is deployed as a managed resource component of the customer tenant subscription.<\/p>\n

The last piece you will develop is the front-end service (FES). This the service used to manage the components in the customer tenant. This service cannot directly access Azure Cosmos DB until it goes through the orchestration of taking the daemon application identity. The following illustrates a step-by-step walkthrough for the FES interaction with the customer\u2019s subscription resources.<\/p>\n

\"FES<\/p>\n

FES takes over the daemon application identity at the run time. FES also has its own managed identity (MSI) which is registered in Key Vault for access. At the run time, the FES connects to the Key Vault using the Azure MSI and obtains the certificate credential, which in turn uses a credential to obtain a token from AAD representing the daemon application (Step 1).<\/p>\n

Once the FES gets the certificates, it assumes the identity of daemon service by using the client ID and secret certificate. Then it will call AAD to get the access token for the Managed Application (Step 2). This FES uses Azure Active Directory Authorization DLL (AAD DLL). See the FES code snippet below, which helps FES to get the token from AAD.<\/p>\n

\r\nusing Microsoft.Azure.KeyVault;\r\nusing Microsoft.Azure.Services.AppAuthentication;\r\nusing Microsoft.IdentityModel.Clients.ActiveDirectory;\r\n\r\nstring secretIdentifier = \" key vault secretIdentifier for daemon app goes here \";\r\nvar tokenCache = TokenCache.DefaultShared;\r\nstring pubTenantId = \" publisher\u2019s Azure AD directory id here \";\r\n\r\n\/\/\/\/ get app key from Key Vault (\u2026 let me know if you need a sample for reading a certificate\/private key instead of a secret\r\nvar azureServiceTokenProvider = new AzureServiceTokenProvider();\r\n\r\nvar keyVaultClient = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));\r\nstring secret = keyVaultClient.GetSecretAsync(appKey)\r\n.GetAwaiter()\r\n.GetResult();\r\n\r\n\/\/\/\/ now get a token representing the Daemon app, using the secret credential of the Daemon Azure AD application.  Resource is the appropriate Azure resource Uri.\r\nstring daemonAppId = \"daemon Azure AD application Id\";\r\nstring authString = $\"https:\/\/login.microsoftonline.com\/{pubTenantId}\";\r\nstring daemonAppResourceUri = \"https:\/\/management.core.windows.net\/\";\r\nvar clientCredential = new ClientCredential(daemonAppId, secret.Value);\r\nvar authenticationContext = new AuthenticationContext(authString, false, tokenCache);\r\n\r\nvar authnResult = authenticationContext.AcquireTokenAsync(resourceUri, clientCredential)\r\n.GetAwaiter()\r\n.GetResult();\r\n\r\nstring daemonToken = authnResult.AccessToken;\r\n\r\n\/\/\/\/ alternately, to use a certificate you would substitute the above variables:\r\n\/\/\/\/     var clientCredential = new ClientAssertionCertificate(clientId, certificate);<\/pre>\n
Once the access token is obtained by FES, it calls into Azure Cosmos DB to get the master key (Step 3 and 4). This is accomplished by using the access token of the daemon application. For this FES we pass the AAD token in header.<\/p>\n
\r\nusing Microsoft.Azure.Management.CosmosDB.Fluent;\r\nusing Microsoft.Azure.Management.Fluent;\r\nusing Microsoft.Azure.Management.ResourceManager.Fluent;\r\nusing Microsoft.Azure.Management.ResourceManager.Fluent.Core;\r\n\r\nstring subscriptionId = \" subscribing customer\u2019s subscription id \";\r\nstring resourceGroupName = \" subscribing customer\u2019s resource group name \";\r\nstring databaseAccountName = \" subscribing customer\u2019s Cosmos DB account name \";\r\n\r\nvar credential = new AzureCredentials(new TokenCredentials(daemonToken), pubTenantId, AzureEnvironment.AzureGlobalCloud);\r\n\r\nvar azure = Azure.Configure()\r\n.WithLogLevel(HttpLoggingDelegatingHandler.Level.Basic)\r\n.Authenticate(credential)\r\n.WithSubscription(subscriptionId);\r\n\r\nvar cosmosDbAccounts = azure.CosmosDBAccounts;\r\nvar readWritekeys = cosmosDbAccounts.ListKeysAsync(resourceGroupName, databaseAccountName)\r\n.GetAwaiter()\r\n.GetResult();<\/pre>\n
Once it has the master key, it starts accessing the Cosmos DB (Step 5).<\/p>\n
\r\nusing Microsoft.Azure.Documents;\r\nusing Microsoft.Azure.Documents.Client;\r\n\r\nstring cosmosDBendpointUri = $\"{databaseAccountName}.documents.azure.com:443\/\";\r\n\r\nstring masterKey = readWritekeys.PrimaryMasterKey; \/\/\/\/ pick the one you need\r\n\r\nvar connectionPolicy = new ConnectionPolicy { ConnectionMode = ConnectionMode.Direct, ConnectionProtocol = Protocol.Tcp };\r\n\r\nvar documentClient = new DocumentClient(new Uri(cosmosDBendpointUri), masterKey, connectionPolicy);\r\n\r\nclient.OpenAsync()\r\n.GetAwaiter()\r\n.GetResult();<\/pre>\n
You may wonder why the daemon application identity, rather than an Azure MSI<\/a> representing the FES, is used to retrieve the Azure Cosmos DB keys. The answer is security isolation, JIT access, getting the daemon application secret from Key Vault, and accessing AAD to get it\u2019s token all help support security isolation. This orchestration makes sure that FES does not have access to all the tenants\u2019 keys. It can get access to keys JIT only by using the daemon identity.<\/p>\n
This system has the following advantages:<\/p>\n