Set up a Flexible Federated identity credential (preview)

  • Article

This article provides a guide on how to set up a Flexible Federated identity credential in the Azure portal. Flexible federated identity credentials are an advanced feature of Microsoft Entra Workload ID that enhances the existing federated identity credential model.

Prerequisites

  • An Azure account with an active subscription. If you don't already have one, Create an account.
  • Create an app registration. Grant your app access to the Azure resources targeted by your external software workload.

Note

Flexible federated identity credentials support is not yet available for managed identities.

Setting 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 have been made 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 and 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.

Set up a Flexible Federated identity credential

  1. Navigate to Microsoft Entra ID and select the application where you want to configure the federated identity credential.
  2. In the left-hand navigation pane, select Certificates & secrets.
  3. Under the Federated credentials tab, select + Add credential.
  4. In the Add a credential window that appears, from the dropdown menu next to Federated credential scenario, select Other issuer.
  5. 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
  6. In Value enter the claim matching expression you want to use, for example claims['sub'] matches 'repo:contoso/contoso-repo:ref:refs/heads/*'
  7. 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.

Related content