Tips

Github Workflow OIDC Access to Azure

NEEDS REWRITE

OIDC allows workflows to authenticate and interact with Azure using short-lived tokens. This eliminates the need for long-lived personal access tokens (PAT) or service principal with a secrets, providing a more secure and manageable approach to accessing cloud resources directly from GitHub Actions.

How It Works

  1. Configuration: You configure your Azure AD App Registration to trust an external identity provider by setting up a federation with that IdP. This involves specifying details about the IdP, such as the issuer URL, and possibly uploading metadata documents for SAML-based federations.

  2. Authentication Flow: A user or service attempts to access an application protected by Azure AD and is redirected to sign in. Instead of presenting Azure AD credentials, the user or service presents credentials from the federated IdP. The federated IdP authenticates the user or service and issues a token. This token is presented to Azure AD, which validates it based on the trust configuration. Upon successful validation, Azure AD issues its own token to the user or service, granting access to the application.

Setting Up

  1. Enable OIDC in Azure
    • You still need an App Registration and Service Principal
    • Assign it the required Azure RBAC and Entra roles, at the required scope, to be able to do what you want it to do
    • But instead of configuring a secret, you configure a “federated” credential
    • Configure a federated identity credential on an app
    • click “Certificates & secrets” -> “Federated credentials”, and “Add credential” and select “Github Actions deploying Azure resources”
    • Enter the Github Organization
    • The Github Repository name
    • The Entity type = “Branch”
    • And Based on selection = “main”, or whatever that may be
  2. Set below variables as secrets in your GitHub repository:
    • AZURE_AD_APPLICATION_CLIENT_ID: The client ID of the Azure AD application
    • AZURE_TENANT_ID: Your Azure tenant ID
    • AZURE_SUBSCRIPTION_ID: Your Azure subscription ID (may not be needed)
  3. Setup a workflow that authenticates to Azure using OIDC, does something useful
    • Can be used with Terraform
    • Requires azurerm provider version 3.7.0 or higher
    • Azure CLI is set up with the token automatically, of course
    • Terraform picks up the token automatically also
    • Anything running within the Github Action job can use Azure CLI to get respective API tokens, as shown below
    • Example OIDC Github Action job using Azure CLI:
       permissions:
     id-token: write  # This is required for requesting the JWT
     contents: read   # This is required for actions/checkout

   jobs:
     task_leveraging_oidc_login:
       runs-on: ubuntu-latest
       steps:

         - name: checkout_github_action_code
           uses: actions/checkout@v4
           with:
             ref: main

         # Option 1: Using azure-cli
         - name: azure_oidc_login
           uses: azure/login@v1
           with:
             client-id: $
             tenant-id: $
             allow-no-subscriptions: true  

         - name: capture_azure_tokens
           run: |
             # https://learn.microsoft.com/en-us/cli/azure/account?view=azure-cli-latest#az-account-get-access-token
             # [--resource-type {aad-graph, arm, batch, data-lake, media, ms-graph, oss-rdbms}]
             export MG_TOKEN="$(az account get-access-token --resource-type ms-graph --query accessToken -o tsv)"
             export AZ_TOKEN="$(az account get-access-token --resource-type arm --query accessToken -o tsv)"
             echo "MG_TOKEN=$MG_TOKEN" >> $GITHUB_ENV  # To use in another step 
             echo "AZ_TOKEN=$AZ_TOKEN" >> $GITHUB_ENV
             curl -sH "Content-Type: application/json" -H "Authorization: Bearer ${AZ_TOKEN}" -X GET "https://management.azure.com/subscriptions?api-version=2022-12-01" | jq

         # Option 2: Using custom Python script (RECOMMENDED)
         # See https://github.com/git719/tips/blob/main/scripts/get_oidc_tokens.py

         - name: some_other_step
           run: |
             curl -sH "Content-Type: application/json" -H "Authorization: Bearer $" -X GET "https://graph.microsoft.com/v1.0/users" | jq

Overview

A Github workflow action can be setup to You can - Using Azure as a sample cloud provider

OIDC Flow Diagram

GitHub             GitHub Workflow Action             Microsoft
│                           │                             │
│   1. Give me JWT token    │                             │
│ ◄──────────────────────── │                             │
│                           │                             │
│   2. Returns JWT token    │                             │
│ ────────────────────────► │                             │
│                           │                             │
│                           │                             │
│                           │  3. Give me Azure ARM       │
│                           │     and MS Graph tokens     │
│                           │ ──────────────────────────► │
│                           │                             │
│                           │  4. Returns each token      │
│                           │ ◄────────────────────────── │
                            │                             
                            │                             
MS Graph                    │                         Azure ARM
│                           │                             │
│   5. Update MS Graph X    │                             │
│      object using token   │                             │
│ ◄──────────────────────── │                             │
│                           │                             │
│   6. Update done          │                             │
│ ────────────────────────► │                             │
│                           │                             │
│                           │  7. Update Azure ARM X      │
│                           │     object using token      │
│                           │ ──────────────────────────► │
│                           │                             │
│                           │  8. Update done             │
│                           │ ◄────────────────────────── │

References

Using OIDC for Authentication with Azure

This document explains how OpenID Connect (OIDC) authentication works between a program (like a GitHub workflow) and Azure, and what it takes for any program to be trusted by Azure.

1. How GitHub Workflows Use OIDC to Authenticate with Azure

When a GitHub workflow authenticates with Azure, it follows these steps:

  1. Acquire an OIDC Token from GitHub:
    • GitHub Actions generates an OIDC token for the workflow run. This token contains claims about the workflow (e.g., repository, branch, job name) and is signed by GitHub’s private key.
  2. Present the OIDC Token to Azure:
    • The workflow uses the OIDC token to request an Azure access token from Microsoft Identity Platform (formerly Azure AD).
  3. Azure Validates the OIDC Token:
    • Azure verifies the OIDC token’s signature using GitHub’s public key (which it trusts).
    • Azure checks the token’s claims against the federated identity configuration set up in Azure AD. This configuration defines which GitHub repositories, branches, or workflows are allowed to assume specific Azure roles.
  4. Azure Issues an Access Token:
    • If the OIDC token is valid and the claims match the configuration, Azure issues an access token to the workflow. This access token allows the workflow to perform actions in Azure based on the assigned permissions.

2. Can Any Program Do the Same?

Yes, any program can use OIDC to authenticate with Azure, provided it meets the following requirements:

a. The Program Must Be Able to Generate an OIDC Token

b. Azure Must Trust the OIDC Token Issuer

c. The Program Must Have the Correct Configuration in Azure AD

3. What Makes Azure Trust the GitHub OIDC Token?

Azure trusts the GitHub OIDC token because:

  1. GitHub’s Public Key is Trusted:
    • Azure has GitHub’s public key and uses it to verify the token’s signature.
  2. Federated Identity Configuration:
    • Azure AD is configured to trust tokens from GitHub’s OIDC issuer (https://token.actions.githubusercontent.com).
    • The federated identity configuration specifies which GitHub repositories, branches, or workflows are allowed to assume specific roles in Azure.
  3. Token Claims Match the Configuration:
    • The OIDC token’s claims (e.g., issuer, subject, audience) match the conditions defined in the federated identity configuration.

4. What Does It Take for Any Program to Be Trusted by Azure?

For any program to be trusted by Azure, you need to:

  1. Set Up the Program as an OIDC Identity Provider:
    • The program must generate OIDC tokens that comply with the OIDC standard.
    • The tokens must include the necessary claims (e.g., issuer, subject, audience).
  2. Register the Program’s Public Key in Azure AD:
    • Azure AD needs the public key of the program’s OIDC token issuer to verify the token’s signature.
  3. Configure Federated Identity in Azure AD:
    • Create a federated identity credential in Azure AD that maps the program’s OIDC token claims to an Azure AD application or service principal.
    • Define the conditions under which the program is allowed to assume roles (e.g., specific issuer, subject, audience values).
  4. Ensure the Program’s OIDC Token Meets Azure’s Requirements:
    • The token must include the correct claims and be signed with the program’s private key.

5. Example: Custom Program Using OIDC with Azure

If you want to write a custom program that uses OIDC to authenticate with Azure, here’s what you’d do:

  1. Generate an OIDC Token:
    • Use an OIDC library (e.g., for Go, Python, or Node.js) to generate a signed OIDC token.
    • Include the required claims (issuer, subject, audience, etc.).
  2. Register Your Program in Azure AD:
    • Create an Azure AD application or service principal.
    • Add a federated identity credential that maps your program’s OIDC token claims to the Azure AD application.
  3. Configure Azure to Trust Your Program:
    • Provide Azure AD with your program’s public key for token verification.
    • Define the conditions under which your program is allowed to authenticate (e.g., specific issuer and subject values).
  4. Use the OIDC Token to Authenticate with Azure:
    • Present the OIDC token to Microsoft Identity Platform to request an Azure access token.
    • Use the access token to interact with Azure resources.

Summary

Roles in the OIDC Flow

In the OIDC authentication flow between GitHub and Azure, GitHub acts as the Identity Provider (IdP), while Azure acts as the Relying Party (RP) or Service Provider (SP).

Why This Works