Flexible Federated Identity Credentials in Entra ID |...

The Problem with "Working" Federation Setups

Workload identity federation is one of the best security improvements you can make in CI/CD.

It replaces long-lived client secrets with short-lived tokens issued by a trusted identity provider such as GitHub or Terraform Cloud. That means fewer secrets to rotate, fewer credentials to leak, and a much cleaner security story for pipelines.

The problem is that many federation designs start simple and then get messy fast.

At first, you create a federated credential for one repository and one branch. Everything looks clean. Then the team adds more branches, reusable workflows, environment-specific pipelines, preview deployments, and Terraform Cloud workspaces. Suddenly one app registration needs a growing pile of federated identity credentials just to keep the automation working.

That is where flexible federated identity credentials become useful.

This feature in Microsoft Entra ID lets you match incoming claims with expressions instead of exact one-to-one subject strings. Used well, it reduces trust rule sprawl without falling back to overly broad patterns.

This guide covers what flexible federated identity credentials are, when they help, how to use them with GitHub Actions and Terraform Cloud, and how to avoid turning a convenience feature into a trust policy you regret later.

If you need the baseline on standard workload identity controls first, read the new [Conditional Access for workload identities guide](/blog/conditional-access-for-workload-identities-entra-id) after this. The two capabilities solve different problems and work well together.

What Flexible Federated Identity Credentials Actually Solve

Standard federated identity credentials in Entra ID rely on exact matching for values such as:

issuer
audience
subject

That works fine when each trust relationship is narrow and static.

It becomes awkward when your workload identity needs to trust:

Multiple branches in the same GitHub repository
Reusable GitHub workflows
Different Terraform Cloud run phases
Patterns that change regularly but still follow a safe naming convention

Without flexible matching, you often end up creating one federated credential per allowed subject pattern. That increases administrative overhead and encourages bad shortcuts, such as broadening trust in ways that are not well documented.

Flexible federated identity credentials let you define a claims matching expression instead. That means you can describe allowed patterns more clearly and reduce the number of separate trust objects you need to manage.

Why This Matters for Security, Not Just Convenience

At first glance, this feature sounds like a way to make administrators' lives easier. It is that, but the security angle matters more.

Teams that hate managing too many trust objects often drift toward one of two bad outcomes:

They keep long-lived client secrets because federation feels too painful to maintain
They create loose trust relationships without a clear model

Flexible matching gives you a middle path.

You can stay on federation, keep the setup auditable, and still support real-world CI/CD patterns.

That makes this article especially relevant if you already run:

GitHub Actions for deployments or infrastructure changes
Terraform Cloud for IaC execution
Azure resources accessed by external workloads

Standard Federated Credentials vs Flexible Federated Credentials

Here is the practical difference.

Standard federated credential

You define an exact trusted subject such as:

repo:your-org/platform-infra:ref:refs/heads/main

That is precise and safe, but only for that single branch pattern.

Flexible federated credential

You define an expression such as:

claims['sub'] matches 'repo:your-org/platform-infra:ref:refs/heads/release/*'

Now you can trust a controlled pattern instead of one exact string.

This is powerful. It is also the reason you need guardrails.

What a Claims Matching Expression Looks Like

Flexible federated identity credentials introduce the claimsMatchingExpression property.

At a high level, the expression has three parts:

The claim lookup
The operator
The value to compare against

Example:

"claims['sub'] matches 'repo:contoso/platform-infra:ref:refs/heads/release/*'"

You will mostly care about these operators:

eq for exact match
matches for wildcard-based matching

In plain English:

Use eq when one exact value is correct
Use matches when you need a controlled wildcard

If you can safely use eq, use eq.

Supported Platforms and Important Limits

Flexible federated identity credentials are not a universal wildcard engine for every possible IdP. They are currently supported for specific issuers and claims.

The most relevant supported issuers for your site audience are:

GitHub
GitLab
Terraform Cloud

There are also important limitations to remember:

Support is provided for specific token issuers and claims, not arbitrary external platforms
Flexible federated identity credentials currently apply to application objects
The subject property and claimsMatchingExpression are mutually exclusive
Tooling support can lag behind the platform itself, so Graph or az rest may be required

That last point is worth planning for. If your team expects a polished Azure CLI or Terraform provider experience for every operation, you may need to adjust expectations.

When You Should Use Flexible FIC

Use flexible federated identity credentials when all of these are true:

You already want federation instead of static secrets
Your trust relationships follow a predictable pattern
Exact one-to-one subject mapping is creating operational sprawl
You can describe the trust boundary clearly

Good examples:

GitHub repo branches that follow a release naming pattern
Reusable workflow references that should be trusted from a known path
Terraform Cloud run phases for a bounded set of workspaces

Do not use flexible matching just because it feels more elegant. Use it because the trust model is clear and the wildcard pattern is still narrower than the operational burden of separate exact entries.

GitHub Actions: The Real-World Use Case

This is where most teams first feel the pain.

Imagine you deploy Azure infrastructure from GitHub Actions. You start with one branch:

repo:your-org/platform-infra:ref:refs/heads/main

Then the team wants:

release/* branches
A reusable workflow used by multiple repos
Separate deployment flows for preview and production

Now your exact-match trust model becomes noisy.

Example 1: Allow release branches in one repository

{
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "issuer": "https://token.actions.githubusercontent.com",
  "name": "github-release-branches",
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'repo:your-org/platform-infra:ref:refs/heads/release/*'",
    "languageVersion": 1
  }
}

This is reasonable if your deployment model genuinely allows all release/* branches.

Example 2: Restrict to a reusable workflow

This is where flexible matching gets more useful than a plain branch wildcard.

{
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "issuer": "https://token.actions.githubusercontent.com",
  "name": "github-reusable-workflow-main",
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'repo:your-org/platform-infra:ref:refs/heads/*' and claims['job_workflow_ref'] matches 'your-org/shared-pipelines/.github/workflows/*.yml@refs/heads/main'",
    "languageVersion": 1
  }
}

This gives you a better trust story than "any branch in any repo can authenticate." You are saying:

The token must come from a repo pattern I expect
The workflow itself must come from a trusted reusable workflow path on main

That is a much stronger model.

GitHub Design Tips That Matter

Flexible FIC for GitHub Actions is not just about writing a wildcard. It is about writing the *right* wildcard.

Good pattern

Trust a specific repository and a narrow branch family:

repo:your-org/platform-infra:ref:refs/heads/release/*

Weak pattern

Trust every branch in a repo with no workflow restriction:

repo:your-org/platform-infra:ref:refs/heads/*

That may be acceptable in some repos, but only if every branch is equally trusted to access Azure. In most organizations, that is not true.

Better pattern

Combine branch constraints with job_workflow_ref whenever possible.

This is especially useful when:

Multiple repositories call a central workflow
You want to separate trusted deployment logic from general repo activity
You want security to review one reusable workflow instead of many independent YAML files

Terraform Cloud: Another Strong Fit

Terraform Cloud is another case where flexible FIC can clean things up significantly.

A standard exact-match model may require separate trust entries for different run_phase values or workspace patterns. That gets noisy in larger environments.

Example: Allow multiple run phases for one workspace pattern

{
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "issuer": "https://app.terraform.io",
  "name": "tfc-network-prod",
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'organization:your-org:project:platform:workspace:network-prod:run_phase:*'",
    "languageVersion": 1
  }
}

That is much cleaner than managing separate credentials for each run phase when the workspace itself is the real trust boundary.

Example: Pattern across a controlled workspace family

{
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "issuer": "https://app.terraform.io",
  "name": "tfc-platform-prod-family",
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'organization:your-org:project:platform:workspace:prod-*:run_phase:*'",
    "languageVersion": 1
  }
}

This can be useful if your workspace naming is disciplined and the same Azure access pattern truly applies to the whole family.

If your workspace names are chaotic, flexible matching will not save you. It will just make chaos easier to encode.

Practical Setup Paths

There are two realistic ways most teams configure flexible FIC today:

Azure portal
Microsoft Graph or az rest

For automation-heavy teams, Graph or az rest is often the better fit because it is explicit, scriptable, and easy to review in code.

Example with `az rest`

az rest --method post   --url https://graph.microsoft.com/beta/applications/<object-id>/federatedIdentityCredentials   --body '{
    "audiences": ["api://AzureADTokenExchange"],
    "issuer": "https://token.actions.githubusercontent.com",
    "name": "github-release-branches",
    "claimsMatchingExpression": {
      "value": "claims['''sub'''] matches '''repo:your-org/platform-infra:ref:refs/heads/release/*'''",
      "languageVersion": 1
    }
  }'

The exact escaping is ugly, but the benefit is that the trust rule lives in a repeatable automation path instead of a one-time manual click path.

Security Guardrails You Should Not Skip

Flexible matching is useful because it allows broader patterns than exact match. That is also why it needs discipline.

1. Treat naming conventions as security boundaries

If your branch naming and workspace naming are inconsistent, your wildcard rules will be inconsistent too.

Good federation design starts with good naming.

2. Avoid organization-wide trust patterns unless you can defend them

A pattern like "any repo in the org" is easy to write and hard to justify.

Keep trust as close as possible to:

A single repository
A single workflow path
A single workspace or controlled workspace family

3. Prefer trusted reusable workflows over broad branch wildcards

If your deployment logic is centralized in a reviewed reusable workflow, you can narrow the trust boundary to that workflow. That is usually stronger than trusting every branch equally.

4. Review privilege on the Azure side too

Federation solves authentication risk, not authorization excess.

If the app registration has broad subscription-level permissions, a beautifully designed flexible FIC still leads to too much blast radius.

Pair this with:

Least privilege RBAC
Separate identities for separate trust levels
Narrow role assignments per environment

5. Document why the wildcard exists

A year from now, someone should be able to answer:

Why does this pattern exist?
Which repos or workspaces depend on it?
What would break if we narrowed it?

If the answer is "nobody knows," the trust rule is already drifting out of control.

Common Mistakes

Using flexible matching where exact match is enough

If one repo and one branch are all you need, keep it exact. Simpler is safer.

Writing wildcards before understanding the token claims

Inspect the real issuer and subject format first. Do not build expressions from memory or assumption.

Trusting every branch equally

Feature branches, personal branches, and deployment branches often should not share the same Azure trust path.

Forgetting the difference between app registration object ID and service principal object ID

Flexible FIC configuration is tied to the application object. Keep your IDs straight or you will waste time debugging the wrong object.

Treating flexible FIC as a replacement for Conditional Access

It is not. Flexible FIC controls how external workloads authenticate to Entra using federation. [Conditional Access for workload identities](/blog/conditional-access-for-workload-identities-entra-id) controls policy decisions for supported service principal token requests.

They complement each other.

How This Fits with the Rest of Your Cloud Security Stack

This article connects naturally with several areas you already cover on Protego.

Terraform security

If Terraform Cloud or GitHub Actions is going to authenticate into Azure, also harden the backend and state path. Your [Terraform remote state in Azure Storage guide](/blog/terraform-remote-state-azure-storage-security) is the right companion read.

Team Terraform design

If workspace and environment naming are inconsistent, federation design gets weaker. The [Terraform best practices article](/blog/terraform-best-practices-for-teams) helps on that side.

CI/CD security

This is also part of a broader [DevSecOps pipeline security model](/blog/devsecops-integrating-security-into-cicd-pipelines-2026). Authentication is one layer. Secret scanning, approval design, and least privilege still matter.

A Safe Rollout Strategy

If you are moving from static secrets or from a messy exact-match sprawl, use this sequence:

Inventory the current federated credentials and secret-based auth flows
Identify the real trust boundary for each workflow
Start with one GitHub or Terraform Cloud use case
Write the narrowest expression that still fits the operational need
Validate the token claims carefully
Test in a non-production app registration first
Confirm Azure RBAC is still least privilege
Document the pattern and owner
Migrate production only after the design is clear

This is one of those areas where five extra minutes of design can save you hours of cleanup later.

Final Checklist

[ ] You know the exact issuer URL for the platform
[ ] You inspected the real claim format before writing the expression
[ ] The wildcard is narrower than "everything in the org"
[ ] You used eq when exact match was enough
[ ] You used job_workflow_ref for GitHub when it improved trust boundaries
[ ] Azure RBAC permissions are still least privilege
[ ] The rule has a clear owner and documented purpose

Frequently Asked Questions

What are flexible federated identity credentials in Entra ID?

They are federated identity credentials that use a claims matching expression instead of a single exact subject string, allowing controlled pattern matching for supported issuers such as GitHub and Terraform Cloud.

When should I use flexible FIC instead of standard federated credentials?

Use them when exact one-to-one subject matching creates unnecessary sprawl and your trust boundary can still be expressed safely with a narrow pattern.

Does flexible FIC work with GitHub Actions?

Yes. GitHub is one of the key supported platforms, including support for claims such as sub and job_workflow_ref.

Can I use flexible FIC with Terraform Cloud?

Yes. It is a strong fit for Terraform Cloud, especially when you need to support multiple run phases or a controlled workspace family.

Should I replace all exact-match credentials with flexible ones?

No. Exact match is still the safer default when it is operationally simple enough. Flexible matching is best for cases where the pattern is legitimate and well understood.

Closing Thought

Flexible federated identity credentials are not exciting because they add more flexibility. They are exciting because they make it easier to stay on a secure federation model without drowning in exception management.

That matters in the real world. Security controls that are too painful to manage often get bypassed. Flexible FIC gives cloud and security teams a way to keep the trust boundary explicit, reduce static secret usage, and support modern CI/CD patterns without turning the setup into a maintenance nightmare.