Workload identity federation (preview)

This article provides an overview of workload identity federation for software workloads. Using workload identity federation allows you to access Azure Active Directory (Azure AD) protected resources without needing to manage secrets (for supported scenarios).

You can use workload identity federation in scenarios such as GitHub Actions.

Why use workload identity federation?

Typically, a software workload (such as an application, service, script, or container-based application) needs an identity in order to authenticate and access resources or communicate with other services. When these workloads run on Azure, you can use managed identities and the Azure platform manages the credentials for you. For a software workload running outside of Azure, you need to use application credentials (a secret or certificate) to access Azure AD protected resources (such as Azure, Microsoft Graph, Microsoft 365, or third-party resources). These credentials pose a security risk and have to be stored securely and rotated regularly. You also run the risk of service downtime if the credentials expire.

You use workload identity federation to configure an Azure AD app registration to trust tokens from an external identity provider (IdP), such as GitHub. Once that trust relationship is created, your software workload can exchange trusted tokens from the external IdP for access tokens from Microsoft identity platform. Your software workload then uses that access token to access the Azure AD protected resources to which the workload has been granted access. This eliminates the maintenance burden of manually managing credentials and eliminates the risk of leaking secrets or having certificates expire.

Supported scenarios

The following scenarios are supported for accessing Azure AD protected resources using workload identity federation:

  • GitHub Actions. First, Configure a trust relationship between your app in Azure AD and a GitHub repo in the Azure portal or using Microsoft Graph. Then configure a GitHub Actions workflow to get an access token from Microsoft identity provider and access Azure resources.
  • Workloads running in compute platforms outside of Azure. Configure a trust relationship between your Azure AD application registration and the external IdP for your compute platform. You can use tokens issued by that platform to authenticate with Microsoft identity platform and call APIs in the Microsoft ecosystem. Use the client credentials flow to get an access token from Microsoft identity platform, passing in the identity provider's JWT instead of creating one yourself using a stored certificate.

How it works

Create a trust relationship between the external IdP and an app in Azure AD by configuring a federated identity credential. The federated identity credential is used to indicate which token from the external IdP should be trusted by your application. You configure the federated identity credential on your app registration in the Azure portal or through Microsoft Graph. The steps for configuring the trust relationship will differ, depending on the scenario and external IdP.

The workflow for exchanging an external token for an access token is the same, however, for all scenarios. The following diagram shows the general workflow of a workload exchanging an external token for an access token and then accessing Azure AD protected resources.

Shows an external token exchanged for an access token and accessing Azure

  1. The external workload (such as a GitHub Actions workflow) requests a token from the external IdP (such as GitHub).
  2. The external IdP issues a token to the external workload.
  3. The external workload (the login action in a GitHub workflow, for example) sends the token to Microsoft identity platform and requests an access token.
  4. Microsoft identity platform checks the trust relationship on the app registration and validates the external token against the Open ID Connect (OIDC) issuer URL on the external IdP.
  5. When the checks are satisfied, Microsoft identity platform issues an access token to the external workload.
  6. The external workload accesses Azure AD protected resources using the access token from Microsoft identity platform. A GitHub Actions workflow, for example, uses the access token to publish a web app to Azure App Service.

Next steps

Learn more about how workload identity federation works: