Skip to content

ADR-0003: Use GitHub OIDC for Azure authentication

Status

Accepted

Context

CI/CD workflows in GitHub Actions need to authenticate with Azure to provision infrastructure and deploy applications. The main authentication options were:

  • Service principal with client secret -- Store a secret in GitHub Secrets, rotate periodically
  • Service principal with certificate -- Store a certificate, rotate periodically
  • OIDC federated identity -- Token exchange between GitHub and Azure AD, no stored secrets

Decision

Use OpenID Connect (OIDC) federated identity for all GitHub Actions to Azure authentication.

Implementation:

  1. An Azure AD app registration is created with federated credentials
  2. Federated credentials are scoped to the release branch and pull requests
  3. Workflows set ARM_USE_OIDC: true to enable token exchange
  4. No secrets are stored for Azure authentication

See OIDC setup for the full configuration guide.

Consequences

Positive

  • No stored secrets -- Eliminates the risk of credential leakage and the burden of secret rotation
  • Short-lived tokens -- OIDC tokens expire quickly, reducing the window for misuse
  • Scoped access -- Federated credentials are bound to specific branches and event types
  • Audit trail -- Azure AD logs all token exchanges for compliance

Negative

  • Setup complexity -- Initial configuration requires Azure AD app registration, federated credentials, and correct subject claims. Misconfigured subjects cause silent authentication failures.
  • GitHub dependency -- OIDC federation is specific to GitHub. Moving to another CI platform requires reconfiguration.
  • Debugging difficulty -- OIDC failures are harder to diagnose than secret-based auth failures. Subject claim mismatches produce generic error messages.

Neutral

  • OIDC is now the recommended authentication method by both GitHub and Microsoft for Actions-to-Azure integration.
  • The azure/login@v2 action handles the OIDC token exchange transparently.