GitHub Actions to Azure: Implementing OIDC Federation with Microsoft Entra ID

The conventional way to let a GitHub Actions workflow deploy to Azure is to create a service principal, generate a client secret for it, and store that secret (often as part of an AZURE_CREDENTIALS JSON blob, or as a standalone AZURE_CLIENT_SECRET) in GitHub Actions secrets. That secret is a bearer credential: whoever holds the string can authenticate as that service principal from anywhere, not just from your workflow. Client secrets on an Entra ID App Registration commonly get created with no expiration, or with an expiration far enough out that they are functionally permanent until someone remembers to rotate them. In practice that means a single leaked value, whether from a misconfigured log, a forked pull request workflow, a compromised third-party action, or a runner that got popped, grants standing access to Azure for as long as the secret remains valid, which is often measured in months or years rather than minutes. The service principal behind that secret is also frequently over-scoped, holding Contributor or Owner at the subscription level because it was easier to set up that way, which turns a single credential leak into a subscription-wide compromise. OIDC federation removes the secret from the equation entirely: there is nothing long-lived to leak, because Azure never issues a durable credential to the workflow in the first place.

Before starting, confirm you have the access this procedure requires. Each of these gaps is a common reason the setup stalls partway through.

If you already have a service principal your pipeline uses, you can attach a federated credential to its existing App Registration and skip straight to Step 2. To create a new one:

az ad app create --display-name "gh-actions-<repo>-<environment>"

Record the appId (this is the client ID you will use later) and then fetch the app's object ID, which the federated-credential command needs:

az ad app show --id <appId> --query id -o tsv

Create a corresponding service principal for the app if one does not already exist, since the RBAC role assignment in Step 3 is made against the service principal, not the App Registration object itself:

az ad sp create --id <appId>

Use a naming convention that ties the App Registration to a single repository and, ideally, a single environment (for example gh-actions-payments-api-prod). A separate App Registration per deployment target keeps the blast radius of any single federated credential misconfiguration contained to one pipeline.

This is the step that determines whether the whole setup works, and it is where almost every first attempt fails. Microsoft Entra ID authorizes the token exchange by matching the sub (subject) claim in the OIDC token GitHub issues against the subject string on the federated credential. The two have to match exactly, including case. The issuer and audience are fixed values for GitHub Actions:

issuer: https://token.actions.githubusercontent.com audience: api://AzureADTokenExchange

The subject claim format depends on what triggers the workflow. The common patterns are:

repo:<org>/<repo>:ref:refs/heads/main (a specific branch) repo:<org>/<repo>:environment:production (a specific GitHub Environment, regardless of branch) repo:<org>/<repo>:pull_request (any pull request against the repo) repo:<org>/<repo>:ref:refs/tags/v1.0.0 (a specific tag)

For a production deployment pipeline, scoping to a GitHub Environment is usually the better choice over a raw branch ref, because it lets you layer GitHub's own environment protection rules (required reviewers, wait timers) on top of the Azure federation, and because the environment name stays stable even if branching strategy changes later. Save the credential definition to a file and create it:

{ "name": "gh-actions-payments-api-prod", "issuer": "https://token.actions.githubusercontent.com", "subject": "repo:contoso/payments-api:environment:production", "audiences": ["api://AzureADTokenExchange"] }

az ad app federated-credential create --id <app-object-id> --parameters ./credential.json

One additional detail worth planning for now rather than later: as of mid-2026, GitHub also supports an immutable subject format that appends the numeric owner and repository IDs to the name-based subject (for example repo:contoso@5544123/payments-api@821093847:environment:production), and GitHub is rolling this out by default for newly created, renamed, or transferred repositories. If your repository is on the immutable format, or moves to it later, the subject string above will stop matching and you will need either a second federated credential for the immutable subject or a flexible federated credential using a claims matching expression, which is covered in the failure cases section below.

The federated credential only proves identity to Entra ID. It grants nothing on its own; the service principal still needs an Azure RBAC role assignment to do anything in the subscription. Resist the default of reaching for Contributor at the subscription scope. Scope the role assignment to the narrowest resource group, or ideally the narrowest individual resource, that the workflow actually needs to touch, and use the most specific built-in role that covers the actions the pipeline performs (for example Storage Blob Data Contributor for a workflow that only needs to push build artifacts to a storage account, rather than Contributor over the whole resource group):

az role assignment create --assignee <appId> --role "Storage Blob Data Contributor" --scope /subscriptions/<sub-id>/resourceGroups/<rg-name>

This mirrors the same reasoning covered in our zero trust network architecture guide: a federated identity is still an identity, and it should be granted only the access its specific task requires, not broad standing access justified by convenience. Treat the RBAC assignment as a separate control decision from the OIDC trust relationship, and revisit both whenever the pipeline's actual responsibilities change.

With the federated credential and RBAC role in place, update the workflow to authenticate with azure/login and OIDC instead of a stored secret. Two things are easy to miss: the id-token: write permission has to be declared explicitly (GitHub Actions does not grant it by default), and none of the three values passed to azure/login are secret in the traditional sense, so it is reasonable to store the client ID, tenant ID, and subscription ID as repository or environment variables rather than encrypted secrets if your workflow structure benefits from that.

permissions: id-token: write contents: read

jobs: deploy: runs-on: ubuntu-latest environment: production steps: - uses: actions/checkout@v4 - name: Azure login uses: azure/login@v2 with: client-id: ${{ vars.AZURE_CLIENT_ID }} tenant-id: ${{ vars.AZURE_TENANT_ID }} subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

Notice there is no client-secret input at all. If your workflow currently references AZURE_CLIENT_SECRET or a full AZURE_CREDENTIALS JSON blob anywhere, this step replaces both. Once the login step is confirmed working end to end, delete the old secret from GitHub Actions secrets rather than leaving it in place as a fallback; an unused static credential still sitting in the secrets store is exactly the risk this migration is meant to close, and see our GitHub Actions security hardening guide for the broader set of workflow permission and third-party action controls worth reviewing at the same time.

A workflow that reaches the azure/login step without an authentication error is a good sign, but it is worth confirming the exchange happened the way you intended rather than assuming it. Check these three places.

Most first-time setup failures come down to one of these four causes, roughly in order of how often they show up.

The temptation once this is working is to make the federated credential cover more than it needs to, usually to avoid repeating this setup for every new repository or branch. Resist it. A federated credential built with a claims matching expression that wildcards the repository, such as matching any subject starting with repo:contoso-org/ regardless of which repository or branch follows, grants every repository in that GitHub organization the ability to authenticate as that Azure identity. If the RBAC role behind it has any meaningful write access, that wildcard has effectively turned a single compromised or malicious repository anywhere in the org into a path to that access, which defeats the reason for scoping OIDC federation in the first place. The same reasoning applies to scoping by branch: a subject that matches any ref (ref:refs/heads/*, where supported) rather than a specific branch means a pull request from an untrusted branch or a compromised dependency in a feature branch's workflow can potentially authenticate with the same access as your production pipeline. Prefer one federated credential per repository and per environment or protected branch, sized to exactly what that pipeline needs, even though it means more App Registrations or more federated credentials to keep track of. The bookkeeping cost is small and predictable; the cost of an over-scoped wildcard being discovered by an attacker is not.