Authenticate to Azure from GitHub Actions¶

This page documents two methods to access Azure from a GitHub repository when running GitHub Actions: OpenID Connect (OIDC) and Service Principal Name (SPN). OIDC is preferred for its security properties, such as dynamic, short-lived tokens and system-bound authentication. This guide covers the setup of the OIDC connection.

Difference between OIDC & SPN¶

OIDC

OIDC allows GitHub Actions workflows to access Azure resources without storing long-lived credentials as GitHub secrets.

OIDC uses dynamically generated tokens with a short lifespan, reducing the risk of credential compromise.
Tokens are tied to GitHub Actions, limiting misuse if leaked.

SPN

Requires hardcoded credentials (username/password or client id/secret).
Credentials can be used from any system, increasing the attack surface.

Info

Avoid using SPN and always use OIDC

OIDC Setup¶

1. Register an Azure AD Application¶

Create a new application registration in Azure AD to represent GitHub Actions.

az login
az ad app create --display-name {Name}

Retrieve the appId from the output.

2. Create a Service Principal¶

Create a service principal associated with the app registration.

az ad sp create --id {appId}

Use the id value from the output for the next step.

3. Assign RBAC Permissions¶

Assign the service principal the contributor role to a subscription.

az role assignment create --role contributor \
  --subscription {subscriptionId} \
  --assignee-object-id {spnId} \
  --assignee-principal-type ServicePrincipal \
  --scope /subscriptions/{subscriptionId}

4. Create a Federated Identity Credential¶

Create a trust relationship between the app registration and GitHub.

Create a credential.json file:

{
    "name": "{name}",
    "issuer": "https://token.actions.githubusercontent.com",
    "subject": "{subject}",
    "description": "{description}",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

Run:

az ad app federated-credential create --id {appId} --parameters credential.json

5. Create GitHub Secrets¶

Add the following values to your GitHub repository secrets:

AZURE_CLIENT_ID: The appId from step 1
AZURE_SUBSCRIPTION_ID: The target subscription ID
AZURE_TENANT_ID: The Azure tenant ID

6. Confirm Connectivity¶

Create a workflow in .github/workflows/verify-azure-login-with-oidc.yaml:

name: Verify Azure Login with OIDC
on: [workflow_dispatch]

permissions:
  id-token: write
  contents: read

jobs:
  login:
    runs-on: ubuntu-latest
    steps:
    - name: 'Az CLI login'
      uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}