Skip to main content

How to authenticate StackQL to Azure

StackQL authenticates to Azure with a Microsoft Entra ID (formerly Azure AD) service principal, supplied through three environment variables: AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET.

Steps​

  1. Create a service principal and grant it a role on the target subscription (the Reader role suffices for read-only querying):
az ad sp create-for-rbac --name stackql-sp --role Reader \
  --scopes /subscriptions/<subscription-id>
  1. Export the credentials it returns:
export AZURE_TENANT_ID=your-tenant-id
export AZURE_CLIENT_ID=your-client-id
export AZURE_CLIENT_SECRET=your-client-secret
  1. Pull the Azure provider (first use only):
REGISTRY PULL azure;
  1. Verify with a query:
SELECT name, location
FROM azure.compute.virtual_machines
WHERE subscriptionId = '00000000-1111-2222-3333-444444444444';

The subscriptionId predicate is a required routing parameter of the Azure API, not part of authentication. Methods scoped to a resource group additionally require resourceGroupName; run SHOW METHODS IN azure.compute.virtual_machines to see the required parameters for each access method (list_all needs only subscriptionId; list needs resourceGroupName as well; get needs vmName).

Where the variables apply​

The variables work identically across stackql shell, stackql exec, stackql srv (PostgreSQL wire server), and stackql mcp. For MCP clients such as Claude Desktop, place them in the env block of the server entry in claude_desktop_config.json. In CI, source them from the pipeline's secret store.