Set up a Flexible Federated identity credential (preview)

This article shows how to set up a flexible federated identity credential for an application or user-assigned managed identity. You can use the Azure portal, Microsoft Graph for an application, or Azure Resource Manager for a user-assigned managed identity. Before you begin, review the requirements in Prerequisites.

Prerequisites

Understand the credential properties

Property Description
audiences The audience that can appear in the external token. This field is mandatory and should be set to api://AzureADTokenExchange for Microsoft Entra ID. It says what Microsoft identity platform should accept in the aud claim in the incoming token. This value represents Microsoft Entra ID in your external identity provider and has no fixed value across identity providers - you might need to create a new application registration in your IdP to serve as the audience of this token.
issuer The URL of the external identity provider. Must match the issuer claim of the external token being exchanged.
subject The identifier of the external software workload within the external identity provider. Like the audience value, it has no fixed format, as each IdP uses their own - sometimes a GUID, sometimes a colon delimited identifier, sometimes arbitrary strings. The value here must match the sub claim within the token presented to Microsoft Entra ID. If subject is defined, claimsMatchingExpression must be set to null.
name A unique string to identify the credential. For applications, this property is an alternate key, and you can use it to reference the credential through a GET operation. For a user-assigned managed identity, the credential name is part of the Azure Resource Manager resource path.
claimsMatchingExpression a new complex type containing two properties, value and languageVersion. Value is used to define the expression, and languageVersion is used to define the version of the flexible federated identity credential expression language (FFL) being used. languageVersion should always be set to 1. If claimsMatchingExpression is defined, subject must be set to null.

Set up a flexible federated identity credential

For GitHub, a flexible federated identity credential must match the sub claim and one or both of the following immutable claims:

  • repository_id identifies the repository where the workflow runs.
  • repository_owner_id identifies the repository owner.

These claims are required regardless of whether sub uses a name-based, customized, or immutable format.

When you use mutable subjects with GitLab, your flexible federated identity credential expression must match the sub and project_id claims.

To create the credential in the Azure portal:

  • Navigate to Microsoft Entra ID and select the application where you want to configure the federated identity credential.
  • In the left-hand navigation pane, select Certificates & secrets.
  • Under the Federated credentials tab, select + Add credential.
  • In the Add a credential window that appears, from the dropdown menu next to Federated credential scenario, select Other issuer.
  • Under Connect your account, enter the Issuer URL of the external identity provider. For example:
    • GitHub: https://token.actions.githubusercontent.com
    • GitLab: https://gitlab.example.com
    • Terraform Cloud: https://app.terraform.io
  • In Value, enter the claim matching expression you want to use. For example, for GitHub, enter claims['sub'] matches 'repo:contoso/contoso-repo:ref:refs/heads/*' and claims['repository_id'] eq '456789'.
  • Select Add to save the credential.

More examples of Flexible Federated identity credentials

Flexible federated identity credentials can use different issuers, such as GitHub, GitLab, and Terraform Cloud. Use the following tabs to set up a flexible federated identity credential for each of these issuers.

This example shows how to set up a flexible federated identity credential for GitHub with an expression for the job_workflow_ref claim. Get the numeric repository_id and repository_owner_id values from the GitHub OpenID Connect (OIDC) token. Use repository_id to bind the credential to a repository.

{
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "name": "MyGitHubFlexibleFIC",
  "issuer": "https://token.actions.githubusercontent.com",
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'repo:contoso/contoso-repo:ref:refs/heads/*' and claims['repository_id'] eq '456789' and claims['job_workflow_ref'] matches 'contoso/contoso-prod/.github/workflows/*.yml@refs/heads/main'",
    "languageVersion": 1
  }
}

To require the repository to remain with a specific owner, also match repository_owner_id:

{
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "name": "MyGitHubOwnerFlexibleFIC",
  "issuer": "https://token.actions.githubusercontent.com",
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'repo:contoso/contoso-repo:ref:refs/heads/*' and claims['repository_id'] eq '456789' and claims['repository_owner_id'] eq '123456' and claims['job_workflow_ref'] matches 'contoso/contoso-prod/.github/workflows/*.yml@refs/heads/main'",
    "languageVersion": 1
  }
}

Related content

  • Last updated on