Identity-Based Authentication with Azure Cosmos DB and Orbital
Identity is important. Without it, it’s difficult to trace actions in a system. It helps answer important questions like “who made this change?” and “who has permission to make this change?” These questions become particularly important when determining what actions an individual or application should be allowed to perform.
Typically, in the early stages of developing an application, we choose to use secrets through a secret store like Azure Key Vault to manage credentials such as connection strings. However, with resources like Azure Cosmos DB, a connection string can provide significantly more permissions than we may want an individual identity, such as an application or user, to have.
For instance, a Cosmos DB connection string containing a read-write account key gives the consumer broad access to the database, including the ability to read, write, update, and delete data. While storing this connection string in Key Vault helps protect the credential, it doesn’t limit the permissions associated with it.
There’s significantly less control over what an individual consumer can do when using these account keys.
Updating Orbital
With that in mind, I’ve updated Orbital to support both connection-string and identity-based authentication using the Cosmos DB SDK.
In version 3.0.1, currently in pre-release, I’ve introduced OrbitalCosmosAuthenticationOptions. This class encapsulates authentication configuration so consumers can either use connection strings or Azure credential-based authentication.
With identity-based authentication, developers can authenticate using their Azure CLI credentials locally, while applications deployed to Azure can authenticate using their own identities.
This also allows us to follow Microsoft’s recommended practices and disable key-based authentication entirely.
However, I want Orbital to be useful for both production and testing applications. Rather than requiring one authentication approach, I’ve given consumers the option of using either method. This maintains compatibility with applications that currently use connection strings while allowing others to take advantage of identity-based authentication.
Updating the Blog API
In my Blog API, I’ve updated the NuGet package to the latest pre-release version of Orbital and made a couple of changes to the configuration.
First, we need to update our application settings to include the Cosmos DB account endpoint:
{
"CosmosDbAccountEndpoint": "{{BLOG_DB_ENDPOINT}}"
}
Then, we update the DataFacade to configure Orbital to use DefaultAzureCredential:
public static class DataFacade
{
public static IServiceCollection AddData(
this IServiceCollection services,
IConfiguration configuration) =>
services
.AddOptions()
.AddOrbitalDatabaseSettings(configuration, "DatabaseSettings")
.AddSingleton<BlogPostContainerSettings>()
.AddCosmosContainer<BlogPostContainer>()
.AddOrbitalCosmos(options =>
{
options.Authentication.Configuration = configuration;
options.Authentication.AuthenticationType =
OrbitalCosmosAuthenticationType.DefaultAzureCredential;
});
}
By using DefaultAzureCredential, we don’t necessarily need to change how the application authenticates depending on where it’s running.
During local development, we can authenticate using our Azure CLI credentials. When running through Docker, we can provide the credentials for our application’s identity through environment variables. The Azure Identity library handles obtaining the appropriate access token in either case.
A small change for a big impact: now we have control over what operations the API can perform in Cosmos DB using data-plane permissions.
For simplicity, I’ve assigned the API the Cosmos DB Built-in Data Contributor role since it requires read/write access. However, we could further restrict these permissions to individual databases or containers.
This gives us considerably more control than relying on a connection string containing an account key.
Decoupling Identity from Infrastructure
For our usage, I’ve also assigned the application’s identity Basic access within Azure DevOps and granted it permission to commit to our repository. The API needs these permissions as part of our publishing process, where publishing a blog post involves committing the updated content to source control.
Previously, these permissions were associated with the App Service we’ve since deleted.
By assigning them to an identity that exists independently of our hosting resources, we gain a bit more portability. We can continue using the same identity as we explore different deployment options without having to reassign its permissions each time.
More importantly, our application no longer needs to depend on a particular hosting environment to authenticate with the services it consumes.
Running the Application with Docker
With these changes in place, we can start exploring different deployment options without having to modify the application’s authentication implementation.
The first deployment option we’ve completed is running the application locally using Docker Compose:
services:
bpe-api:
image: blackpantherenterprises.azurecr.io/bpe-blog-api:1035
environment:
ASPNETCORE_ENVIRONMENT: Development
ASPNETCORE_URLS: "http://+:8080;https://+:8081"
ASPNETCORE_Kestrel__Certificates__Default__Path: /https/bpe-blog-api.pfx
ASPNETCORE_Kestrel__Certificates__Default__Password: ${HTTPS_CERT_PASSWORD}
AZURE_TENANT_ID: ${AZURE_TENANT_ID}
AZURE_CLIENT_ID: ${AZURE_CLIENT_ID}
AZURE_CLIENT_SECRET: ${AZURE_CLIENT_SECRET}
CosmosDbAccountEndpoint: ${COSMOSDB_ENDPOINT}
ports:
- "7035:8080"
- "7036:8081"
volumes:
- type: bind
source: ${USERPROFILE}/.aspnet/https/bpe-blog-api.pfx
target: /https/bpe-blog-api.pfx
read_only: true
restart: unless-stopped
blog-management-ui:
image: blackpantherenterprises.azurecr.io/blog-admin-ui:1034
ports:
- "4200:80"
restart: unless-stopped
Alongside this Docker Compose file, we have a .env file containing the configuration and credentials needed to run the application:
AZURE_TENANT_ID={{TENANT_ID}}
AZURE_CLIENT_ID={{CLIENT_ID}}
AZURE_CLIENT_SECRET={{CLIENT_SECRET}}
COSMOSDB_ENDPOINT=https://{{ACCOUNT_NAME}}.documents.azure.com:443/
HTTPS_CERT_PASSWORD={{CERT_PASSWORD}}
In this case, we’re providing the application’s service principal credentials through environment variables.
Because we’re using DefaultAzureCredential, the application can authenticate using these credentials without requiring any additional changes to our data layer.
For this local deployment, the .env file is excluded from source control since it contains sensitive information. This approach is sufficient for our development environment, although we’ll want to use a more appropriate credential mechanism for production deployments rather than maintaining application secrets directly.
Using Docker Compose, we can launch both the UI and API with a single command:
docker compose up -d
We can then start using the application locally. I can authenticate using my own identity through Microsoft Entra ID, while the API uses its own identity to communicate with Cosmos DB and Azure DevOps.
This allows us to maintain separate permissions for users and applications while keeping our authentication implementation independent of the hosting environment.
What’s Next?
With our application now running locally through Docker, the next step is to explore deploying it to Azure Kubernetes Service.
One of the benefits of these changes is that we can use a different credential mechanism, such as Microsoft Entra Workload ID, without needing to redesign how the application communicates with Cosmos DB.
Ultimately, that’s what I wanted to accomplish with this update to Orbital: give consumers control over how their applications authenticate while allowing them to take advantage of more granular permissions.
The less our applications depend on a particular hosting environment, the easier it becomes to move them between deployment options as our requirements change.