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.

Important considerations and restrictions

To create, update, or delete a federated identity credential, the account performing the action must have the Application Administrator, Application Developer, Cloud Application Administrator, or Application Owner role. The microsoft.directory/applications/credentials/update permission is required to update a federated identity credential.

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.

To learn more about supported regions, time to propagate federated credential updates, supported issuers and more, read Important considerations and restrictions for federated identity credentials.

Prerequisites

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:

  1. 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.

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

  3. Specify the Organization and Repository for your GitHub Actions workflow.

  4. 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.

  5. Add a Name for the federated credential.

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

  7. Select Add to configure the federated credential.

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

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.

    Screenshot that demonstrates how to copy the application ID and tenant ID from Microsoft Entra admin center.

  • 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:

  • Cluster issuer URL is the OIDC issuer URL for the managed cluster or the OIDC Issuer URL for a self-managed cluster.
  • 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:

  • 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.
  • 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.

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.

Prerequisites

  • 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

Run the az ad app federated-credential create command to create a new federated identity credential on your 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://aksoicchinanorth.blob.core.chinacloudapi.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/",
    "subject": "system:serviceaccount:erp8asle:pod-identity-sa",
    "description": "Kubernetes service account federated credential",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

List federated identity credentials on an app

Run the az ad app federated-credential list command to list the federated identity credentials on your app.

The id parameter specifies the identifier URI, application ID, or object ID of the application.

az ad app federated-credential list --id 00001111-aaaa-2222-bbbb-3333cccc4444

Get a federated identity credential on an app

Run the az ad app federated-credential show command to get a federated identity credential on your app.

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 show --id 00001111-aaaa-2222-bbbb-3333cccc4444 --federated-credential-id c79f8feb-a9db-4090-85f9-90d820caa0eb

Delete a federated identity credential from an app

Run the az ad app federated-credential delete command to remove a federated identity credential from your app.

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 can 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:

  1. Install the latest version of Azure PowerShell if you haven't already.

  2. Sign in to Azure.

    Connect-AzAccount -Environment AzureChinaCloud

  3. Install the latest version of PowerShellGet.

    Install-Module -Name PowerShellGet -AllowPrerelease

    You might need to Exit out of the current PowerShell session after you run this command for the next step.

  4. Install the prerelease version of the Az.Resources module to perform the federated identity credential operations in this article.

    Install-Module -Name Az.Resources -AllowPrerelease

Configure a federated identity credential on an app

Run the New-AzADAppFederatedCredential cmdlet to create a new federated identity credential on an application.

GitHub Actions example

  • 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".
New-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -Audience api://AzureADTokenExchange -Issuer 'https://token.actions.githubusercontent.com/' -Name 'GitHub-Actions-Test' -Subject 'repo:octo-org/octo-repo:environment:Production'

Kubernetes example

  • 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.
New-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -Audience api://AzureADTokenExchange -Issuer 'https://aksoicchinanorth.blob.core.chinacloudapi.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/' -Name 'Kubernetes-federated-credential' -Subject 'system:serviceaccount:erp8asle:pod-identity-sa'

List federated identity credentials on an app

Run the Get-AzADAppFederatedCredential cmdlet to list the federated identity credentials for an application.

Get-AzADApplication -ObjectId $app | Get-AzADAppFederatedCredential

Get a federated identity credential on an app

Run the Get-AzADAppFederatedCredential cmdlet to get the federated identity credential by ID from an application.

Get-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -FederatedCredentialId $credentialId

Delete a federated identity credential from an app

Run the Remove-AzADAppFederatedCredential cmdlet to delete a federated identity credential from an application.

Remove-AzADAppFederatedCredential -ApplicationObjectId $appObjectId -FederatedCredentialId $credentialId

Prerequisites

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://microsoftgraph.chinacloudapi.cn) exposes REST APIs to create, update, delete federatedIdentityCredentials on applications. Launch Azure Powershell 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://microsoftgraph.chinacloudapi.cn/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"]}'

And you get the response:

{
  "@odata.context": "https://microsoftgraph.chinacloudapi.cn/$metadata#applications('00001111-aaaa-2222-bbbb-3333cccc4444')/federatedIdentityCredentials/$entity",
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "description": "Testing",
  "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "issuer": "https://token.actions.githubusercontent.com",
  "name": "Testing",
  "subject": "repo:octo-org/octo-repo:environment:Production"
}

name: The name of your Azure application.

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://microsoftgraph.chinacloudapi.cn/applications/00001111-aaaa-2222-bbbb-3333cccc4444/federatedIdentityCredentials' --body '{"name":"Kubernetes-federated-credential","issuer":"https://aksoicchinanorth.blob.core.chinacloudapi.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/","subject":"system:serviceaccount:erp8asle:pod-identity-sa","description":"Kubernetes service account federated credential","audiences":["api://AzureADTokenExchange"]}'

And you get the response:

{
  "@odata.context": "https://microsoftgraph.chinacloudapi.cn/$metadata#applications('00001111-aaaa-2222-bbbb-3333cccc4444')/federatedIdentityCredentials/$entity",
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "description": "Kubernetes service account federated credential",
  "id": "51ecf9c3-35fc-4519-a28a-8c27c6178bca",
  "issuer": "https://aksoicchinanorth.blob.core.chinacloudapi.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/",
  "name": "Kubernetes-federated-credential",
  "subject": "system:serviceaccount:erp8asle:pod-identity-sa"
}

List federated identity credentials on an app

Run the following method to list the federated identity credential(s) for an app (specified by the object ID of the app):

az rest -m GET -u 'https://microsoftgraph.chinacloudapi.cn/applications/00001111-aaaa-2222-bbbb-3333cccc4444/federatedIdentityCredentials'

And you get a response similar to:

{
  "@odata.context": "https://microsoftgraph.chinacloudapi.cn/$metadata#applications('00001111-aaaa-2222-bbbb-3333cccc4444')/federatedIdentityCredentials",
  "value": [
    {
      "audiences": [
        "api://AzureADTokenExchange"
      ],
      "description": "Testing",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "issuer": "https://token.actions.githubusercontent.com/",
      "name": "Testing",
      "subject": "repo:octo-org/octo-repo:environment:Production"
    }
  ]
}

Get a federated identity credential on an app

Run the following method to get a federated identity credential for an app (specified by the object ID of the app):

az rest -m GET -u 'https://microsoftgraph.chinacloudapi.cn/applications/00001111-aaaa-2222-bbbb-3333cccc4444//federatedIdentityCredentials/00aa00aa-bb11-cc22-dd33-44ee44ee44ee'

And you get a response similar to:

{
  "@odata.context": "https://microsoftgraph.chinacloudapi.cn/$metadata#applications('00001111-aaaa-2222-bbbb-3333cccc4444')/federatedIdentityCredentials",
  "value": {
      "@odata.context": "https://microsoftgraph.chinacloudapi.cn/$metadata#applications('00001111-aaaa-2222-bbbb-3333cccc4444')/federatedIdentityCredentials/$entity",
      "@odata.id": "https://microsoftgraph.chinacloudapi.cn/v2/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/directoryObjects/$/Microsoft.DirectoryServices.Application('00001111-aaaa-2222-bbbb-3333cccc4444')/federatedIdentityCredentials('00001111-aaaa-2222-bbbb-3333cccc4444')/00001111-aaaa-2222-bbbb-3333cccc4444",
    "audiences": [
        "api://AzureADTokenExchange"
      ],
      "description": "Testing",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "issuer": "https://token.actions.githubusercontent.com/",
      "name": "Testing",
      "subject": "repo:octo-org/octo-repo:environment:Production"
    }
}

Delete a federated identity credential from an app

Run the following method to delete a federated identity credential from an app (specified by the object ID of the app):

az rest -m DELETE  -u 'https://microsoftgraph.chinacloudapi.cn/applications/00001111-aaaa-2222-bbbb-3333cccc4444/federatedIdentityCredentials/00aa00aa-bb11-cc22-dd33-44ee44ee44ee'

Next steps