Daily.Entra.News
Aboutmerill.net
Microsoft Entra Workload ID
Security

Set up a Flexible Federated identity credential (preview)

23 September 2026Feature update+91 / −48 lines

In brief

The documentation now explains setup for applications and user-assigned managed identities, using Microsoft Graph for applications and Azure Resource Manager for managed identities. It also adds details about credential properties, including claimsMatchingExpression.

What Entra admins need to know

Administrators managing user-assigned managed identities can use the new setup guidance. No action is required.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

View full page diffView on Microsoft Learn

The comparison below shows only the changed extract. Use the full-page view for complete context.

Set up a Flexible Federated identity credential (preview)

This article shows how to configureset up a flexible federated identity credential for an application inor user-assigned managed identity. You can use the Azure portal orportal, Microsoft Graph Explorer. Usefor an application, or Azure Resource Manager for a user-assigned managed identity. Before you begin, review the issuer-specific examples to create a credential for GitHub, GitLab, or Terraform Cloud.requirements in Prerequisites.

Prerequisites

Setting up federated identity credentials through Microsoft GraphUnderstand the credential properties

To accommodate the flexible federated identity credential functionality, the federatedIdentityCredentials resource is being extended with a new claimsMatchingExpression property. In addition to this, the subject property is now nullable. The claimsMatchingExpression and subject properties have been made mutually exclusive, so you can't define both within a federated identity credential.

  • PropertyDescription
    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. ThisFor applications, this property is an alternate keykey, and the valueyou can be useduse it to reference the federated identity credential viathrough a GET operation. For a user-assigned managed identity, the GET and UPSERT operations.
  • credential name is part of the Azure Resource Manager resource path.
    • claimsMatchingExpression: a new complex type containing two properties, value and languageVersion.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 Federatedflexible federated identity credential

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

    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.

    Azure portalApplication - Azure portal

    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.

Microsoft Graph ExplorerApplication - Microsoft Graph

To create the credential by using Microsoft Graph Explorer:

    • Open the Microsoft Graph Explorer.

    • In the Request section, enter the URL that corresponds to the application: https://graph.microsoft.com/beta/applications/{objectId}/federatedIdentityCredentials.

    • Add the following request body: 

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

    • Select Run query to create the federated identity credential.

Managed identity - Azure portal

To create the credential for a user-assigned managed identity in the Azure portal:

  • In the Azure portal, open the user-assigned managed identity where you want to configure the credential.
  • Under Settings, select Federated credentials.
  • Select Add credential.
  • For Federated credential scenario, select Other issuer.
  • 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 claims matching expression. For example, enter claims['sub'] matches 'repo:contoso/contoso-repo:ref:refs/heads/*' and claims['repository_id'] eq '456789'.
  • Select Add to save the credential.

Managed identity - ARM REST

Create the credential under the user-assigned managed identity's Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials resource.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}/federatedIdentityCredentials/{credentialName}?api-version=2025-01-31-preview
Content-Type: application/json

{
  "properties": {
    "issuer": "https://token.actions.githubusercontent.com",
    "audiences": [
      "api://AzureADTokenExchange"
    ],
    "claimsMatchingExpression": {
      "value": "claims['sub'] matches 'repo:contoso/contoso-repo:ref:refs/heads/*' and claims['repository_id'] eq '456789'",
      "languageVersion": 1
    }
  }
}

The request must contain either subject or claimsMatchingExpression, but not both.

More examples of Flexible Federated identity credentials

GitLab

Get the numeric project_id value from the GitLab ID token. Include this immutable claim when the sub claim uses the mutable project_path format.

{
  "audiences": [
  "name": "MyGitLabFlexibleFIC",
  "issuer": "https://gitlab.example.com",
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'project_path:contoso/contoso-project:ref_type:branch:ref:main' and claims['project_id'] eq '57382910'",
    "languageVersion": 1
  }
}

### [Terraform Cloud](#tab/terraform-cloud)

The following example matches Terraform Cloud runs for any run phase in the specified workspace:

```json
{
  "audiences": [
Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…