Configure an app to trust an external identity provider
Article
This article describes how to manage a federated identity credential on an application in Microsoft Entra ID. The federated identity credential creates a trust relationship between an application and an external identity provider (IdP).
You can then configure an external software workload to exchange a token from the external IdP for an access token from Microsoft identity platform. The external workload can access Microsoft Entra protected resources without needing to manage secrets (in supported scenarios). To learn more about the token exchange workflow, read about workload identity federation.
In this article, you learn how to create, list, and delete federated identity credentials on an application in Microsoft Entra ID.
A maximum of 20 federated identity credentials can be added to an application or user-assigned managed identity.
When you configure a federated identity credential, there are several important pieces of information to provide:
issuer and subject are the key pieces of information needed to set up the trust relationship. The combination of issuer and subject must be unique on the app. When the external software workload requests Microsoft identity platform to exchange the external token for an access token, the issuer and subject values of the federated identity credential are checked against the issuer and subject claims provided in the external token. If that validation check passes, Microsoft identity platform issues an access token to the external software workload.
issuer is the URL of the external identity provider and must match the issuer claim of the external token being exchanged. Required. If the issuer claim has leading or trailing whitespace in the value, the token exchange is blocked. This field has a character limit of 600 characters.
subject is the identifier of the external software workload and must match the sub (subject) claim of the external token being exchanged. subject has no fixed format, as each IdP uses their own - sometimes a GUID, sometimes a colon delimited identifier, sometimes arbitrary strings. This field has a character limit of 600 characters.
Important
The subject setting 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.
Important
If you accidentally add the incorrect external workload information in the subject setting the federated identity credential is created successfully without error. The error does not become apparent until the token exchange fails.
audiences lists the audiences that can appear in the external token. Required. You must add a single audience value, which has a limit of 600 characters. The recommended value is "api://AzureADTokenExchange". It says what Microsoft identity platform must accept in the aud claim in the incoming token.
name is the unique identifier for the federated identity credential. Required. This field has a character limit of 3-120 characters and must be URL friendly. Alphanumeric, dash, or underscore characters are supported, the first character must be alphanumeric only. It's immutable once created.
description is the user-provided description of the federated identity credential. Optional. The description isn't validated or checked by Microsoft Entra ID. This field has a limit of 600 characters.
Wildcard characters aren't supported in any federated identity credential property value.
Create an app registration in Microsoft Entra ID. Grant your app access to the Azure resources targeted by your external software workload.
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 Microsoft Entra admin center. Go to the list of app registrations and select your app registration. In Overview->Essentials, find the Object ID.
Get the subject and issuer information for your external IdP and software workload, which you need in the following steps.
Configure a federated identity credential on an app
GitHub Actions
To add a federated identity for GitHub actions, follow these steps:
Find your app registration in the app registrations experience of the Microsoft Entra admin center. Select Certificates & secrets in the left nav pane, select the Federated credentials tab, and select Add credential.
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. The values must exactly match the configuration in the GitHub workflow. Pattern matching isn't supported for branches and tags. Specify an environment if your on-push workflow runs against many branches or tags. For more info, read the examples.
Add a Name for the federated credential.
The Issuer, Audiences, and Subject identifier fields autopopulate based on the values you entered.
Select Add to configure the federated credential.
Use the following values from your Microsoft Entra application registration for your GitHub workflow:
AZURE_CLIENT_ID the Application (client) ID
AZURE_TENANT_ID the Directory (tenant) ID
The following screenshot demonstrates how to copy the application ID and tenant ID.
AZURE_SUBSCRIPTION_ID your subscription ID. To get the subscription ID, open Subscriptions in Azure portal and find your subscription. Then, copy the Subscription ID.
Entity type examples
Branch example
For a workflow triggered by a push or pull request event on the main branch:
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
Specify an Entity type of Branch and a GitHub branch name of "main".
Environment example
For Jobs tied to an environment named "production":
on:
push:
branches:
- main
jobs:
deployment:
runs-on: ubuntu-latest
environment: production
steps:
- name: deploy
# ...deployment-specific steps
Specify an Entity type of Environment and a GitHub environment name of "production".
Tag example
For example, for a workflow triggered by a push to the tag named "v2":
on:
push:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
# Sequence of patterns matched against refs/tags
tags:
- v2
- v1.*
Specify an Entity type of Tag and a GitHub tag name of "v2".
Pull request example
For a workflow triggered by a pull request event, specify an Entity type of Pull request
Kubernetes
Find your app registration in the app registrations experience of the Microsoft Entra admin center. Select Certificates & secrets in the left nav pane, select the Federated credentials tab, and select Add credential.
Select the Kubernetes accessing Azure resources scenario from the dropdown menu.
Fill in the Cluster issuer URL, Namespace, Service account name, and Name fields:
Service account name is the name of the Kubernetes service account, which provides an identity for processes that run in a Pod.
Namespace is the service account namespace.
Name is the name of the federated credential, which can't be changed later.
Other identity providers
Find your app registration in the app registrations experience of the Microsoft Entra admin center. Select Certificates & secrets in the left nav pane, select the Federated credentials tab, and select Add credential.
Select the Other issuer scenario from the dropdown menu.
Specify the following fields (using a software workload running in Google Cloud as an example):
Name is the name of the federated credential, which can't be changed later.
Subject identifier: must match the sub claim in the token issued by the external identity provider. In this example using Google Cloud, subject is the Unique ID of the service account you plan to use.
Issuer: must match the iss claim in the token issued by the external identity provider. A URL that complies with the OIDC Discovery spec. Microsoft Entra ID uses this issuer URL to fetch the keys that are necessary to validate the token. For Google Cloud, the issuer is "https://accounts.google.com".
List federated identity credentials on an app
Find your app registration in the app registrations experience of the Microsoft Entra admin center. Select Certificates & secrets in the left nav pane and select the Federated credentials tab. The federated credentials that are configured on your app are listed.
Delete a federated identity credential from an app
Find your app registration in the app registrations experience of the Microsoft Entra admin center. Select Certificates & secrets in the left nav pane and select the Federated credentials tab. The federated credentials that are configured on your app are listed.
To delete a federated identity credential, select the Delete icon for the credential.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
Create an app registration in Microsoft Entra ID. Grant your app access to the Azure resources targeted by your external software workload.
Find the object ID, app (client) ID, or identifier URI of the app, which you need in the following steps. You can find these values in the Microsoft Entra admin center. Go to the list of registered applications and select your app registration. In Overview->Essentials, get the Object ID, Application (client) ID, or Application ID URI value, which you need in the following steps.
Get the subject and issuer information for your external IdP and software workload, which you need in the following steps.
Configure a federated identity credential on an app
The id parameter specifies the identifier URI, application ID, or object ID of the application. The parameters parameter specifies the parameters, in JSON format, for creating the federated identity credential.
GitHub Actions example
The name specifies the name of your federated identity credential.
The issuer identifies the path to the GitHub OIDC provider: https://token.actions.githubusercontent.com/. This issuer will become trusted by your Azure application.
subject identifies the GitHub organization, repo, and environment for your GitHub Actions workflow. When the GitHub Actions workflow requests Microsoft identity platform to exchange a GitHub token for an access token, the values in the federated identity credential are checked against the provided GitHub token. Before Azure will grant an access token, the request must match the conditions defined here.
For Jobs tied to an environment: repo:< Organization/Repository >:environment:< Name >
For Jobs not tied to an environment, include the ref path for branch/tag based on the ref path used for triggering the workflow: repo:< Organization/Repository >:ref:< ref path>. For example, repo:n-username/ node_express:ref:refs/heads/my-branch or repo:n-username/ node_express:ref:refs/tags/my-tag.
For workflows triggered by a pull request event: repo:< Organization/Repository >:pull-request.
az ad app federated-credential create --id 00001111-aaaa-2222-bbbb-3333cccc4444 --parameters credential.json
("credential.json" contains the following content)
{
"name": "Testing",
"issuer": "https://token.actions.githubusercontent.com",
"subject": "repo:octo-org/octo-repo:environment:Production",
"description": "Testing",
"audiences": [
"api://AzureADTokenExchange"
]
}
Kubernetes example
issuer is your service account issuer URL (the OIDC issuer URL for the managed cluster or the OIDC Issuer URL for a self-managed cluster).
subject is the subject name in the tokens issued to the service account. Kubernetes uses the following format for subject names: system:serviceaccount:<SERVICE_ACCOUNT_NAMESPACE>:<SERVICE_ACCOUNT_NAME>.
name is the name of the federated credential, which can't be changed later.
audiences lists the audiences that can appear in the external token. This field is mandatory. The recommended value is "api://AzureADTokenExchange".
az ad app federated-credential create --id 00001111-aaaa-2222-bbbb-3333cccc4444 --parameters credential.json
("credential.json" contains the following content)
{
"name": "Kubernetes-federated-credential",
"issuer": "https://aksoicwesteurope.blob.core.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/",
"subject": "system:serviceaccount:erp8asle:pod-identity-sa",
"description": "Kubernetes service account federated credential",
"audiences": [
"api://AzureADTokenExchange"
]
}
Other identity providers example
You can configure a federated identity credential on an app and create a trust relationship with other external identity providers. The following example uses a software workload running in Google Cloud as an example:
name is the name of the federated credential, which can't be changed later.
id: the object ID, application (client) ID, or identifier URI of the app.
subject: must match the sub claim in the token issued by the external identity provider. In this example using Google Cloud, subject is the Unique ID of the service account you plan to use.
issuer: must match the iss claim in the token issued by the external identity provider. A URL that complies with the OIDC Discovery spec. Microsoft Entra ID uses this issuer URL to fetch the keys that are necessary to validate the token. For Google Cloud, the issuer is "https://accounts.google.com".
audiences: lists the audiences that can appear in the external token. This field is mandatory. The recommended value is "api://AzureADTokenExchange".
az ad app federated-credential create --id 00001111-aaaa-2222-bbbb-3333cccc4444 --parameters credential.json
("credential.json" contains the following content)
{
"name": "GcpFederation",
"issuer": "https://accounts.google.com",
"subject": "112633961854638529490",
"description": "Test GCP federation",
"audiences": [
"api://AzureADTokenExchange"
]
}
The id parameter specifies the identifier URI, application ID, or object ID of the application.
The federated-credential-id specifies the ID or name of the federated identity credential.
az ad app federated-credential delete --id 00001111-aaaa-2222-bbbb-3333cccc4444 --federated-credential-id c79f8feb-a9db-4090-85f9-90d820caa0eb
Prerequisites
To run the example scripts, you have two options:
Use Azure Cloud Shell, which you can open by using the Try It button in the upper-right corner of code blocks.
Run scripts locally with Azure PowerShell, as described in the next section.
Create an app registration in Microsoft Entra ID. Grant your app access to the Azure resources targeted by your external software workload.
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 Microsoft Entra admin center. Go to the list of registered applications and select your app registration. In Overview->Essentials, find the Object ID.
Get the subject and issuer information for your external IdP and software workload, which you need in the following steps.
Configure Azure PowerShell locally
To use Azure PowerShell locally for this article instead of using Cloud Shell:
ApplicationObjectId: the object ID of the app (not the application (client) ID) you previously registered in Microsoft Entra ID.
Issuer identifies GitHub as the external token issuer.
Subject identifies the GitHub organization, repo, and environment for your GitHub Actions workflow. When the GitHub Actions workflow requests Microsoft identity platform to exchange a GitHub token for an access token, the values in the federated identity credential are checked against the provided GitHub token.
For Jobs tied to an environment: repo:< Organization/Repository >:environment:< Name >
For Jobs not tied to an environment, include the ref path for branch/tag based on the ref path used for triggering the workflow: repo:< Organization/Repository >:ref:< ref path>. For example, repo:n-username/ node_express:ref:refs/heads/my-branch or repo:n-username/ node_express:ref:refs/tags/my-tag.
For workflows triggered by a pull request event: repo:< Organization/Repository >:pull-request.
Name is the name of the federated credential, which can't be changed later.
Audience lists the audiences that can appear in the external token. This field is mandatory. The recommended value is "api://AzureADTokenExchange".
ApplicationObjectId: the object ID of the app (not the application (client) ID) you previously registered in Microsoft Entra ID.
Issuer is your service account issuer URL (the OIDC issuer URL for the managed cluster or the OIDC Issuer URL for a self-managed cluster).
Subject is the subject name in the tokens issued to the service account. Kubernetes uses the following format for subject names: system:serviceaccount:<SERVICE_ACCOUNT_NAMESPACE>:<SERVICE_ACCOUNT_NAME>.
Name is the name of the federated credential, which can't be changed later.
Audience lists the audiences that can appear in the aud claim of the external token.
Specify the following parameters (using a software workload running in Google Cloud as an example):
ObjectID: the object ID of the app (not the application (client) ID) you previously registered in Microsoft Entra ID.
Name is the name of the federated credential, which can't be changed later.
Subject: must match the sub claim in the token issued by the external identity provider. In this example using Google Cloud, subject is the Unique ID of the service account you plan to use.
Issuer: must match the iss claim in the token issued by the external identity provider. A URL that complies with the OIDC Discovery spec. Microsoft Entra ID uses this issuer URL to fetch the keys that are necessary to validate the token. For Google Cloud, the issuer is "https://accounts.google.com".
Audiences: must match the aud claim in the external token. For security reasons, you should pick a value that is unique for tokens meant for Microsoft Entra ID. The recommended value is "api://AzureADTokenExchange".
Create an app registration in Microsoft Entra ID. Grant your app access to the Azure resources targeted by your external software workload.
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 Microsoft Entra admin center. Go to the list of registered applications and select your app registration. In Overview->Essentials, find the Object ID.
Get the subject and issuer information for your external IdP and software workload, which you need in the following steps.
The Microsoft Graph endpoint (https://graph.microsoft.com) exposes REST APIs to create, update, delete federatedIdentityCredentials on applications. Launch Azure Cloud Shell and sign in to your tenant in order to run Microsoft Graph commands from AZ CLI.
Configure a federated identity credential on an app
GitHub Actions
Run the following method to create a new federated identity credential on your app (specified by the object ID of the app). The issuer identifies GitHub as the external token issuer. subject identifies the GitHub organization, repo, and environment for your GitHub Actions workflow. When the GitHub Actions workflow requests Microsoft identity platform to exchange a GitHub token for an access token, the values in the federated identity credential are checked against the provided GitHub token.
az rest --method POST --uri 'https://graph.microsoft.com/applications/00001111-aaaa-2222-bbbb-3333cccc4444/federatedIdentityCredentials' --body '{"name":"Testing","issuer":"https://token.actions.githubusercontent.com","subject":"repo:octo-org/octo-repo:environment:Production","description":"Testing","audiences":["api://AzureADTokenExchange"]}'
issuer: The path to the GitHub OIDC provider: https://token.actions.githubusercontent.com. This issuer will become trusted by your Azure application.
subject: Before Azure will grant an access token, the request must match the conditions defined here.
For Jobs tied to an environment: repo:< Organization/Repository >:environment:< Name >
For Jobs not tied to an environment, include the ref path for branch/tag based on the ref path used for triggering the workflow: repo:< Organization/Repository >:ref:< ref path>. For example, repo:n-username/ node_express:ref:refs/heads/my-branch or repo:n-username/ node_express:ref:refs/tags/my-tag.
For workflows triggered by a pull request event: repo:< Organization/Repository >:pull-request.
audiences lists the audiences that can appear in the external token. This field is mandatory. The recommended value is "api://AzureADTokenExchange".
Kubernetes example
Run the following method to configure a federated identity credential on an app and create a trust relationship with a Kubernetes service account. Specify the following parameters:
issuer is your service account issuer URL (the OIDC issuer URL for the managed cluster or the OIDC Issuer URL for a self-managed cluster).
subject is the subject name in the tokens issued to the service account. Kubernetes uses the following format for subject names: system:serviceaccount:<SERVICE_ACCOUNT_NAMESPACE>:<SERVICE_ACCOUNT_NAME>.
name is the name of the federated credential, which can't be changed later.
audiences lists the audiences that can appear in the external token. This field is mandatory. The recommended value is "api://AzureADTokenExchange".
az rest --method POST --uri 'https://graph.microsoft.com/applications/00001111-aaaa-2222-bbbb-3333cccc4444/federatedIdentityCredentials' --body '{"name":"Kubernetes-federated-credential","issuer":"https://aksoicwesteurope.blob.core.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/","subject":"system:serviceaccount:erp8asle:pod-identity-sa","description":"Kubernetes service account federated credential","audiences":["api://AzureADTokenExchange"]}'
Run the following method to configure a federated identity credential on an app and create a trust relationship with an external identity provider. Specify the following parameters (using a software workload running in Google Cloud as an example):
name is the name of the federated credential, which can't be changed later.
ObjectID: the object ID of the app (not the application (client) ID) you previously registered in Microsoft Entra ID.
subject: must match the sub claim in the token issued by the external identity provider. In this example using Google Cloud, subject is the Unique ID of the service account you plan to use.
issuer: must match the iss claim in the token issued by the external identity provider. A URL that complies with the OIDC Discovery spec. Microsoft Entra ID uses this issuer URL to fetch the keys that are necessary to validate the token. For Google Cloud, the issuer is "https://accounts.google.com".
audiences lists the audiences that can appear in the external token. This field is mandatory. The recommended value is "api://AzureADTokenExchange".
az rest --method POST --uri 'https://graph.microsoft.com/applications/<ObjectID>/federatedIdentityCredentials' --body '{"name":"GcpFederation","issuer":"https://accounts.google.com","subject":"112633961854638529490","description":"Testing","audiences":["api://AzureADTokenExchange"]}'
az rest -m GET -u 'https://graph.microsoft.com/applications/00001111-aaaa-2222-bbbb-3333cccc4444//federatedIdentityCredentials/00aa00aa-bb11-cc22-dd33-44ee44ee44ee'
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.
For more information, read about how Microsoft Entra ID uses the OAuth 2.0 client credentials grant and a client assertion issued by another IdP to get a token.
For information about the required format of JWTs created by external identity providers, read about the assertion format.