Microsoft Azure Learning Journey

Stop Storing Client Secrets: Azure Workload Identity Federation

Let GitHub Actions prove its identity with a short-lived OIDC token instead of keeping a long-lived Azure password in repository secrets.

11 min read · 2013 words
Microsoft AzureGitHub ActionsOIDCDevOpsCloud Security
Stop Storing Client Secrets: Azure Workload Identity Federation cover image

A deployment pipeline needs Azure access, so someone creates an application secret and saves it in GitHub. It works—until the secret expires, gets copied to the wrong workflow, or appears in a log. The pipeline has become a long-lived credential holder.

Workload identity federation replaces that stored credential with a trust rule. GitHub issues a signed OpenID Connect (OIDC) token for a specific workflow context. Microsoft Entra ID validates the token against a federated identity credential and exchanges it for an Azure access token.

What you’ll learn

Where this fits

This is Module 7 and Phase 2, Part 3. It builds on least-privilege Azure access. The next article covers Key Vault and managed identities; the phase ends with a lab that provisions and tests the GitHub trust.

Prerequisites


The three claims behind federation

OpenID Connect (OIDC) is an identity layer built on OAuth 2.0. In this pattern, GitHub is the issuer (identity provider). It issues a signed JSON Web Token (JWT) describing the workflow run. Microsoft Entra ID checks whether that token matches a trust rule configured on an application or user-assigned managed identity.

A federated identity credential matches three values:

All values must match the token exactly. A mismatch does not create partial access: the exchange is rejected.

GitHub Actions job
      |
      | signed OIDC token: issuer + subject + audience
      v
Microsoft Entra ID checks federated credential
      |
      | short-lived Azure access token for trusted identity
      v
Azure service checks that identity's Azure RBAC permissions

The federated credential answers which external workload may become this identity. Azure RBAC separately answers what that identity can do. Do not confuse trust to authenticate with permission to deploy.

App registration or user-assigned managed identity?

Both can be configured with a federated identity credential and used as a deployment identity.

Choose one identity model and manage its lifecycle intentionally. A UAMI is convenient for Azure-native identity management; an app registration may fit existing application identity governance. In either case, keep its Azure role narrow and remove obsolete federated credentials and assignments when the workflow is retired.

GitHub Actions example

For a GitHub repository with an environment named dev, a workflow can request an OIDC token and pass it to the Azure Login action:

name: Azure deployment

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: dev
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Sign in to Azure with OIDC
        uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

id-token: write allows this job to request an OIDC token; it does not give the workflow write permission to Azure resources. The Azure Login action exchanges that token for an Azure token. The IDs are identifiers, not client secrets; GitHub repository or environment variables are suitable, although organizations may choose another configuration-management approach.

For production, pin third-party and first-party Actions to verified commit SHAs using an approved update process. A version tag such as @v2 is easier to read but can move; verify the current action documentation and security policy before adopting an example.

Environment subject and branch protection

When a job references a GitHub environment, the traditional subject claim uses the environment name rather than a branch ref. Therefore, a trust on repo:OWNER/REPOSITORY:environment:dev trusts jobs in that environment; the subject alone does not restrict which branch can enter it.

Configure GitHub environment deployment protection rules to allow only the intended branch or tag, require approval where appropriate, and restrict who can change the environment. For branches that do not use an environment, the traditional subject commonly takes the form repo:OWNER/REPOSITORY:ref:refs/heads/BRANCH.

GitHub introduced immutable default subject formats for certain repositories created or renamed/transferred after July 15, 2026. Existing repositories may retain the prior format unless opted in. Inspect the actual current OIDC subject claim and configure the federated credential to match it exactly; do not copy a subject string from another repository or assume all repositories use the same format.

Threat model and operational limits

Federation removes one class of risk: a long-lived Azure client secret stored in a CI system. It does not make an untrusted workflow safe.

For Microsoft-hosted GitHub runners, federation avoids a static credential but does not give a private VNet route by itself. A self-hosted runner inside a network introduces its own patching, isolation, and secret-management obligations.

Hands-on: map a workflow to an exact trust

No Azure resources or permissions are changed in this exercise.

  1. Identify the owner and repository name exactly as GitHub reports them.

  2. Choose one GitHub environment, for example dev, and add it to the deployment job.

  3. Configure that environment to allow only the intended branch and reviewers where appropriate.

  4. Determine the subject format GitHub will issue for this repository. For repositories using the traditional format, an environment subject resembles:

    repo:YOUR_OWNER/YOUR_REPOSITORY:environment:dev
    
  5. Record the expected issuer https://token.actions.githubusercontent.com and audience api://AzureADTokenExchange.

  6. Decide which Entra identity will receive the federated credential and which narrowly scoped Azure RBAC role it requires.

  7. Test a valid workflow and a negative case from a branch or environment that should not be trusted. A test must prove both the allowed path and rejection of the unauthorized path.

✅ Checkpoint: Your issuer, subject, and audience describe one intended workflow context, and you can explain that a separate RBAC assignment is still required. No Azure resource or credential was created.

Cost implications

The claims-mapping exercise creates no Azure resources or Azure consumption charges. Running a GitHub Actions workflow may count against the repository’s plan or included minutes. Any Azure resources deployed by a federated workflow are billed normally; federation does not make the deployment free.

Troubleshooting federation

Production-readiness checklist

Cleanup

This exercise only maps claims and reviews a workflow example. It creates no federated credential, identity, role assignment, or Azure resource. No cleanup is required. The Phase 2 lab performs provisioning and includes ordered removal steps.

Key takeaways

Quick self-check

  1. Which claim identifies the trusted GitHub workflow context?
  2. Does id-token: write grant Azure Contributor?
  3. If OIDC login succeeds but resource creation is forbidden, which system should you inspect next?
  4. Does an environment-based subject automatically restrict deployments to the main branch?

Answers

  1. The subject (sub), along with matching issuer and audience.
  2. No. It lets the job request a GitHub OIDC token.
  3. Azure RBAC, then applicable policy, network, and service controls.
  4. No. Configure the GitHub environment’s deployment branch/tag protection rules.

References

What’s next

Next, Azure Key Vault and Managed Identities: Secrets Without Hardcoding explains how Azure workloads obtain identity and how Key Vault protects secrets, keys, and certificates.


Series navigation


Disclaimer: GitHub claims, Azure identity features, action versions, and service limits change. Verify current documentation before implementation.

Share this article

LinkedIn post draft