Federated Credentials, Plainly: Trusting Another System's Token

Picture a partner hotel arrangement. You are staying at the Harbour Hotel, and your room card lets you into the spa at the hotel next door, because the two hotels have agreed to honour each other's guests. The spa desk does not hand you a new password; it looks at your card, checks that it really came from the Harbour Hotel, that it belongs to the room it claims, and that it was meant for this spa, and then gives you a day pass of its own. Software in today's cloud often lives in a similar situation. A build pipeline runs on GitHub, an application runs in a Kubernetes cluster, or a job runs in another company's cloud, and each needs to reach something in Microsoft's Azure cloud. The old answer was to copy an Azure password into that outside system and hope it never leaked. A federated credential is the newer answer: Azure agrees to trust the outside system's own proof of identity and trade it for an Azure pass, so no Azure secret ever has to leave home. This article explains what that trust is, what the few fields that define it really mean, how the exchange works step by step, and the limits and small surprises a newcomer should know, including what it means for artificial intelligence (AI) agents that run outside Azure.

The problem: software that lives somewhere else

Inside Azure, a program can use a managed identity, an identity that Azure creates and looks after for the resource the program runs on, so the program never sees a password. But a great deal of software that needs Azure does not run on Azure at all. A deployment pipeline on GitHub Actions, the automation service built into GitHub, needs to update an Azure web app. A service in a Kubernetes cluster, a system that runs and manages containers of software across many machines, needs to read an Azure storage account. A job in Amazon Web Services (AWS) or Google Cloud needs to write to an Azure database.

For years, the usual fix was a client secret: a long password created for an Azure application and pasted into the outside system's settings. It worked, but it brought every problem passwords bring. Someone had to copy it, store it, remember to renew it before it expired, and hope nobody printed it in a log or shared it in a chat. If it leaked, anyone holding it could sign in as that application from anywhere.

The outside systems, though, already know who their own workloads are. GitHub knows which repository and which branch a pipeline run belongs to. A Kubernetes cluster knows which service account a piece of software runs as. Each of them can issue a signed statement saying so. The question federation asks is simple: instead of copying an Azure secret out, why not let Azure trust that statement?

What a federated credential is

Microsoft calls the overall approach workload identity federation. A workload is simply a piece of software doing a job, such as a pipeline, a service or a scheduled task. Federation means two separate identity systems agree to recognise each other's proof. With workload identity federation, an identity in Microsoft Entra ID, Microsoft's cloud directory of users and software, is set up to trust tokens from an external identity provider such as GitHub Actions, Kubernetes, Google Cloud or AWS, and to exchange them for Microsoft Entra access tokens, the passes Azure services accept.

The thing that records this trust is called a federated identity credential, often shortened to FIC. It is attached either to a user-assigned managed identity, the kind of managed identity created as its own Azure resource, or to an app registration, the directory entry you create for an application you build. You can think of it as a short, written rule on that identity: 'accept tokens from this provider, about this workload, meant for this purpose.'

Notice what is missing from that rule: a secret. The federated credential stores no password and no key. It is a description of whose tokens to believe. The external system keeps signing its own tokens with its own keys, and Azure checks those signatures against keys the provider publishes openly. Nothing confidential has to cross from Azure to the outside system, or the other way.

The fields, in plain words

A federated identity credential has five fields, and three of them do almost all the work. In the hotel picture, they are the hotel's name on the card, the room number, and the desk the card was meant for.

The issuer is the web address of the external identity provider, the 'which hotel' field. It must match the issuer written inside the incoming token exactly. The subject is the identity of the workload inside that external system, the 'which room' field. It has no fixed format; each provider writes its own, so a GitHub subject describes a repository and the branch, environment or pull request involved, while a Kubernetes subject names a service account. The audience is the intended recipient of the token, the 'which desk' field. A credential holds one audience, and Microsoft recommends the value api://AzureADTokenExchange.

The remaining two fields are housekeeping. The name is a label of 3 to 120 characters that must be friendly to web addresses and cannot be changed once created. The description is free text for people. Issuer, subject and audience can each be up to 600 characters long.

The most important property of all is how strictly those three fields are compared. The issuer, subject and audience must match the incoming token exactly, and the comparison is case-sensitive, so capital and small letters count as different. There are no wildcards, the 'anything here' patterns many systems allow. Even a stray space at the start or end of the issuer is enough to block the exchange.

The exchange, step by step

Microsoft documents the exchange as six steps, and once the fields make sense, the steps read almost like a story.

First, the external workload asks its own identity provider for a token; a GitHub pipeline run asks GitHub, a Kubernetes service asks its cluster. Second, the provider issues that token, signed with the provider's key and carrying the issuer, subject and audience. Third, the workload sends the token to the Microsoft identity platform and asks for an access token for the Azure identity it wants to act as.

Fourth comes the check that matters. The platform looks for a federated identity credential on that identity whose issuer, subject and audience match the token, and validates the token's signature against the provider's OpenID Connect (OIDC) issuer address. OpenID Connect is a widely used standard for publishing identity information; among other things, it is how a provider publishes the public keys anyone can use to check its signatures. Fifth, if everything matches, the platform issues a Microsoft Entra access token. Sixth, the workload uses that token to call the Azure resource, which then checks, as always, whether this identity has been granted access there.

The workload never held an Azure secret at any point. It held a token from its own home system, and it got a short-lived Azure token in return.

Why exact matching is both the safety and the frustration

Exact matching is what makes the arrangement safe. A federated credential that trusts a particular GitHub repository's production environment will not accept a token from a different repository, a fork, or a test branch, because their subjects are different strings. The narrower the subject, the smaller the set of workloads that can become this identity.

The same strictness is the most common source of frustration. A credential copied with a capital letter in the wrong place, an issuer pasted with a trailing slash the provider does not use, or a space at the end of a line will simply not match, and the exchange fails. When it does, the error message tells you no matching record was found, not which character was wrong, so the fix is to compare the stored fields with the claims inside a real token, character by character.

There is also a small timing surprise. A newly created federated credential takes a short while to spread through Microsoft's systems. During that window a perfectly correct request can fail with the error AADSTS70021, 'No matching federated identity record found for presented assertion.' Microsoft recommends building retry logic into the first sign-in rather than assuming the configuration is wrong.

Limits and special cases worth knowing

A few rules shape how federated credentials can be used, and knowing them early saves redesigns later.

Each app registration or user-assigned managed identity can hold up to 20 federated identity credentials. Because every credential has a single, exact subject, a team with many repositories, branches or clusters can reach that limit faster than expected, which is one reason to group workloads thoughtfully rather than piling every trust onto one identity.

Federated credentials cannot be added to a system-assigned managed identity, the kind that is switched on for one Azure resource and deleted with it. Only user-assigned managed identities and app registrations can carry them.

Tokens issued by Microsoft Entra ID itself generally cannot be used as the outside token in this exchange; federation is designed for trusting other providers. The documented exception runs the other way: a managed identity can be the federated credential of an app registration. In that setup, the issuer is the tenant's sign-in address (https://login.microsoftonline.com/ followed by the tenant ID and /v2.0), the subject is the managed identity's object ID, and the audience is api://AzureADTokenExchange. The app and the managed identity must be in the same tenant, meaning the same organisation's directory, and the app can then reach resources in another tenant, though not in a separate sovereign cloud.

Finally, a preview feature called flexible federated identity credentials adds a small matching language for tokens from GitHub, GitLab and Terraform Cloud, so one credential can cover a defined pattern of subjects. Standard credentials remain exact-match only.

• Up to 20 federated identity credentials per app registration or user-assigned managed identity.
• Not available on system-assigned managed identities.
• No wildcards in standard credentials; flexible credentials (preview) add patterns for GitHub, GitLab and Terraform Cloud only.
• A managed identity can act as an app's federated credential within the same tenant, reaching other tenants but not other clouds.

What this means for AI agents

AI agents, programs that use a large language model (LLM) to plan steps and call tools, are often built, deployed and run outside Azure even when the data and models they use live inside it. A pipeline deploys the agent, a Kubernetes cluster hosts it, or another cloud runs it next to other services. Each of those places needs a way into Azure.

With a federated credential, none of them has to store an Azure secret. The pipeline proves itself with its GitHub token, the cluster-hosted agent with its Kubernetes service account token, and each receives a short-lived Azure token in exchange. There is no long-lived key in the agent's configuration for a prompt injection, text crafted to make the model follow an attacker's instructions, to coax into the open, and nothing to rotate on a calendar.

The trust does not disappear, though; it moves. Whoever can make the outside system issue a token with the right subject can become the Azure identity. For an agent, that means the subject should name the narrowest thing that genuinely needs access, such as one repository's protected production environment or one dedicated service account, and the Azure identity on the receiving end should be granted only the roles that agent's tasks require.

Decisions for the people who set it up

Federated credentials are quick to create and easy to forget, so the useful decisions are the ones made before the first credential exists.

Which identity carries the trust? A user-assigned managed identity keeps everything inside Azure's resource model; an app registration is the choice when the identity also needs settings only applications have. Either way, decide whether each workload gets its own identity or several share one, remembering that every trusted subject on a shared identity receives all of its access.

How narrow is the subject? Prefer the most specific subject the provider offers, such as a protected environment rather than any branch, and write down why each credential exists and which team owns it.

How will you notice changes? A federated credential is a trust path that holds no secret, so secret-scanning tools will never flag it. Put the creation and deletion of federated credentials under the same review you would give to adding a password to an application, and review the list on each identity regularly, since it can hold up to 20 entries and each one is a way in.

Glossary

Workload identity federation

An arrangement in which an Azure identity accepts tokens from an outside identity provider and exchanges them for Microsoft Entra tokens.

Federated identity credential (FIC)

The rule on an Azure identity that says which outside issuer, subject and audience to trust; it contains no secret.

Identity provider

A system that knows who its users or workloads are and issues signed tokens saying so.

Issuer

The web address of the identity provider that signed a token.

Subject

The identity of the specific workload inside the outside system, written in that provider's own format.

Audience

The intended recipient of a token; for this exchange Microsoft recommends api://AzureADTokenExchange.

OpenID Connect (OIDC)

A widely used identity standard that, among other things, lets a provider publish the public keys used to check its tokens.

Client secret

A password created for an application, which federation is designed to replace.

Tenant

One organisation's own instance of Microsoft Entra ID, with its own users, apps and identities.

Further reading

1. Workload identity federation (Microsoft Learn)
2. Important considerations and restrictions for federated identity credentials (Microsoft Learn)
3. Configure an application to trust a managed identity (Microsoft Learn)
4. federatedIdentityCredential resource type overview (Microsoft Graph)