Configure an app to trust a GitHub repo (preview)

This article describes how to create a trust relationship between an application in Azure Active Directory (Azure AD) and a GitHub repo. You can then configure a GitHub Actions workflow to exchange a token from GitHub for an access token from Microsoft identity platform and access Azure AD protected resources without needing to manage secrets. To learn more about the token exchange workflow, read about workload identity federation. You establish the trust relationship by configuring a federated identity credential on your app registration in the Azure portal or by using Microsoft Graph.

Anyone with permissions to create an app registration and add a secret or certificate can add a federated identity credential. If the Users can register applications switch in the User Settings blade is set to No, however, you won't be able to create an app registration or configure the federated identity credential. Find an admin to configure the federated identity credential on your behalf. Anyone in the Application Administrator or Application Owner roles can do this.

After you configure your app to trust a GitHub repo, configure your GitHub Actions workflow to get an access token from Microsoft identity provider and access Azure AD protected resources.

Prerequisites

Create an app registration in Azure AD. Grant your app access to the Azure resources targeted by your GitHub workflow.

Find the object ID of the app (not the application (client) ID), which you need in the following steps. You can find the object ID of the app in the Azure portal. Go to the list of registered applications in the Azure portal and select your app registration. In Overview->Essentials, find the Object ID.

Get the organization, repository, and environment information for your GitHub repo, which you need in the following steps.

Configure a federated identity credential

Sign in to the Azure portal. Go to App registrations and open the app you want to configure.

Go to Certificates and secrets. In the Federated credentials tab, select Add credential. The Add a credential blade opens.

In the Federated credential scenario drop-down box select GitHub actions deploying Azure resources.

Specify the Organization and Repository for your GitHub Actions workflow.

For Entity type, select Environment, Branch, Pull request, or Tag and specify the value.

Add a Name for the federated credential.

The Issuer, Audiences, and Subject identifier fields autopopulate based on the values you entered.

Click Add to configure the federated credential.

Screenshot of the Add a credential window, showing sample values.

Note

If you accidentally configure someone else's GitHub repo in the subject setting (enter a typo that matches someone elses repo) you can successfully create the federated identity credential. But in the GitHub configuration, however, you would get an error because you aren't able to access another person's repo.

Important

The Organization, Repository, and Entity type values must exactly match the configuration on the GitHub workflow configuration. Otherwise, Microsoft identity platform will look at the incoming external token and reject the exchange for an access token. You won't get an error, the exchange fails without error.

Get the application (client) ID and tenant ID from the Azure portal

Before configuring your GitHub Actions workflow, get the tenant-id and client-id values of your app registration. You can find these values in the Azure portal. Go to the list of registered applications and select your app registration. In Overview->Essentials, find the Application (client) ID and Directory (tenant) ID. Set these values in your GitHub environment to use in the Azure login action for your workflow.

Next steps

Configure a GitHub Actions workflow to get an access token from Microsoft identity provider and access Azure resources.

Read the GitHub Actions documentation to learn more about configuring your GitHub Actions workflow to get an access token from Microsoft identity provider and access Azure resources.