GitHub Azure AD OIDC Authentication

Authenticating GitHub Actions to Azure Active Directory using OpenID Connect

This video explains how to securely authenticate GitHub Actions with Azure Active Directory (Azure AD) by leveraging OpenID Connect (OIDC), eliminating the need to store secrets like client secrets in GitHub.

1. The Problem: Service-to-Service Authentication and Secrets Management

When one service (e.g., GitHub Actions) needs to interact with another (e.g., Azure AD) to deploy resources, it requires an identity to authenticate. Historically, this involved creating a service principal in Azure AD, generating a secret, and storing that secret within the GitHub repository. This method poses a security risk due to the potential exposure of these secrets.

2. The Solution: OpenID Connect (OIDC)

OIDC offers a more secure alternative by enabling a trust relationship between Azure AD and GitHub. Instead of storing secrets, GitHub Actions can obtain an OIDC identity token from GitHub's token service. This token can then be exchanged with Azure AD for an Azure AD access token, which grants the necessary permissions to interact with Azure resources.

3. Understanding OIDC and OAuth 2.0

• OAuth 2.0: Primarily focused on authorization, allowing a client application to access resources on behalf of a user, with the user's consent. It uses delegated permissions.
• OpenID Connect (OIDC): Built on top of OAuth 2.0, OIDC is focused on authentication, proving the identity of the client. It always uses JSON Web Tokens (JWTs), also known as "jots."

4. JSON Web Tokens (JWTs)

JWTs are a standard for securely transmitting information between parties as a JSON object. They consist of three parts:

• Header: Contains metadata about the token, such as the signing algorithm.
• Claims (Body): Holds the actual information, including:
  • Issuer: The entity that issued the token (e.g., token.actions.githubusercontent.com).
  • Subject: Details about the specific entity requesting the token (e.g., organization, repository, and the entity type like environment, tag, branch, or pull request). This is crucial for matching with Azure AD configuration.
  • Audience: The intended recipient of the token (e.g., Azure AD token exchange).
• Signature: Used to verify the token's integrity and authenticity. It's a digest of the header and claims, signed with a private key.

5. The OIDC Flow: GitHub Actions to Azure AD

1. GitHub Workflow Execution: A GitHub Actions workflow runs.
2. Token Issuance by GitHub: GitHub's token service issues an OIDC identity token (a JWT) to the running workflow. This token contains information about the issuer, subject, and audience.
3. Token Exchange with Azure AD: The GitHub Actions workflow presents this identity token to Azure AD.
4. Azure AD Verification and Token Issuance: Azure AD verifies the token's authenticity and the subject claim against its configured Federated Identity Credentials. If a match is found, Azure AD issues an Azure AD access token to the workflow.
5. Accessing Azure Resources: The GitHub Actions workflow uses the Azure AD access token to authenticate and authorize its actions against Azure resources (e.g., deploying to a subscription).

6. Key Configuration Steps and Details

A. Azure AD Application Registration

1. Create an App Registration: In Azure AD, create a new application registration (e.g., "GitHub DevOps").
2. Add Federated Credentials: Instead of a client secret, add a Federated credential. This is where the crucial matching occurs.
   • Issuer: This is automatically set to GitHub's issuer.
   • Subject Identifier: This needs to precisely match the subject claim in the GitHub OIDC token. It follows a pattern: organization_name/repository_name/entity_type/entity_value.
     • Entity Types: Can be environment, tag, branch, or pull_request.
     • Entity Value: The specific name of the environment, tag, branch, or pull request being targeted.
   • Example: For an environment named "test" in the organization "John_brick" and repository "DevOps_MC", the subject identifier would be John_brick/DevOps_MC/environment/test.
   • Verification: Azure AD will display the expected subject claim format based on your configuration.

B. Granting Permissions to the App Registration

• Assign appropriate roles to the Azure AD application registration on the target Azure resource (e.g., a subscription or resource group). For example, granting the "Contributor" role to the subscription.

C. GitHub Repository Secrets

1. Configure Repository Secrets: In your GitHub repository, navigate to Settings > Secrets and variables > Actions and create the following repository secrets:
   • AZURE_CLIENT_ID: The Application (client) ID of your Azure AD app registration.
   • AZURE_TENANT_ID: Your Azure AD tenant ID.
   • AZURE_SUBSCRIPTION_ID: The ID of the Azure subscription you want to deploy to.

D. GitHub Actions Workflow

1. Azure Login Action: Use the azure/login action in your workflow. This action handles the OIDC token exchange process.
2. Provide Required Inputs: The azure/login action requires the following inputs, which are sourced from the GitHub secrets:
   • client-id: secrets.AZURE_CLIENT_ID
   • tenant-id: secrets.AZURE_TENANT_ID
   • subscription-id: secrets.AZURE_SUBSCRIPTION_ID
3. Targeting Specific Entities: The workflow must specify what it's targeting (e.g., an environment, branch, tag, or pull request) so that the subject claim in the OIDC token can be correctly generated and matched by Azure AD.

7. Example of a Failed Authentication

A common failure occurs when the subject claim in the OIDC token does not match the configured Federated Identity Credential in Azure AD. For instance, if the Azure AD app registration is configured for a specific environment, but the GitHub workflow targets a different entity or has an incorrect subject identifier, Azure AD will not find a matching Federated Identity Record, leading to authentication failure.

8. Benefits of OIDC for Authentication

• Enhanced Security: Eliminates the need to store sensitive secrets (like client secrets) in GitHub.
• Simplified Management: Reduces the overhead of managing and rotating secrets.
• Broader Applicability: The OIDC concept is applicable to authenticating GitHub Actions with other cloud providers like AWS, and for other services like Kubernetes pods interacting with Azure AD.

9. Conclusion

By implementing OIDC, you can establish a secure and efficient authentication mechanism between GitHub Actions and Azure AD. This approach leverages GitHub's identity provider capabilities to issue verifiable identity tokens, which are then exchanged for access tokens by Azure AD, enabling seamless and secure deployments without the burden of managing traditional secrets. The key to success lies in precisely matching the subject identifier configured in Azure AD with the entity being targeted by your GitHub Actions workflow.

Key Concepts

• OpenID Connect (OIDC): An authentication layer on top of OAuth 2.0 that uses JWTs to verify identity.
• OAuth 2.0: An authorization framework for delegated access.
• JSON Web Token (JWT) / Jot: A standard for securely transmitting information as a JSON object.
• Service Principal: An identity created for applications to access Azure resources.
• Client Secret: A password used by an application to authenticate with Azure AD.
• Federated Credential: A configuration in Azure AD that establishes a trust relationship with an external identity provider (like GitHub).
• Issuer: The entity that issues an OIDC token.
• Subject: Identifies the specific entity for which the OIDC token was issued.
• Audience: Specifies the intended recipient of the OIDC token.
• App Registration: A representation of an application in Azure AD.
• GitHub Actions: A CI/CD platform integrated into GitHub.
• Repository Secrets: Sensitive information stored securely within a GitHub repository.