Overview of federated identity credentials in Azure Active Directory (preview)

Namespace: microsoft.graph


APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Traditionally, developers use certificates or client secrets for their application's credentials to authenticate with and access services in Azure AD. To access the services in their Azure AD tenant, developers have had to store and manage application credentials outside Azure, introducing the following bottlenecks:

  • A maintenance burden for certificates and secrets.
  • The risk of leaking secrets.
  • Certificates expiring and service disruptions because of failed authentication.

Federated identity credentials are a new type of credential that enables workload identity federation for software workloads. Workload identity federation allows you to access Azure Active Directory (Azure AD) protected resources without needing to manage secrets (for supported scenarios). You create a trust relationship between an external identity provider and an app in Azure AD by configuring a federated identity credential. The federated identity credential is used to indicate which token from the external IdP should be trusted by your application. Once that trust relationship is created, your software workload can exchange trusted tokens from the external identity provider for access tokens from Microsoft identity platform. Your software workload then uses that access token to access the Azure AD protected resources to which the workload has been granted access. This eliminates the maintenance burden of manually managing credentials and eliminates the risk of leaking secrets or having certificates expire. For more information and supported scenarios, read about workload identity federation.

The federatedIdentityCredential resource represents the configuration of a federated identity credential via Microsoft Graph API. The following properties are the building blocks of federated identity credentials:

  • audiences—Lists the audiences that can appear in the external token. This field is mandatory, and defaults to "api://AzureADTokenExchange". It says what Microsoft identity platform should accept in the aud claim in the incoming token. This value represents Azure AD in your external identity provider and has no fixed value across identity providers - you may 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 and 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 Azure AD.

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.

Federated identity credentials are supported on applications only. A maximum of 20 federated identity credentials can be added per application object.

The federated identity credentials API is not available in national cloud deployments.

See also