{"id":12878,"date":"2026-08-26T09:47:16","date_gmt":"2026-08-26T16:47:16","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=12878"},"modified":"2026-08-27T07:45:14","modified_gmt":"2026-08-27T14:45:14","slug":"i-need-my-ci-cd-pipeline-to-access-cosmos-db-without-using-a-secret","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/i-need-my-ci-cd-pipeline-to-access-cosmos-db-without-using-a-secret\/","title":{"rendered":"I Need My CI\/CD Pipeline to Access Cosmos DB Without Using a Secret"},"content":{"rendered":"

In the last post we walked through <\/span><\/span>why RBAC broke your app and how to fix it<\/span><\/span><\/a>. Your app is now running on a managed identity, keys are off, and everything is green. Then your build pipeline runs, and it needs to seed test data. Suddenly <\/span>you’re<\/span> staring at a secret in your CI settings and wondering if you just undid all that work. As we continue this security series, <\/span>let’s<\/span> get your pipeline to Cosmos DB with no secret anywhere.<\/span><\/span><\/em>\u00a0<\/span><\/p>\n

The situation<\/span>\u00a0<\/span><\/h3>\n

You did the hard part. Your app uses <\/span>DefaultAzureCredential<\/span><\/code>, you assigned a data plane role, and you set <\/span>disableLocalAuth: true<\/span><\/code>. Passwordless, done.<\/span>\u00a0<\/span><\/p>\n

Then you look at your CI\/CD pipeline and find this sitting in your repository secrets:<\/span><\/p>\n

AZURE_CLIENT_SECRET = <<\/span>a very long<\/span> string that expires in 6 months><\/span><\/span>\u00a0<\/span>
<\/span>COSMOS_CONNECTION_STRING = <\/span>AccountEndpoint<\/span>=https:\/\/...;<\/span>AccountKey<\/span>=...<\/span><\/span>\u00a0<\/span><\/code><\/p>\n

That connection string doesn’t even work anymore \u2014 local auth is off. And the client secret is exactly the kind of long-lived credential you just spent a sprint eliminating from your app. It sits in a settings page, it gets copied into a runbook, someone pastes it in a chat, and in six months it expires at 2am during a release.<\/span>\u00a0<\/span><\/p>\n

There is a better answer, and it’s not “store the secret somewhere nicer.” It’s <\/span>workload identity federation<\/span><\/b>: your pipeline proves who it is with a short-lived OIDC token issued by GitHub or Azure DevOps, and Entra ID trades that token for an Azure access token. No secret is stored anywhere. Nothing expires. Nothing to rotate.<\/span><\/p>\n

The mental model: three things have to line up<\/span>\u00a0<\/span><\/h3>\n

Before touching any YAML, get this picture straight. When your pipeline talks to Cosmos DB, three separate things have to be true:<\/span>\u00a0<\/span><\/p>\n

    \n
  1. Trust<\/span><\/b> \u2014 Entra ID has to believe the token your CI platform hands it. That’s the federated credential.<\/span>\u00a0<\/span><\/li>\n
  2. Control plane authorization<\/span><\/b> \u2014 if the pipeline deploys infrastructure (creates the account, databases, containers), it needs an Azure RBAC role like <\/span>DocumentDB Account Contributor<\/span>.<\/span>\u00a0<\/span><\/li>\n
  3. Data plane authorization<\/span><\/b> \u2014 if the pipeline reads, writes, or seeds <\/span>items<\/span><\/i>, it needs a Cosmos DB data plane role assignment.<\/span>\u00a0<\/span><\/li>\n<\/ol>\n

    Most people set up #1, get excited that <\/span>az login<\/span><\/code> works, and then get blindsided by a <\/span>403<\/span><\/code> because they never did #3. If that sounds familiar, the previous post has the full breakdown of why control plane and data plane are separate systems.<\/span>\u00a0<\/span><\/p>\n

    GitHub Actions: the walkthrough<\/span>\u00a0<\/span><\/h3>\n

    Step 1: Create an identity for the pipeline<\/span>\u00a0<\/span><\/h4>\n

    You can federate either an app registration or a user-assigned managed identity. I’ll use an app registration here because it’s the most common, but a user-assigned managed identity works the same way and is worth considering if you want the identity to live in a resource group with the rest of your infrastructure.<\/span>\u00a0<\/span><\/p>\n

    APP_ID=$(<\/span>az<\/span> ad app create --display-name \"<\/span>gh<\/span>-actions-<\/span>myrepo<\/span>\" --query <\/span>appId<\/span> -o <\/span>tsv<\/span>)<\/span><\/span>\u00a0<\/span>
    <\/span>az ad <\/span>sp<\/span> create --id \"$APP_ID\"<\/span><\/span>\u00a0<\/span><\/code><\/p>\n

    Step 2: Add the federated credential<\/span>\u00a0<\/span><\/h4>\n

    This is where you tell Entra ID which workflow is allowed to use this identity. The <\/span>subject<\/span> is the important field \u2014 it has to match the OIDC token GitHub issues, exactly.<\/span><\/p>\n

    az<\/span> ad app federated-credential create \\<\/span><\/span>\u00a0<\/span>
    <\/span>\u00a0 --id \"$APP_ID\" \\<\/span><\/span>\u00a0<\/span>
    <\/span>\u00a0 --parameters '{<\/span><\/span>\u00a0<\/span>
    <\/span>\u00a0\u00a0\u00a0 \"name\": \"<\/span>github<\/span>-prod-env\",<\/span><\/span>\u00a0<\/span>
    <\/span>\u00a0\u00a0\u00a0 \"issuer\": \"https:\/\/token.actions.githubusercontent.com\",<\/span><\/span>\u00a0<\/span>
    <\/span>\u00a0\u00a0\u00a0 \"subject\": \"<\/span>repo:my-org<\/span>\/<\/span>my-repo:environment:production<\/span>\",<\/span><\/span>\u00a0<\/span>
    <\/span>\u00a0\u00a0\u00a0 \"audiences\": [\"<\/span>api<\/span>:\/\/<\/span>AzureADTokenExchange<\/span>\"]<\/span><\/span>\u00a0<\/span>
    <\/span>\u00a0 }'<\/span><\/span>\u00a0<\/span><\/code><\/p>\n

    A few notes on <\/span>subject<\/span><\/code>, because this is where people miss:<\/span>\u00a0<\/span><\/p>\n\n\n\n\n\n\n
    What you want<\/span><\/span>\u00a0<\/span><\/strong><\/td>\nSubject<\/strong><\/td>\n<\/tr>\n
    A specific branch<\/td>\nrepo:my-org<\/span>\/<\/span>my-repo:ref:refs<\/span>\/heads\/main<\/span><\/span>\u00a0<\/span><\/code><\/td>\n<\/tr>\n
    A GitHub environment<\/span><\/span>\u00a0<\/span><\/td>\nrepo:my-org<\/span>\/<\/span>my-repo:environment:production<\/span><\/span>\u00a0<\/span><\/code><\/td>\n<\/tr>\n
    Pull request builds<\/span><\/span>\u00a0<\/span><\/td>\nrepo:my-org<\/span>\/<\/span>my-repo:pull_request<\/span><\/span>\u00a0<\/span><\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    Pr<\/span>efer <\/span>scoping <\/span>the <\/span>federated <\/span>credential<\/span> to a <\/span>GitHub <\/span>environment<\/span><\/strong>.<\/span><\/span> B<\/span>ranch<\/span>-based<\/span> subjects <\/span>don’t<\/span> support wildcards, so <\/span>every <\/span>new <\/span>release branch requires another <\/span>federated credential<\/span>. Environment-based subjects are easier to manage, support approvals and branch protection, and remain stable as branches come and go. You can assign<\/span> up to 20 federated credentials <\/span>to a single<\/span> identity, so <\/span>plan their <\/span>use <\/span>carefully<\/span><\/span>.<\/span><\/span>\u00a0<\/span><\/p>\n

    Step 3: Check which subject format your repo uses<\/span>\u00a0<\/span><\/h4>\n

    This one is new and it will quietly break setups that used to work.<\/span>\u00a0<\/span><\/p>\n

    The OIDC spec requires subject claims to be locally unique and never reassigned. The old format used only organization and repository\u202f<\/span>names<\/span><\/i>, which meant a recycled namespace could produce the same subject value under a different owner. To close that hole,\u202f<\/span>repositories created after July 15, 2026 use an immutable default subject format that includes the owner ID and the repository ID.<\/span><\/b>\u00a0<\/span><\/p>\n

    \"Hand-drawn<\/a><\/p>\n