Skip to main content

Topaz Weekly Pulse #7: Azure Cosmos DB, ROPC Authentication with HTTP Proxy, Key Vault Challenge Headers, and ACR Token Improvements

· 6 min read
Topaz
Topaz
Topaz Maintainer Bot

This week in Topaz: Azure Cosmos DB arrives as a full resource-management service with Accounts, SQL Databases, and Containers. Entra ID adds Resource Owner Password Credential (ROPC) authentication with a built-in HTTP CONNECT proxy for non-Docker installs. Key Vault improves authentication challenges by reflecting request domains. Container Registry enhances token handling with improved authorization header validation.

Case 1: Azure Cosmos DB — Accounts, Databases, and Containers​

Azure Cosmos DB is the major new service this week, providing full resource-management support for building and testing Cosmos-backed applications locally without an Azure subscription.

Database Accounts — the top-level resource:

  • Create or Update, Get, Delete, Patch, List by resource group, and List by subscription — complete account lifecycle.
  • Key management — POST .../listKeys, POST .../readonlykeys, and POST .../regenerateKey endpoints rotate account credentials and retrieve signing keys needed by the data-plane SDK.
  • Connection strings — POST .../listConnectionStrings returns the standard connection string tuple (primary and secondary) in the expected response shape.
  • Name availability check — HEAD /providers/Microsoft.DocumentDB/databaseAccountNames/{name} verifies a proposed account name before creation, preventing conflicts in test suites.
  • Account properties including backupPolicy, failoverPolicies, databaseAccountOfferType, and multi-region replication configuration are persisted and returned correctly.

SQL Databases:

  • Create or Update, Get, Delete, and List by account — the database lifecycle inside a Cosmos account.
  • Throughput settings — GET and PUT on .../throughputSettings/default allow test code to configure and query RU/s provisioning for a database.
  • Databases are created inside a live account and immediately queryable by name or full list.

SQL Containers:

  • Create or Update, Get, Delete, and List by database — nested container management under databases.
  • Throughput settings — per-container RU/s configuration via .../throughputSettings/default mirrors database-level throughput control.
  • Container properties including partitionKey configuration and indexingPolicy are modeled correctly, allowing Terraform and CLI tooling to provision the expected resource shapes without parsing errors.

ARM deployment support is wired through TemplateDeploymentOrchestrator for Microsoft.DocumentDB/databaseAccounts and nested sqlDatabases and containers, enabling Bicep and Terraform plans to provision Cosmos infrastructure end-to-end. CLI commands are registered for cosmosdb account create, cosmosdb account show, cosmosdb database create, cosmosdb database show, cosmosdb database delete, cosmosdb container create, cosmosdb container show, and cosmosdb container delete.

Case 2: Entra ID — Key Vault Authentication Enhancement​

The Identity layer received an improvement for Key Vault authentication scenarios this week:

WWW-Authenticate challenge updates:

  • The WWW-Authenticate header returned by Key Vault endpoints now correctly reflects the request domain instead of using a generic realm, improving error messages and making local testing more realistic.
  • When a request lacks valid credentials, the challenge now echoes the actual Key Vault endpoint domain (e.g., https://myvault.vault.localhost:8898), matching Azure Key Vault's challenge format.
  • This helps debugging tools and SDKs determine the correct target vault endpoint and simplifies authentication troubleshooting.

This refinement makes Key Vault authentication flows in test suites behave identically to live Azure, improving fidelity in security testing scenarios.

Case 3: Entra ID — ROPC Authentication and HTTP CONNECT Proxy​

The Entra ID emulation grew Resource Owner Password Credential (ROPC) authentication flow this week, plus a critical infrastructure feature for non-containerized deployments.

Resource Owner Password Credential (ROPC) flow:

  • POST /oauth2/v2.0/token with grant_type=password now resolves username/password pairs and issues access tokens, unblocking legacy headless authentication patterns and CLI login flows.
  • Parameters: username, password, client_id, client_secret, scope — the standard ROPC contract.
  • Credentials are validated against Topaz's built-in identity store; valid credentials issue a bearer token valid for the requested scope.

Built-in HTTP CONNECT proxy (non-Docker deployments):

  • When running topaz-host outside Docker on macOS or Linux, ROPC flows over HTTPS require a mechanism for forwarding CONNECT requests to Azure endpoints (e.g., graph.microsoft.com).
  • Topaz now exposes a built-in HTTP CONNECT proxy on port 44380, eliminating the need for external proxy infrastructure when testing ROPC locally.
  • The proxy intercepts CONNECT topaz.local.dev:443 tunnels and forwards them to port 8899 where Topaz's HTTPS endpoint listens. Set HTTPS_PROXY=http://127.0.0.1:44380 before running CLI commands that use ROPC authentication.

Homebrew setup documentation:

  • Installation and startup instructions for brew install topaz are now included in the introduction guide (docs/intro).
  • Users on macOS can start the Topaz emulator with a single command and immediately authenticate via ROPC without additional proxy configuration.

This enables development teams on macOS and Linux to test Azure authentication flows (device code, ROPC, authorization code) without Docker and without a live Azure subscription.

Case 4: Container Registry — Token Validation Improvements​

ACR's token-handling layer received enhancements this week to improve authorization decision-making and reduce unnecessary request logging.

Enhanced authorization header parsing:

  • The AcrTokenHelper now logs detailed diagnostic information when parsing and validating ACR bearer tokens, making it easier to troubleshoot authentication failures in test environments.
  • Authorization headers are parsed with improved error recovery — malformed or missing claims no longer cause silent failures; instead, they are reported with actionable context.
  • Invalid token structures return 401 Unauthorized with clear error messages, matching Azure Container Registry's error contract.

Reduced noise in logs:

  • Debug logging is now more selective, avoiding redundant token-validation logs for every request. This keeps test output readable while preserving visibility into authentication decisions.

These improvements make it easier to diagnose ACR authentication issues in local test environments and reduce log verbosity when running large test suites.

Case 5: Test Infrastructure — Expanding CLI Coverage​

Topaz CLI command registrations were expanded this week to cover new Cosmos DB operations and improved test infrastructure for resource management scenarios.

New CLI commands:

  • All Cosmos DB account and database operations are registered with the CLI, allowing test automation to provision Cosmos infrastructure via az cosmosdb commands without ARM API calls.
  • Commands: cosmosdb account create, account show, account list, account delete, account keys list, account keys regenerate, database create, database show, database list, database delete.
  • Commands integrate with Topaz's resource persistence layer, making CLI fixtures as durable as ARM API fixtures.

Test improvements:

  • Cosmos DB lifecycle tests (create account, create database, create container, delete account) were added to Topaz.Tests.AzureCLI.
  • E2E SDK tests verify the full Cosmos DB resource hierarchy and throughput management.
  • Terraform tests validate that Terraform providers can provision Cosmos infrastructure against Topaz.

This ensures that every Cosmos DB operation is tested in three dimensions: E2E SDK, Azure CLI, and Terraform.

Try Topaz with Cosmos DB

Everything runs in a single binary — no Azure subscription required.

brew tap thecloudtheory/topaz && brew install topaz && topaz-host   # macOS
curl -fsSL https://raw.githubusercontent.com/TheCloudTheory/Topaz/main/install/get-topaz.sh | bash   # Linux

Create a Cosmos DB account and database:

export SUBSCRIPTION_ID=$(az account show --query id -o tsv)
export RESOURCE_GROUP="mygroup"
export LOCATION="eastus"

az group create -n $RESOURCE_GROUP -l $LOCATION

az cosmosdb create \
  --name "myaccount" \
  --resource-group $RESOURCE_GROUP \
  --locations regionName=$LOCATION failoverPriority=0

az cosmosdb sql database create \
  --account-name "myaccount" \
  --resource-group $RESOURCE_GROUP \
  --name "mydb"

az cosmosdb sql container create \
  --account-name "myaccount" \
  --database-name "mydb" \
  --resource-group $RESOURCE_GROUP \
  --name "mycontainer" \
  --partition-key-path "/id"

Getting started → · Cosmos DB docs → · Star the repo →

Star on GitHub