Microsoft Entra Workload ID

Flexible federated identity credentials (preview)

23 September 2026Feature update+37 / −18 lines

In brief

The guidance now covers applications and user-assigned managed identities, including Azure Resource Manager setup instructions and updated GitLab claim-matching requirements.

What Entra admins need to know

Managed identity administrators can use the updated guidance when configuring these credentials. 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 diff

View on Microsoft Learn

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

Flexible federated identity credentials (preview)

How do flexible federated identity credentials work?

Flexible federated identity credentials don't change the baseline functionality provided by federated identity credentials. These trust relationships are still used to indicate which token from the external IdP should be trusted by your ~~application.~~application or user-assigned managed identity. Instead, they extend the ability of federated identity credentials by enabling scenarios which previously required multiple federated identity credentials to instead be managed under a single flexible federated identity credential. A few examples include:

GitHub repositories with various workflows, each running on a different branch (or being used across branches). Previously, a unique federated identity credential was required for each of the branches in which workflows could run across. With flexible federated identity credentials, this scenario can be managed under a single federated identity credential.
Terraform ~~cloud~~Cloud run_phases plans, which each requires a unique federated identity credential. With flexible federated identity credentials, this can be managed under a single flexible federated identity credential.
Reusable GitHub Actions workflows, where wildcards can be used against GitHub's custom job_workflow_ref claim.

Supported identity resources

Flexible federated identity credentials are supported for applications and user-assigned managed identities.

Flexible federated identity credential language structure

"claims['sub'] matches 'repo:contoso/contoso-repo:ref:refs/heads/*' and claims['repository_id'] eq '456789'"


## Flexible federated identity credential expression language functionality

Flexible federated identity credentials currently support the use of a few operators across the enabled issuers. Single quotes are interpreted as escape characters within the flexible federated identity credential expression language.

Depending on the platform you're using, you need to implement different issuer URLs, claims, and operators. Use the following tabs to select your chosen platform.

### [GitHub](#tab/github)

Supported issuer URLs: `https://token.actions.githubusercontent.com`


Supported issuer URLs: `https://gitlab.com`, `https://gitlab.example.com`, and `https://gitlab.example.ca` where `example` can be any string.

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

Supported claims and operators per claim:

- Claim `sub` supports operators `eq` and `matches`.
- Claim `project_id` supports operator `eq`.

### [Terraform Cloud](#tab/terraformcloud)


You can use Azure CLI's `az rest` method to make REST API requests for flexible federated identity credential creation and management.

### Application

```bash
az rest --method post \
    --url https://graph.microsoft.com/beta/applications/{objectId}/federatedIdentityCredentials
    --body "{'name': 'FlexFic1', '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}}"

User-assigned managed identity

Use the Azure Resource Manager federated identity credential resource for a user-assigned managed identity.

az rest --method put \
    --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}/federatedIdentityCredentials/{credentialName}?api-version=2025-01-31-preview" \
    --body "{'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}}}"

Flexible federated identity credential properties

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 the GET and UPSERT operations. 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.

For an application, these properties are part of the Microsoft Graph federatedIdentityCredentials resource. For a user-assigned managed identity, Azure Resource Manager accepts and returns the properties through the Microsoft.ManagedIdentity federated identity credential resource.

Related content

Implement a flexible federated identity credential

@@ -1,12 +1,12 @@ --- title: Flexible federated identity credentials (preview)-description: Learn how Microsoft Entra Workload ID flexible federated identity credentials match token claims and reduce credential management overhead.+description: Learn how Microsoft Entra Workload ID flexible federated identity credentials work with applications and user-assigned managed identities. ms.topic: concept-article-ms.date: 08/14/2026+ms.date: 09/18/2026 ms.custom: msecd-doc-authoring-1018 ms.reviewer: ludwignick ai-usage: ai-assisted-#customer intent: As an application administrator, I want to understand flexible federated identity credentials so that I can manage trust for external workloads.+#customer intent: As an application or managed identity administrator, I want to understand flexible federated identity credentials so that I can manage trust for external workloads. ---  # Flexible federated identity credentials (preview)@@ -25,15 +25,19 @@ Flexible federated identity credentials can help reduce management overhead when  ## How do flexible federated identity credentials work?  -Flexible federated identity credentials don't change the baseline functionality provided by federated identity credentials. These trust relationships are still used to indicate which token from the external IdP should be trusted by your application. Instead, they extend the ability of federated identity credentials by enabling scenarios which previously required multiple federated identity credentials to instead be managed under a single flexible federated identity credential. A few examples include:+Flexible federated identity credentials don't change the baseline functionality provided by federated identity credentials. These trust relationships are still used to indicate which token from the external IdP should be trusted by your application or user-assigned managed identity. Instead, they extend the ability of federated identity credentials by enabling scenarios which previously required multiple federated identity credentials to instead be managed under a single flexible federated identity credential. A few examples include:  - GitHub repositories with various workflows, each running on a different branch (or being used across branches). Previously, a unique federated identity credential was required for each of the branches in which workflows could run across. With flexible federated identity credentials, this scenario can be managed under a single federated identity credential.-- Terraform cloud `run_phases` plans, which each requires a unique federated identity credential. With flexible federated identity credentials, this can be managed under a single flexible federated identity credential.+- Terraform Cloud `run_phases` plans, which each requires a unique federated identity credential. With flexible federated identity credentials, this can be managed under a single flexible federated identity credential. - Reusable GitHub Actions workflows, where wildcards can be used against GitHub's custom `job_workflow_ref` claim.  > [!NOTE] > -> Flexible federated identity credentials support is currently provided for matching against GitHub, GitLab, and Terraform Cloud issued tokens. This support exists only for federated identity credentials configured on application objects currently. You can only create and manage flexible federated identity credentials via Microsoft Graph or the Azure portal.+> Flexible federated identity credentials support is currently provided for matching against GitHub, GitLab, and Terraform Cloud issued tokens. You can configure flexible federated identity credentials on application objects and user-assigned managed identities.++## Supported identity resources++Flexible federated identity credentials are supported for applications and user-assigned managed identities.  ## Flexible federated identity credential language structure  @@ -51,16 +55,6 @@ Put together, an example GitHub flexible federated identity credential expressio "claims['sub'] matches 'repo:contoso/contoso-repo:ref:refs/heads/*' and claims['repository_id'] eq '456789'" ``` -## Set up federated identity credentials through Microsoft Graph--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 are mutually exclusive, so you can't define both within a federated identity credential.--- `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. This property is an alternate key and the value can be used to reference the federated identity credential via the [GET](/graph/api/federatedidentitycredential-get) and [UPSERT](/graph/api/federatedidentitycredential-upsert) operations. -- `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. - ## Flexible federated identity credential expression language functionality    Flexible federated identity credentials currently support the use of a few operators across the enabled issuers. Single quotes are interpreted as escape characters within the flexible federated identity credential expression language.  @@ -76,7 +70,7 @@ Flexible federated identity credentials currently support the use of a few opera  Depending on the platform you're using, you need to implement different issuer URLs, claims, and operators. Use the following tabs to select your chosen platform. -## [GitHub](#tab/github) +### [GitHub](#tab/github)  Supported issuer URLs: `https://token.actions.githubusercontent.com`  @@ -98,9 +92,12 @@ Supported claims and operators per claim:  Supported issuer URLs: `https://gitlab.com`, `https://gitlab.example.com`, and `https://gitlab.example.ca` where `example` can be any string.   +When you use mutable subjects with GitLab, your flexible federated identity credential expression must match the `sub` and `project_id` claims.+ Supported claims and operators per claim:  -- Claim `sub` supports operators `eq` and `matches` +- Claim `sub` supports operators `eq` and `matches`.+- Claim `project_id` supports operator `eq`.  ### [Terraform Cloud](#tab/terraformcloud) @@ -118,12 +115,34 @@ Explicit flexible federated identity credential support doesn't yet exist within  You can use Azure CLI's `az rest` method to make REST API requests for flexible federated identity credential creation and management.  +### Application+ ```bash az rest --method post \     --url https://graph.microsoft.com/beta/applications/{objectId}/federatedIdentityCredentials     --body "{'name': 'FlexFic1', '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}}" ``` +### User-assigned managed identity++Use the Azure Resource Manager federated identity credential resource for a user-assigned managed identity.++```azurecli+az rest --method put \+    --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}/federatedIdentityCredentials/{credentialName}?api-version=2025-01-31-preview" \+    --body "{'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}}}"+```++## Flexible federated identity credential properties++- `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 the [GET](/graph/api/federatedidentitycredential-get) and [UPSERT](/graph/api/federatedidentitycredential-upsert) operations. 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.++For an application, these properties are part of the Microsoft Graph `federatedIdentityCredentials` resource. For a user-assigned managed identity, Azure Resource Manager accepts and returns the properties through the `Microsoft.ManagedIdentity` federated identity credential resource.+ ## Related content  - [Implement a flexible federated identity credential](./workload-identity-federation-create-trust.md#set-up-a-flexible-federated-identity-credential-preview)