Solution Architecture · Enterprise Architecture (TOGAF 10) · Target-State & Transition Architecture · Microservices · Event-Driven Architecture · Domain-Driven Design · API-Led Integration · Strangler-Fig Migration · C4 Modelling · HLD / LLD · Architecture Decision Records

Eleven terms, comma-separated, in no particular order. It reads as a keyword list — and interviewers read it that way too, which is why the follow-up question is usually some variant of "pick one and tell me what you actually did with it."

But they aren't eleven independent skills. On a real modernisation they happen in a specific order, each one answering a question the previous one raised. This post walks that order, and says where each concept earns its keep — and where it doesn't.

The running example throughout: you have been handed a legacy monolith and asked to modernise it. That is the engagement most of these words were invented for.

1 · Where you sit — enterprise vs solution architecture

The first question is not technical. It is what am I allowed to decide?

Enterprise architecture is the organisation-wide view: the capability map, the technology standards, the principles, the roadmap across many programmes. Solution architecture is one solution inside that frame. If you are the solution architect, the EA function is your constraint set and often your approval gate.

Getting this boundary wrong is the most common early mistake. Architects who ignore the EA context design something elegant that gets rejected at a design authority for using a database the organisation has committed to retiring. Architects who over-defer produce a design that satisfies every standard and solves nothing.

What TOGAF is actually for

TOGAF 10 gets sneered at, usually by people who have only met it as a certification. Its real value is not the ADM phases — most organisations that "do TOGAF" by running every phase produce enormous documents nobody reads.

Its value is vocabulary and artefacts. It gives you agreed words for baseline, target, and transition architecture, and a standard set of deliverables that a governance body already knows how to review. When you present a target-state architecture and a set of transition architectures, a TOGAF-literate design authority knows exactly what it is looking at and what it is being asked to approve.

That is the honest pitch: TOGAF is a shared language for getting decisions made in large organisations. Use the parts that buy you that and skip the rest.

Worth saying in an interview

"I use TOGAF for the artefact vocabulary and the governance touchpoints, not as a process to follow end to end. Running the full ADM on a single solution is usually ceremony." This lands well because it signals you have used it rather than passed an exam on it.

2 · Finding the seams — domain-driven design

You now know your scope. The next question is where does this monolith naturally come apart?

This is where domain-driven design does its real work — and it is almost always applied too late. DDD is not a coding style. Its contribution at this stage is the bounded context: a boundary inside which a term means exactly one thing.

The classic example is worth using because it is true everywhere. "Customer" in a billing context is an account with a payment method and a credit limit. "Customer" in a support context is a person with a contact history and a sentiment score. Same word, different model, different lifecycle, different team. That is two bounded contexts, and the seam between them is where a service boundary belongs.

Why this matters more than any technology choice: if you draw service boundaries from the existing database schema or the current team structure instead of from the domain, you get a distributed monolith — services that cannot be deployed independently because every change touches three of them. You have taken on all the operational cost of microservices and none of the benefit. This is the single most common failure mode in modernisation programmes, and it is decided at this step, months before anyone writes a service.

The practical technique

Run event storming with the people who actually do the work — not their managers. You put domain events on a wall in time order, then cluster them. The clusters are your candidate contexts. It takes a day or two and it is worth more than a month of reading the existing code.

Then draw a context map showing how the contexts relate: which is upstream, which is downstream, where you need an anti-corruption layer to stop a legacy model leaking into a clean one.

3 · Where you are going — target-state architecture

Now you can describe the destination.

A target-state architecture describes the estate as it should be once the work is complete: the contexts as services, the data stores, the integration patterns, the runtime platform, the non-functional characteristics it must hit.

Two rules I would defend in any review:

The target state must be falsifiable. "Cloud-native, scalable, event-driven" is not a target state, it is an aspiration. A target state names the services, the data ownership, and the specific non-functionals — this service owns order data, exposes it over an API-led contract, and must sustain 400 requests per second at p95 under 200ms. If nobody could ever tell you that you had failed to reach it, you have not described it.

The target state is allowed to be wrong. It is a hypothesis about a future that is eighteen months away. Write it as a document with a version number and a review date, not a monument.

4 · How you get there — transition architectures

This is the step most architects skip, and it is why modernisations stall.

A transition architecture is an intermediate state that is itself deployable, operable and valuable. Not a milestone on a Gantt chart — a real architecture you could run the business on if the programme were cancelled tomorrow.

The test is blunt: if funding stopped at the end of this transition, would the organisation be better off than before it started? If the answer is no, it is not a transition architecture, it is a partially finished migration. And funding does stop. Priorities change, sponsors move, budgets get cut. A modernisation composed of three well-chosen transition states survives that; one composed of a single eighteen-month leap to the target state does not.

In practice each transition typically moves one or two bounded contexts out, leaves the rest in the monolith, and routes traffic accordingly. The legacy system keeps running throughout.

The interview version

When someone asks how you approach a migration, the answer that separates you is not "strangler-fig" — everyone says that. It is "I define transition architectures such that each one is independently valuable, because programmes get cancelled and I want every stage to have left the estate better than it found it."

5 · What shape it takes — microservices, events, and API-led integration

Only now does the technology shape get decided, and this ordering is deliberate: the shape follows the seams, not the other way round.

Microservices are an organisational decision first

Conway's law is not a curiosity, it is a design constraint. Microservices buy you independent deployability — and independent deployability is only worth its cost if you have independent teams who need to ship without coordinating.

Three teams and a monolith they can all release weekly? Microservices will make you slower. Twelve teams blocked behind a shared release train? Now the cost is worth paying.

Be honest about that cost: distributed tracing, service discovery, contract versioning, eventual consistency, a deployment pipeline per service, and a much harder debugging story. A modular monolith with clean bounded contexts is frequently the better answer, and saying so in an interview signals judgement rather than fashion.

Event-driven architecture buys decoupling and charges you in debuggability

Publishing an event instead of calling an API removes the temporal coupling between producer and consumer. The producer does not know or care who listens. That is genuinely powerful — it is what lets you add a new consumer without touching the producer.

What it costs you is linear reasoning. With a synchronous call you can read the code and follow the request. With events you cannot; you have to reconstruct the flow from a trace. Choose it where the decoupling is worth that, and instrument accordingly from day one — correlation IDs threaded through every message, not added after the first incident.

Also decide explicitly between event notification (thin message, consumer calls back for detail) and event-carried state transfer (fat message, consumer needs nothing else). The second removes a runtime dependency and costs you payload size and staleness. Architects who have not thought about this distinction get caught out by it.

API-led integration is about contracts, not about REST

API-led means the boundary between contexts is an explicit, versioned contract rather than a shared database or a direct table read. That is the whole idea. Whether it is REST, gRPC or GraphQL is a downstream detail.

The discipline that makes it work is contract ownership: the service owning the data owns the contract, consumers code against the contract, and breaking changes go through versioning rather than a coordinated release. The moment a consumer reads the producer's database directly, you no longer have an architecture, you have a shared mutable global.

6 · Actually moving — strangler-fig migration

You know the seams, the destination, the route and the shape. Now you move — without a big-bang cutover, because big-bang cutovers of business-critical systems fail at a rate that should end the conversation.

The strangler-fig pattern puts a facade in front of the legacy system and moves functionality behind it one piece at a time. Traffic for migrated capability routes to the new service; everything else falls through to the monolith. Both run in parallel, indefinitely if need be.

The facade is easy. The data is not.

Every article on strangler-fig spends its time on routing. Routing is a gateway rule. The difficulty is that the monolith's database is one schema with foreign keys across every context, and your new service needs to own its data.

The options, none of them free:

Pick per context rather than globally, and write down which one you picked and why — which is the next section.

Have a stopping rule

Strangler-fig migrations die half-finished more often than they fail outright. A facade, three new services, and a monolith that still owns 70% of the functionality is the worst of both worlds, and it is a stable equilibrium because the remaining pieces are always the hardest.

Decide up front what "done" means and what you will do with the remnant. Sometimes the honest answer is that the last 20% stays in the legacy system permanently, wrapped and left alone. That is a legitimate target state. An unplanned version of it is not.

7 · Communicating it — C4 and the HLD/LLD pair

An architecture that cannot be explained does not get approved, and an architecture that is explained differently to each audience does not get built.

C4 works because it has exactly four zoom levels

The discipline that makes C4 useful is the zoom relationship: each diagram elaborates exactly one box from the level above. That is what stops the sprawling any-shape-any-arrow diagrams that most organisations call architecture. If you take one thing from C4, take that constraint.

In practice you will draw levels 1 and 2 constantly, level 3 for the complicated containers, and level 4 essentially never.

HLD and LLD, and which one people actually read

The high-level design is the solution-wide document: context, containers, integration patterns, data ownership, non-functional requirements, security model, and the decisions that shaped it. It is what goes to a design authority.

The low-level design is per-component: schemas, interface definitions, sequence flows, error handling, retry semantics.

Being realistic about their lifespan changes how you write them. An HLD is read carefully once, at approval, and then skimmed. An LLD is read by the team building the thing and then goes stale within a quarter. Neither is where your reasoning survives — which is the last piece.

8 · Recording why — architecture decision records

The most valuable document in the set is also the smallest.

An architecture decision record is a short file, in the repository, capturing one decision: the context, the options, what was chosen, and what it costs. One decision per record, numbered, immutable. When a decision is reversed you do not edit the old record — you write a new one that supersedes it, and the history stays visible.

# ADR-014 · Event-carried state transfer for order status

**Status:** Accepted · 2026-03-11 · supersedes ADR-009

## Context
Fulfilment, billing and notifications all need order status. Today each
calls the Orders API on every state change — roughly 40 calls/sec at peak,
and an Orders outage takes all three down with it.

## Decision
Orders publishes a fat OrderStatusChanged event carrying the fields
consumers need. Consumers maintain their own read models.

## Consequences
- Orders is no longer on the critical path for those three services
- Consumers tolerate staleness of up to ~2s
- Payload is larger, and adding a field consumers need is a contract change
- We now have four copies of order status and must accept that

## Alternatives considered
- **Thin event + callback** — keeps payload small but leaves the runtime
  dependency on Orders, which was the problem we set out to solve
- **Shared read replica** — rejected; reintroduces schema coupling

The section that earns its place is "alternatives considered." Eighteen months later, someone will propose the thing you already rejected. Without the record they will re-litigate it from scratch, usually badly, and possibly do it. With the record the conversation takes five minutes.

ADRs also do something no other artefact does: they make an architect's reasoning reviewable. A colleague can disagree with a decision and see exactly which assumption they disagree with.

A tell worth knowing

If you are interviewing an architect and want one question that separates depth from vocabulary, ask them to describe a decision they got wrong and how they found out. The people who keep ADRs answer it immediately, because they wrote the superseding record themselves.

What this sequence is really for

The eleven terms are not a toolkit you pick from. They are a chain in which each link answers a question the previous one opened:

1. EA / TOGAF — what am I allowed to decide, and who approves it?

2. Solution architecture — what is my scope?

3. DDD — where does this system come apart?

4. Target-state — what does good look like, specifically?

5. Transition architectures — what is the route, and is each step worth shipping alone?

6. Microservices / EDA / API-led — what shape, and is the cost justified?

7. Strangler-fig — how do we move without a big bang?

8. C4 / HLD / LLD — how do we explain it to each audience?

9. ADRs — how does the reasoning survive us?

An interviewer asking about any one of these is usually probing whether you know its neighbours. Someone who can explain why bounded contexts must precede service boundaries, or why a transition architecture has to be independently valuable, is demonstrating that they have run the sequence — not that they have read the list.

And if you only adopt one thing from all eleven: write ADRs. They are the cheapest artefact here and the only one that is still being read in three years.

Every article on this topic explains the pieces. Very few say what order to do them in, or what you actually put in the email to the partner.

This is the runbook: you own an API, a partner service must call it with no user involved, and they will authenticate with a certificate. Eight steps, the commands, the handover pack, a troubleshooting table of the real AADSTS codes, and a rotation procedure that does not require downtime.

It closes with the questions I have been asked about this in interviews, and the shape of an answer that reads as experience rather than certification.

What you are building

Two separate timelines get confused with each other. The registration work happens once, before anything runs. The token exchange happens on every call.

The certificate is only ever used by the partner to sign an assertion to Entra — it never travels to your gateway or your backend. Your gateway only ever sees a bearer token, which is why the validation policy is the same regardless of how the partner authenticated.

Step 1 · Pick the registration model

Decide this first, because everything after depends on it.

The rest of this runbook uses single-tenant: you create an app registration per partner in your own tenant, they hold a certificate for it. It is simpler to operate and far easier to revoke, and it is what most enterprise partner integrations actually look like.

Step 2 · Register and expose your API

Done once for the API, not per partner.

# Create the app registration that represents your API
az ad app create \
  --display-name "orders-api" \
  --sign-in-audience AzureADMyOrg

# Note both values it returns — you need appId and id (the object id)
API_APP_ID="<appId>"
API_OBJ_ID="<id>"

# Give it an Application ID URI. This becomes the token audience.
az ad app update --id $API_APP_ID \
  --identifier-uris "api://orders-api"

# A service principal must exist in the tenant or token requests fail
# with AADSTS500011 — "resource principal not found"
az ad sp create --id $API_APP_ID

Do this now or debug it later

Force v2 tokens. If you skip it, Entra issues v1 tokens whose issuer is https://sts.windows.net/{tenantId}/, your validate-jwt expects the /v2.0 issuer, and you get a 401 that looks like a signature problem and isn't.

az rest --method PATCH \
  --uri "https://graph.microsoft.com/v1.0/applications/$API_OBJ_ID" \
  --headers "Content-Type=application/json" \
  --body '{"api":{"requestedAccessTokenVersion":2}}'

Step 3 · Define app roles

For service-to-service with no user, permissions are app roles with allowedMemberTypes: ["Application"]. These land in the roles claim. Do not use OAuth2 permission scopes here — those are for delegated access and produce scp, which a daemon token will never have.

app-roles.json — generate a fresh GUID for each role id

[
  {
    "id": "6f9c1a54-3d7e-4b21-9f0a-2c8d5e7b1a33",
    "allowedMemberTypes": ["Application"],
    "displayName": "Read orders",
    "description": "Read-only access to the orders API.",
    "value": "Orders.Read",
    "isEnabled": true
  },
  {
    "id": "b21e7f08-95c4-42da-8ad6-71f3c0e94d17",
    "allowedMemberTypes": ["Application"],
    "displayName": "Read and write orders",
    "description": "Create and amend orders.",
    "value": "Orders.ReadWrite",
    "isEnabled": true
  }
]

az ad app update --id $API_APP_ID --app-roles @app-roles.json

# Keep the role GUIDs — you need them to grant the role in step 5

Step 4 · Onboard the client, and the certificate

This is the step where the premise usually goes wrong, so it is worth being precise about who does what.

You do not generate the certificate

The partner generates the key pair and sends you only the public certificate — a .cer or .pem. You upload that to their app registration. The private key never leaves their estate, and you never hold material that could impersonate them.

If you generate a .pfx and email it to them, you have created a shared secret with a private key in a mailbox, and you can no longer prove which party made any given call. That is worse than a client secret, not better. If a partner genuinely cannot generate a certificate, use a client secret and be honest that you did — don't ship a private key around.

What the partner runs on their side, once:

# Partner generates a key pair and a self-signed certificate.
# Self-signed is fine here — Entra trusts it because YOU registered it,
# not because a CA vouched for it.
openssl req -x509 -newkey rsa:2048 -sha256 -days 730 -nodes \
  -keyout acme-orders-client.key \
  -out    acme-orders-client.cer \
  -subj   "/CN=acme-orders-client"

# They keep the .key. They send you ONLY the .cer

Then you register their client application and attach the certificate they sent:

# One app registration per partner — never share one across partners,
# or you lose the ability to revoke or attribute per partner
az ad app create \
  --display-name "orders-client-acme" \
  --sign-in-audience AzureADMyOrg

CLIENT_APP_ID="<appId>"

# Attach their PUBLIC certificate. --append is important: without it
# this command REPLACES every existing credential on the app.
az ad app credential reset \
  --id $CLIENT_APP_ID \
  --cert @acme-orders-client.cer \
  --append

# The client needs a service principal to be assignable a role
az ad sp create --id $CLIENT_APP_ID

Step 5 · Grant the app role

For application permissions there is no user to consent, so "admin consent" is an app role assignment on the client's service principal. This is the step that puts the roles claim in the token — without it the partner gets a perfectly valid token that your policy then rejects with 403.

# Object ids of the two service principals
CLIENT_SP=$(az ad sp show --id $CLIENT_APP_ID --query id -o tsv)
API_SP=$(az ad sp show --id $API_APP_ID --query id -o tsv)

# Assign Orders.Read (the GUID from app-roles.json)
az rest --method POST \
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$CLIENT_SP/appRoleAssignments" \
  --headers "Content-Type=application/json" \
  --body "{
    \"principalId\": \"$CLIENT_SP\",
    \"resourceId\":  \"$API_SP\",
    \"appRoleId\":   \"6f9c1a54-3d7e-4b21-9f0a-2c8d5e7b1a33\"
  }"

# Verify — this is what the partner will get in their roles claim
az rest --method GET \
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$CLIENT_SP/appRoleAssignments"

Grant the narrowest role

Assign Orders.Read and make them come back and ask for Orders.ReadWrite. Each role is a separate assignment you can add or remove independently, which means a partner's permissions are a one-command change with an audit record — not a redeployment.

Step 6 · The onboarding pack

Send exactly this, and nothing else. It contains no secrets, so it can go by normal email.

Never send: a .pfx, a private key, a client secret, or the backend's direct URL.

Step 7 · The APIM policy fragment

A policy fragment is an APIM object holding a reusable block of policy. Author it once, include it from every API that needs partner token validation, and fix a bug in one place. Create it under APIM → Policy fragments → Add, or via Bicep.

Policy fragment · name: validate-partner-token

<fragment>
  <!-- {{named-values}} come from APIM Named values, so tenant and
       audience are not hard-coded per environment -->
  <validate-jwt
      header-name="Authorization"
      failed-validation-httpcode="401"
      failed-validation-error-message="Unauthorized. Supply a valid bearer token."
      require-expiration-time="true"
      require-signed-tokens="true"
      clock-skew="60"
      output-token-variable-name="jwt">

    <openid-config url="https://login.microsoftonline.com/{{tenant-id}}/v2.0/.well-known/openid-configuration" />

    <audiences>
      <audience>{{orders-api-audience}}</audience>
    </audiences>

    <issuers>
      <issuer>https://login.microsoftonline.com/{{tenant-id}}/v2.0</issuer>
    </issuers>
  </validate-jwt>

  <!-- A daemon token MUST carry app roles. No roles claim means either
       the role was never granted, or a delegated token arrived by mistake. -->
  <choose>
    <when condition='@(!((Jwt)context.Variables["jwt"]).Claims.ContainsKey("roles"))'>
      <return-response>
        <set-status code="403" reason="Forbidden" />
        <set-header name="Content-Type" exists-action="override">
          <value>application/json</value>
        </set-header>
        <set-body>{"error":"no_application_role","detail":"Token carries no app role. An administrator must grant one."}</set-body>
      </return-response>
    </when>
  </choose>

  <!-- Attribute every call to a partner in your logs -->
  <set-variable name="callerAppId"
       value='@(((Jwt)context.Variables["jwt"]).Claims.GetValueOrDefault("azp","unknown"))' />
</fragment>

API-level policy · include the fragment

<policies>
  <inbound>
    <base />
    <include-fragment fragment-id="validate-partner-token" />
  </inbound>
</policies>

Operation-level policy · require a specific role on a write

<policies>
  <inbound>
    <base />   <!-- runs the API-level policy, including the fragment -->
    <choose>
      <when condition='@(!((Jwt)context.Variables["jwt"])
             .Claims["roles"].Contains("Orders.ReadWrite"))'>
        <return-response>
          <set-status code="403" reason="Insufficient permission" />
        </return-response>
      </when>
    </choose>
  </inbound>
</policies>

Why output-token-variable-name matters

It parks the parsed token in context.Variables["jwt"] as a Jwt object, so later policies read claims without re-parsing the header. Without it every subsequent check has to call .AsJwt() on the raw header again — which works, but is easy to get wrong when the header is missing.

Note the single-quoted attributes

Every condition above is delimited with 'single quotes', not double. A policy expression is C#, and C# string literals need double quotes — so if you delimit the XML attribute with " you have to escape every inner quote, and the expression becomes genuinely hard to read and review. Single-quoted attributes are perfectly valid XML, APIM accepts them, and the expression stays legible. Worth adopting as a house convention before your policies get long.

Step 8 · Test it end to end

Prove each hop separately. Most integration pain is not knowing which hop failed.

1. Can the client get a token at all? Have the partner run their MSAL call and print the raw token. If this fails, the problem is the certificate or the app registration — your API and APIM are not involved yet.

2. Does the token look right? Paste it into jwt.ms and check four things: iss ends in /v2.0, aud is api://orders-api, a roles array is present with the expected value, and there is no scp claim.

3. Does APIM accept it? Call through the gateway with that token. A 401 here is issuer, audience or signature. A 403 is the roles check.

4. Does the backend receive the call? Check APIM trace and your backend logs. If APIM passed but the backend rejected, your backend is doing its own validation and needs the same audience and issuer configuration.

# Quick smoke test you can run yourself before involving the partner.
# Uses your own signed-in identity, so it proves the API and APIM config
# independently of the certificate.
TOKEN=$(az account get-access-token \
  --resource "api://orders-api" \
  --query accessToken -o tsv)

curl -i "https://api.contoso.com/orders/v1/orders" \
  -H "Authorization: Bearer $TOKEN"

What that smoke test does not prove

Your own token is a user token — it carries scp, not roles. So it will pass validate-jwt and then be rejected by the roles check with 403. That 403 is the correct result and confirms both halves of the fragment are working. Don't "fix" it by relaxing the roles check.

Troubleshooting

Rotation and revocation

A certificate integration that has no rotation plan is an outage with a date on it. Two certificates can be registered on one app at the same time, and that overlap is the whole trick.

1. Partner generates a new key pair, sends the new .cer, keeps serving traffic with the old key.

2. You upload it with --append, so the app now trusts both. Nothing breaks.

3. Partner switches their code to sign with the new key and confirms tokens are still issued.

4. You remove the old certificate. Rotation complete, no downtime, no coordinated cutover.

To revoke a partner immediately, in order of increasing severity:

• Remove the app role assignment — they still get a token, but your policy returns 403. Reversible in one command.

• Delete the certificate from the app registration — they can no longer get a token at all.

• Disable the service principal (accountEnabled: false) — the identity stops working entirely while remaining auditable.

Set the reminder now

Tokens already issued remain valid until exp — typically up to an hour — so revocation is not instant. If you need immediate cut-off, you need short token lifetimes plus a gateway-level block, not an identity change. And put certificate expiry on a calendar with 60 days' notice on both sides: this is the single most common cause of a working partner integration failing.

Questions you will be asked about this

A background service needs to read from Microsoft Graph. Walk me through your design.

Establish whether a user is involved. No user means client credentials with an application permission, or on-behalf-of if a user initiated the work upstream.

Then narrow it. Take the least-privileged Graph permission that does the job, and if it is a broad .All permission, scope it — an application access policy for mailboxes, or a security group filter. State the blast radius out loud: "Mail.Read as an application permission is every mailbox in the tenant, so I'd bound it."

Credential last: managed identity if it runs in Azure, workload identity federation if not, and a Key Vault secret only if neither is possible — with rotation automated, not documented.

What they're testing: whether you reach for the permission that works or the permission that's correct.

Why not just store the client secret in Key Vault?

Because it moves the problem rather than solving it. Reading Key Vault needs a credential, so either you have another secret to protect, or you use a managed identity for that hop — in which case use it for the resource directly and delete the secret.

Managed identities also remove rotation entirely: the platform rotates roughly every 45 days and your code never handles the material. Secrets in a vault still expire, and an expired secret is an outage.

What they're testing: whether you can identify a bootstrap problem.

Design authentication for a multi-tenant SaaS product on Azure.

Multi-tenant app registration in your home tenant; a service principal is created in each customer tenant on consent. Use the v2.0 endpoint, validate tid against your subscriber list on every call, and never treat a valid token as an authorised tenant — token validity and subscription status are separate questions.

Request the minimum scopes so customer admins can consent without a security review stalling your sale; use incremental consent for anything beyond the baseline. Isolate tenant data by tid at the data layer, and decide explicitly between database-per-tenant and shared-with-partition-key.

For consumer-facing identity instead, that's Entra External ID rather than workforce Entra.

What they're testing: whether you've built multi-tenant or only read about it — the tid validation point is the tell.

How do you stop a compromised CI pipeline deploying to production?

The federated credential's subject claim is the control. Pin it to a protected environment with required reviewers, not to a repository or a pull-request trigger — otherwise anyone who can open a PR can obtain the production identity.

Then defence in depth: a separate federated credential and a separate subscription per environment, the deployment identity scoped to deploy rather than to administer, and branch protection with required reviews as the actual human gate. Check the token Entra issues actually carries the identity you expect, rather than assuming the federation mapped the way you intended.

What they're testing: whether you know that federation moves the trust boundary rather than removing it.

A partner needs to call our API. They can't use OAuth. What do you do?

Terminate their credential at the gateway and don't let it near the backend. Mutual TLS into API Management, validated with validate-client-certificate pinned on issuer and subject rather than thumbprint so their renewal doesn't break us. Then APIM uses its own managed identity to get a token for the backend, so the backend trusts exactly one issuer and one audience and knows nothing about partners.

Flag what mTLS does not give you: it authenticates the channel, not the request. Per-request authorisation still has to come from somewhere — a subject-to-permission mapping in policy, or a claim the gateway injects and the backend trusts only because the network path guarantees it.

And name the operational trap: APIM won't receive a certificate at all unless negotiateClientCertificate is set on the hostname, which produces a policy that looks right and 403s everything.

What they're testing: whether you can design for a constraint you can't change, and whether you volunteer the limitations of your own answer.

Certificate or client secret for a service-to-service call?

Neither, if the caller runs in Azure — that's a managed identity, and the question is only live when it can't be. Then: certificate, because the secret is bearer material and the certificate is proof of possession. The private key never crosses the wire; the signed assertion is single-use, audience-bound and valid for minutes.

The detail that shows you've operated it is sendX5C: true and subject name / issuer authentication — Entra trusts any certificate with that subject and issuer, so renewal is transparent and old and new overlap. Thumbprint-bound certificates just relocate the expiry outage.

What they're testing: whether "use a certificate" is a slogan or something you've actually rotated in production.

This is the last post in the Entra ID Authentication: A Field Guide series. The earlier posts cover certificate authentication, token validation, OAuth grant types, secretless patterns and API Management policy.

A partner sends you a token. It is signed correctly, the audience is right, it has not expired — and API Management returns 401 with nothing useful in the message.

Nine times out of ten this is the v1/v2 issuer mismatch, and it is entirely invisible unless you know to look for it. This post covers the validate-jwt policy properly, how to enforce app roles per operation, client certificate validation for callers who cannot do OAuth, and the two-hop pattern that keeps partner credentials away from your backend.

Validating that token in API Management

The token arrives at your gateway. validate-jwt is where it gets checked — before any request reaches your backend, and without a line of code in the API itself.

Inbound policy — app-only (daemon) caller

<policies>
  <inbound>
    <base />
    <validate-jwt header-name="Authorization"
                  failed-validation-httpcode="401"
                  failed-validation-error-message="Unauthorized"
                  require-expiration-time="true"
                  require-signed-tokens="true"
                  clock-skew="60">

      <!-- Discovery doc means JWKS key rotation is handled for you -->
      <openid-config url="https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration" />

      <audiences>
        <audience>api://orders-api</audience>
      </audiences>

      <issuers>
        <issuer>https://login.microsoftonline.com/{tenantId}/v2.0</issuer>
      </issuers>

      <!-- App-only tokens carry "roles". Delegated tokens carry "scp". -->
      <required-claims>
        <claim name="roles" match="any">
          <value>Orders.Read</value>
          <value>Orders.ReadWrite</value>
        </claim>
      </required-claims>
    </validate-jwt>
  </inbound>
</policies>

The v1 / v2 issuer mismatch

The single most common cause of a working token being rejected by APIM. If the app registration's accessTokenAcceptedVersion is null or 1, Entra issues v1 tokens whose issuer is https://sts.windows.net/{tenantId}/ — not the login.microsoftonline.com/.../v2.0 value you configured. Signature and audience both validate; the issuer doesn't, and the error message won't tell you why. Either set the manifest to version 2, or list both issuers. Being able to diagnose this from a 401 is a strong practical signal.

To enforce different permissions per operation, scope the check rather than repeating the whole policy — inbound policies compose from API level down to operation level:

<!-- Operation-level policy on DELETE /orders/{id} -->
<inbound>
  <base />   <!-- inherits the API-level validate-jwt above -->
  <choose>
    <when condition='@(!context.Request.Headers
        .GetValueOrDefault("Authorization","")
        .AsJwt().Claims.GetValueOrDefault("roles","")
        .Contains("Orders.ReadWrite"))'>
      <return-response>
        <set-status code="403" reason="Insufficient permission" />
      </return-response>
    </when>
  </choose>
</inbound>

Note the single-quoted attribute. A policy expression is C#, and C# string literals need double quotes — so if you delimit the XML attribute with " you have to escape every inner quote as ", which makes a policy genuinely hard to review. Single-quoted attributes are valid XML, APIM accepts them, and the expression stays legible.

Client certificates and mTLS at the gateway

Some callers can't do OAuth at all — a partner's legacy middleware, a payment network, an on-premises scheduler. Mutual TLS authenticates the channel instead of carrying a token, and APIM validates the presented certificate declaratively.

Declarative validation — preferred

<validate-client-certificate
    validate-revocation="true"
    validate-trust="true"
    validate-not-before="true"
    validate-not-after="true"
    ignore-error="false">
  <identities>
    <!-- Pins to issuer + subject, so renewal does not break the integration -->
    <identity
       issuer-subject="CN=Contoso Issuing CA 02, O=Contoso, C=GB"
       subject="CN=partner-gateway.acme-logistics.com, O=Acme Logistics" />
  </identities>
</validate-client-certificate>

The semantics are worth stating precisely, because they're easy to describe wrongly: the certificate must satisfy every top-level attribute and match all the attributes of at least one <identity>. Multiple identities are an OR across partners; attributes within one identity are an AND.

Expression-based equivalent — for logic the policy can't express

<choose>
  <when condition='@(context.Request.Certificate == null
        || !context.Request.Certificate.Verify()
        || context.Request.Certificate.Issuer != "CN=Contoso Issuing CA 02")'>
    <return-response>
      <set-status code="403" reason="Invalid client certificate" />
    </return-response>
  </when>
</choose>

Two operational gotchas

APIM will not receive a certificate unless you ask for one. On the Consumption tier set Request client certificate in the gateway settings; on other tiers set negotiateClientCertificate on the custom hostname. Without it, context.Request.Certificate is always null and every request 403s while the policy looks correct.

Never pin a thumbprint for a partner integration. It works until their certificate renews, then it fails outside your change control and inside their maintenance window. Pin issuer plus subject, and if you must pin a thumbprint, pin two so rollover has an overlap.

The two-hop gateway pattern

This is the composition worth being able to draw on a whiteboard: the caller's credential is terminated at the gateway, and the gateway uses its own identity to reach the backend. Two independent trust decisions, neither one able to compromise the other.

The partner's credential never reaches the backend. Revoking the partner changes one policy; the backend's trust configuration is untouched and knows only about API Management.

Hop 1 and hop 2 in one policy

<inbound>
  <base />

  <!-- HOP 1: the caller is authenticated here -->
  <validate-client-certificate validate-trust="true" validate-revocation="true">
    <identities>
      <identity issuer-subject="CN=Contoso Issuing CA 02, O=Contoso, C=GB"
                subject="CN=partner-gateway.acme-logistics.com" />
    </identities>
  </validate-client-certificate>

  <!-- HOP 2: APIM's managed identity fetches a token for the backend -->
  <authentication-managed-identity
      resource="api://orders-api"
      output-token-variable-name="backend-token"
      ignore-error="false" />

  <set-header name="Authorization" exists-action="override">
    <value>@("Bearer " + (string)context.Variables["backend-token"])</value>
  </set-header>

  <!-- Carry the caller's identity forward for audit, as a claim not a credential -->
  <set-header name="X-Caller-Subject" exists-action="override">
    <value>@(context.Request.Certificate?.Subject ?? "unknown")</value>
  </set-header>

  <set-backend-service base-url="https://orders-internal.contoso.net" />
</inbound>

The backend accepts exactly one issuer and one audience — itself, from your tenant — so it needs no knowledge of partners, certificates or their renewal cycles.

Say the caveat yourself

X-Caller-Subject is a header the backend must trust only because the network path guarantees it came from APIM — private endpoint, VNet integration, or a backend that validates the gateway's token audience. If the backend is reachable directly, that header is attacker-controlled. Volunteering this limitation is exactly the kind of thing that distinguishes an architect from someone reading a tutorial.

If you take one thing

Check requestedAccessTokenVersion on your API's app registration. If it is null or 1, Entra issues tokens whose issuer is https://sts.windows.net/{tenantId}/ — not the login.microsoftonline.com/.../v2.0 value you configured in your policy. Signature and audience both validate. The issuer does not. The error tells you nothing.

Set it to 2, or list both issuers, and you will never lose that afternoon again.

"We keep the client secret in Key Vault" is a very common answer to a question it does not actually address.

Reading Key Vault needs a credential. So either you have another secret to protect, or you use a managed identity for that hop — in which case use it for the resource directly and delete the secret entirely. It is a bootstrap problem, and recognising it is the difference between moving a credential and eliminating one.

This post covers managed identities, workload identity federation for callers outside Azure, and a credential strength ladder you can reason down when asked how two services should authenticate.

Managed identities: the pattern to default to

A managed identity is a service principal whose credential Azure provisions, stores in the platform and rotates roughly every 45 days without telling you. Your code never sees it. This is the single highest-leverage security pattern in Azure, and "why would you use a managed identity over a client secret in Key Vault" is an extremely common interview question.

The answer is the bootstrap problem. A secret in Key Vault still needs a credential to read Key Vault. Either you've moved the problem one hop, or you use a managed identity for that hop — in which case you may as well use it for everything.

User-assigned identities solve a real deployment ordering problem: you can grant RBAC and Key Vault access before the compute exists, so an infrastructure pipeline doesn't have to run a second privileged pass after deploy. That is usually the deciding factor in IaC-heavy estates, not the security posture — both are equally secretless.

Getting a token by hand

SSH onto the VM, or open the Kudu console on an App Service, and ask the local endpoint:

# On an Azure VM — IMDS. Note the mandatory Metadata header.
curl -s -H "Metadata: true" \
  "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://vault.azure.net"

# On App Service / Functions / Container Apps — injected env vars instead
curl -s -H "X-IDENTITY-HEADER: $IDENTITY_HEADER" \
  "$IDENTITY_ENDPOINT?api-version=2019-08-01&resource=https://vault.azure.net"

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs…",
  "expires_on":   "1789016245",
  "resource":     "https://vault.azure.net",
  "token_type":   "Bearer"
}

No credential was supplied. The platform recognised the caller by where the request came from. That is the whole mechanism — and it is why a managed identity cannot be used from outside Azure.

In code — never call that URL yourself

// Walks a chain of credential sources: managed identity in Azure,
// your az login locally. Same code in both places.
var client = new SecretClient(
    new Uri("https://kv-platform.vault.azure.net/"),
    new DefaultAzureCredential());

KeyVaultSecret secret = await client.GetSecretAsync("orders-db-connection");

Workload identity federation

Managed identities only work for workloads running in Azure. Workload identity federation extends the same secretless model to anything that can present an OIDC token — GitHub Actions, GitLab, Kubernetes service accounts, another cloud.

You add a federated credential to an app registration or user-assigned managed identity, declaring the issuer you trust and the exact subject you'll accept. Entra then trades a token from that issuer for one of its own.

The subject is the security boundary

A subject of repo:contoso/platform:ref:refs/heads/main is safe. A subject matching repo:contoso/platform:pull_request means anyone who can open a PR against that repo can obtain your production credential. Pin to an environment with required reviewers, or to a protected branch — and say so unprompted in an interview, because that is the trust boundary the whole pattern hangs on.

1 · Register the trust, once

az identity federated-credential create \
  --name github-prod \
  --identity-name mi-deploy \
  --resource-group rg-platform \
  --issuer "https://token.actions.githubusercontent.com" \
  --subject "repo:contoso/platform:environment:production" \
  --audiences "api://AzureADTokenExchange"

2 · The workflow

permissions:
  id-token: write        # without this, no OIDC token is minted at all
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production   # must match the subject above
    steps:
      - uses: azure/login@v2
        with:
          client-id:       ${{ vars.AZURE_CLIENT_ID }}
          tenant-id:       ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
          # note: vars, not secrets. None of these are sensitive.

      - run: az webapp deploy -g rg-orders -n app-orders --src-path ./drop.zip

No AZURE_CREDENTIALS secret, nothing to rotate, nothing to leak. GitHub mints a short-lived OIDC token describing the run; Entra exchanges it only if issuer and subject match what you registered.

3 · What the subject claim actually looks like

// Safe — the environment gate requires a reviewer
"repo:contoso/platform:environment:production"

// Safe — a protected branch
"repo:contoso/platform:ref:refs/heads/main"

// DANGEROUS — anyone who can open a pull request gets production
"repo:contoso/platform:pull_request"

The subject string is the entire security boundary. There is no secret to steal, so this one line is what an attacker has to work with — which makes reviewing it the highest-value thing you do in this pattern.

Choosing a service-to-service pattern

The credential strength ladder

When you're asked "how should this service authenticate", this is the order to reason down. Take the highest rung the constraints allow, and be able to say why you couldn't take a higher one.

How to deploy this in an interview

When asked how two services should authenticate, don't lead with a mechanism. Ask one question — "is the caller running inside Azure?" — and then walk the ladder out loud. It demonstrates a decision procedure rather than a memorised answer, and it gives the panel somewhere to push, which is what they're trying to do.

Anti-patterns

Where to land

Inside Azure, it is a managed identity and there is no credential to steal. Outside, but able to present an OIDC token, it is workload identity federation. Only below those does a certificate become the right answer, and only below that a secret.

If you take one thing from this: "the secret is in Key Vault" is not an answer to "how does this service authenticate". It is the same question, one hop further down.

Five OAuth flows matter in Azure and two are actively harmful. Which ones you reach for says a lot about whether you learned OAuth in 2015 and stopped.

This post walks the live flows as raw HTTP so you can see what actually differs, explains why PKCE protects a public client that has no secret to protect it, and covers on-behalf-of — the Entra-specific flow for when your API must call a downstream API as the original user.

OAuth 2.0 grant types, and which are dead

Five flows matter and two are actively harmful. Interviewers ask this because it separates people who learned OAuth in 2015 from people who kept up.

The reason implicit died is worth being able to explain: it existed because browsers couldn't do cross-origin POST to the token endpoint before CORS was widely supported. CORS solved that, so a SPA can now do a proper code exchange. PKCE then closes the remaining gap — a public client can't keep a secret, so the authorization code alone is stealable.

How PKCE actually protects a public client

PKCE — Proof Key for Code Exchange — solves one specific problem: the authorization code travels back through the browser, where it can be intercepted, and a public client has no secret with which to prove it should be the one redeeming it.

There is no certificate and no key pair in PKCE, and nothing is registered in advance. The client invents a secret itself, fresh for every sign-in attempt. That is what makes it work for apps that cannot hold a credential at all.

Step 1 · the client invents a secret

High-entropy random string, 43–128 characters. Generated in memory, registered with nobody, discarded seconds later.

code_verifier  = j4ANsyTHtPZktY38c1Q2x8J4DV-KpD_VeIzI501OCL2QZDpT9Wx0_Q

Step 2 · it hashes it

code_challenge = BASE64URL( SHA256( code_verifier ) )
               = 1XisoZOMe5ysmE-v8xegx-oFJqIc26maivy_s7QWxww

Reproduce it yourself — the values above are real:

python -c "import hashlib,base64; v=b'j4ANsyTHtPZktY38c1Q2x8J4DV-KpD_VeIzI501OCL2QZDpT9Wx0_Q'; \
print(base64.urlsafe_b64encode(hashlib.sha256(v).digest()).rstrip(b'=').decode())"

Step 3 · the hash crosses the dangerous channel

The /authorize call travels through the browser — address bar, history, redirects, possibly a malicious app registered for the same URI scheme. So only the hash goes:

GET /authorize?…&code_challenge=1XisoZOMe5ysmE-v8xegx-oFJqIc26maivy_s7QWxww&code_challenge_method=S256

Entra writes that challenge down next to the authorization code it is about to issue. It validates nothing yet — it has nothing to compare against. This step is pure storage.

Step 4 · the verifier crosses the safe channel

The /token call is a direct back-channel HTTPS POST. No browser, no redirect, no intermediary. Now the original is sent:

POST /token
grant_type=authorization_code&code=0.AXoAv4j5…&code_verifier=j4ANsyTHtPZktY38c1Q2x8J4DV-KpD_VeIzI501OCL2QZDpT9Wx0_Q

Step 5 · the server checks

Entra computes SHA256 of the verifier it just received and compares it to the challenge stored in step 3. Match, and it issues tokens. No match, or no verifier at all, and the code is rejected and burned.

Why interception fails

The attacker has the code, stolen from the redirect. To redeem it they need the verifier. What they have instead is the challenge — a SHA-256 hash — and reversing that means inverting SHA-256.

The asymmetry is deliberate: the hash crosses the interceptable channel, the preimage crosses the direct one. Verification costs one hash operation; forgery requires breaking the hash function.

Three different cryptographic mechanisms, one flow

This is where PKCE is most often misunderstood. There are three separate things happening in an OAuth exchange, and they answer three different questions. Only one of them involves a certificate.

PKCE does not authenticate the client. It only binds the authorization code to whoever began the flow. A public client — a SPA, a mobile app — remains fundamentally unauthenticated afterwards, because anything shipped to a user's device can be read by that user.

Which is why the two compose rather than compete: a confidential client uses PKCE and a secret or certificate. PKCE stops code interception; the credential proves app identity. It also explains why PKCE never appears in the client credentials flow — no browser, no redirect, no authorization code, so nothing to intercept and nothing to bind.

The on-behalf-of flow

A user calls your API, and your API must call Microsoft Graph as that user. You cannot reuse the incoming token — its aud is your API, not Graph. On-behalf-of exchanges one for the other while preserving user context.

Your API received token A. It needs token B for Graph. This is the exchange:

POST /72f988bf-…/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=a1b2c3d4-5e6f-4711-8a9b-0c1d2e3f4a5b
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJQUzI1NiIs…
&assertion=eyJ0eXAiOiJKV1QiLCJhbGci…
&scope=https://graph.microsoft.com/Mail.Read
&requested_token_use=on_behalf_of

Two credentials in one request. Your API authenticates itself with the client_assertion, and passes the user's token as assertion. Entra returns a token for Graph that still carries the user's oid.

In MSAL it is one call:

// incomingToken is the raw bearer string your API received
var result = await app
    .AcquireTokenOnBehalfOf(
        new[] { "https://graph.microsoft.com/Mail.Read" },
        new UserAssertion(incomingToken))
    .ExecuteAsync();

What the alternative would cost you

If your API used client credentials instead, Graph would apply the API's tenant-wide Mail.Read application permission — every mailbox in the tenant — and the audit log would record your API rather than the person who asked. Reach for on-behalf-of whenever the downstream authorisation decision should depend on who asked.

Rules of thumb

A user is present: authorization code with PKCE. No user: client credentials with an app role. Your API needs to call something else on the user's behalf: on-behalf-of, not client credentials, or you lose both the permission ceiling and the audit trail.

And the tell for reading someone else's code: .default and roles mean machine. Named scopes and scp mean user.

Here is a bug I have seen in production more than once. An API validates the signature on every incoming JWT, against the correct tenant, using a properly cached JWKS. It looks rigorous. It is wide open.

Signature validation proves the token was not forged. It says nothing about who the token was for. Miss the aud check and any token your tenant issued — including one a user obtained for a completely different application — sails straight through.

This post covers what is actually inside an Entra token, the claims that carry the authorisation decision, and the two distinctions that cause most of the confusion: app registration versus service principal, and delegated versus application permissions.

Tokens and claims

Three words get used interchangeably and shouldn't be. Authentication establishes who a principal is. Authorisation decides what that principal may do. Identity federation is the act of one system trusting another system's authentication, so the principal doesn't need a second set of credentials.

Modern cloud auth runs on three protocol families, and knowing which does what is table stakes:

These are the claims that matter:

The identity objects, and why there are so many

The app registration / service principal split is the distinction that confuses everyone. Ask Entra for both and you get two different ids:

# The application object — the global definition
az ad app show --id api://orders-api \
  --query "{appId:appId, objectId:id, uris:identifierUris}"

{
  "appId":    "a1b2c3d4-5e6f-4711-8a9b-0c1d2e3f4a5b",   // same in every tenant
  "objectId": "9e7c4a18-3b62-4f09-85d1-6c2a7e0b4d53",   // the app registration
  "uris":     ["api://orders-api"]
}

# The service principal — the local instance that permissions attach to
az ad sp show --id a1b2c3d4-5e6f-4711-8a9b-0c1d2e3f4a5b \
  --query "{appId:appId, objectId:id}"

{
  "appId":    "a1b2c3d4-5e6f-4711-8a9b-0c1d2e3f4a5b",   // unchanged
  "objectId": "4d8f1e27-9a03-4c65-b7e2-1f5c8d3a6b90"    // DIFFERENT — the SP
}

Same appId, two different object ids. Role assignments, app role grants and sign-in logs all reference the service principal id, not the app registration id. Passing the wrong one is the cause of most "resource not found" errors when scripting Graph.

Think of the registration as a class and the service principal as an instance. In a single-tenant line-of-business app you'll have one of each and never notice. In a multi-tenant SaaS app, you have one registration in your home tenant and a service principal in every customer tenant that consented — and permissions, Conditional Access and sign-in logs all attach to the service principal, not the registration.

Delegated versus application permissions

This is the distinction Entra interviews live on.

Delegated (scp)

The app acts on behalf of a signed-in user. There is always a user in the picture.

Effective permission = intersection of what the app was granted and what the user is actually allowed to do. An app with Files.ReadWrite.All delegated still can't touch a file the user can't reach.

Consent can come from the user, or require an admin depending on the scope's sensitivity.

Application (roles)

The app acts as itself. No user, no user context, no intersection.

Effective permission = exactly what was granted, tenant-wide. Files.ReadWrite.All here means every file in the tenant.

Always requires admin consent. This is where over-privileged daemons quietly become the largest risk in an estate.

Where this goes wrong

A background job needs to read one mailbox. The quick fix is Mail.Read as an application permission, which grants read on every mailbox in the tenant. The correct fix is application permission plus an application access policy scoping it to a named mailbox or group. If you can articulate this, you're demonstrating that you think about blast radius rather than getting the call to work.

Both of the tokens below are valid for api://orders-api. Your validation logic must treat them differently.

Delegated — a user is behind the call

{
  "aud": "api://orders-api",
  "azp": "a1b2c3d4-5e6f-4711-8a9b-0c1d2e3f4a5b",
  "azpacr": "0",
  "name": "Priya Raman",
  "oid": "3c9e1b74-2a5f-4d86-b0c7-9e4f1a2d8b63",
  "preferred_username": "priya.raman@contoso.com",
  "scp": "Orders.Read Orders.Write",
  "sub": "k9Hx2vQpL7nR4tYw",
  "tid": "72f988bf-86f1-41af-91ab-2d7cd011db47"
}

scp is a space-delimited string. There is a user: name, preferred_username and a user oid. Effective permission is the intersection of these scopes and what Priya herself can reach.

Application — the app acts as itself

{
  "aud": "api://orders-api",
  "azp": "a1b2c3d4-5e6f-4711-8a9b-0c1d2e3f4a5b",
  "azpacr": "2",
  "roles": ["Orders.Read"],
  "oid": "7f3d9c21-64b8-4e0a-9d31-5a8e2b7c1f04",
  "sub": "7f3d9c21-64b8-4e0a-9d31-5a8e2b7c1f04",
  "tid": "72f988bf-86f1-41af-91ab-2d7cd011db47"
}

roles is an array. No name, no preferred_username, and oid equals sub — both are the service principal, because there is no user. Effective permission is exactly Orders.Read, tenant-wide.

Practical consequence: code that reads scp will silently authorise nothing when a daemon calls, and code that reads roles will silently authorise nothing when a user calls. Handle both explicitly, or reject the shape you do not expect.

Conditional Access as the policy decision point

Conditional Access is where Entra stops being a directory and becomes a policy engine. Every sign-in is evaluated against policies shaped as signals → decision → session control.

• Signals — user or group, target application, device state (compliant, hybrid-joined), client app type, location or named network, real-time sign-in risk and user risk from Identity Protection.

• Decisions — block, or grant subject to MFA, compliant device, approved client app, app protection policy, terms of use.

• Session controls — sign-in frequency, persistent browser, app-enforced restrictions, Defender for Cloud Apps proxying, token protection.

Two things to be able to say about it. First, CA policies are evaluated after first-factor authentication — they gate token issuance, not credential verification, which is why they can't protect legacy protocols that don't do modern auth. Second, block always wins over grant, and a policy with no assignment exclusions will eventually lock you out, which is exactly what break-glass accounts exist for.

Hybrid identity

Most enterprises still have Active Directory, and how you bridge it to Entra is a standard design question.

• Password hash sync — a hash of the password hash syncs to Entra. Simplest, most resilient, and cloud sign-in keeps working when the data centre doesn't. The default recommendation.

• Pass-through authentication — validation happens on-premises via lightweight agents. No password material in the cloud, but cloud sign-in now depends on on-premises availability.

• Federation with AD FS — full control and support for exotic requirements, at the cost of running highly-available infrastructure on the critical path of every sign-in. Being migrated away from almost everywhere.

The architect's point is that the first two keep authentication working when on-premises infrastructure fails, and that availability is usually worth more than the control federation buys.

What to take away

Validate the signature, then iss, then aud, on every request. Point your validator at the OIDC discovery document rather than pinning a key, so Microsoft's rotation is invisible to you. And key your user records off oid plus tid — never email or UPN, both of which change when people get married or renamed.

If you only change one thing after reading this: check that your API rejects a token whose aud is some other application in your own tenant. A surprising number do not.

If the client generates its own credential, what stops anyone else doing the same?

That is the question certificate authentication always comes down to, and most explanations skip straight past it into openssl flags. This post answers it directly, with a diagram of what happens once at setup, a diagram of what happens on every call, and a short sequence of commands you can run yourself to watch a forgery attempt fail.

It is written from the position of the API owner — you own the API, a partner service needs to call it, there is no user involved, and they will authenticate with a certificate.

How a confidential client proves who it is

PKCE leaves a gap. It binds the authorization code to whoever started the flow, but it says nothing about which application is calling — and for service-to-service traffic there is no user, no browser and no authorization code at all. Something else has to establish identity.

That something is a credential the app can prove it holds. The strongest form available to a caller outside Azure is a certificate, and it raises the question that certificate authentication always comes down to: if the client generates its own credential, what stops anyone else doing the same?

The answer in three sentences

The client generates a key pair — two mathematically linked files. One can create signatures; the other can only check them, never create them.

The client keeps the creating half forever. You receive the checking half and upload it to Entra in advance. Later the client signs something, and Entra verifies it using the half you gave it — without ever having seen the private key.

Anyone can build the same message. Only the holder of the private key can produce a signature that verifies against the certificate on your app registration.

Phase 1 · Setup — happens once, before anything runs

Nothing secret moves in either direction. The partner creates both halves; only the verifying half travels. Entra records it as usage: "Verify" — the platform itself stating this key can check signatures but never produce them.

The thing people get backwards

You do not generate the pair and send the partner a private key. If you did, two parties would hold the signing key, and a fraudulent call in your logs could no longer be attributed to either of them. That destroys the one property you adopted certificates for — and leaves you with a client secret that is harder to rotate.

Phase 2 · Runtime — happens on every token request

Step 2 is the only step an impostor cannot perform. Everything else — writing the JSON, knowing the client_id, assembling the JWT, posting it — is public knowledge. The signature is the whole of the security, and producing one requires the private key that never left the partner's estate. Steps 1–3 involve no network call at all: the assertion is not issued by anyone, it is manufactured locally.

Why an impostor fails, concretely

Suppose an attacker finds the client_id in a config file and tries the same request.

What each party ends up holding

Contrast a client secret, where that last column would read yes on every row. That is the entire reason to prefer a certificate.

The handover, in both directions

If your onboarding process ever requires you to securely transmit something to the partner, you have drifted back to shared-secret territory and lost the benefit. The assertion is taken apart claim by claim further down this post, and post 6 in this series has the az commands for registering all of it.

Why a certificate beats a client secret

A client secret is bearer material. Whoever holds the string is the application — there is no way for Entra to tell the legitimate service from someone who found the secret in a config file, a pipeline log, or an exception dump. A certificate credential changes the proof from "I know a string" to "I can sign with a key I hold".

Where this genuinely applies

Certificate credentials are the right answer when the calling workload cannot use a managed identity — a service running on-premises, in another cloud, or in a third party's estate that needs to call your Entra-protected API. Inside Azure, a managed identity is still better, because it removes the credential entirely rather than improving it. Say that distinction out loud; it shows you're picking the pattern for the constraint rather than reciting the strongest-sounding option.

The client assertion, claim by claim

Certificate-based client credentials work by private_key_jwt: the client builds a short-lived JWT, signs it with the certificate's private key, and presents that instead of a secret. Entra verifies the signature against the public key registered on the app.

Assertion header — identifies which registered certificate signed this

{
  "alg": "PS256",
  "typ": "JWT",
  "x5t#S256": "kg3W1Hh9Nn_Yp2QqR0sT..."
}

Assertion payload

{
  "aud": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
  "iss": "{clientId}",
  "sub": "{clientId}",
  "jti": "6f1b...-unique",
  "iat": 1789012345,
  "nbf": 1789012345,
  "exp": 1789012645
}

The jti is a single-use id that blocks replay, and exp should be five to ten minutes at most.

Token request

POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={clientId}
&scope=api%3A%2F%2Forders-api%2F.default
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion={the signed JWT above}

Three details that trip people up

The aud is the token endpoint, not the tenant's v2.0 issuer URL. Getting this wrong yields an unhelpful AADSTS700027.

.default is not a scope you invented. In the client credentials flow you cannot request individual scopes — you request {resource}/.default and receive every application permission already consented for that resource. Granularity comes from what an admin consented to, not from the request.

Use x5t#S256 with PS256 for new work. The older x5t header carried a SHA-1 thumbprint with RS256; it still works, but SHA-1 is not a thing to put in a design document in 2026.

Doing it in .NET — and not hand-rolling it

You almost never build that assertion yourself. MSAL constructs and signs it for you:

// Pull the cert from Key Vault using the host's managed identity.
// Nothing secret is ever in appsettings or an environment variable.
var certClient = new CertificateClient(
    new Uri("https://kv-platform.vault.azure.net/"),
    new DefaultAzureCredential());

X509Certificate2 cert = (await certClient
    .DownloadCertificateAsync("orders-client-auth")).Value;

var app = ConfidentialClientApplicationBuilder
    .Create(clientId)
    .WithAuthority($"https://login.microsoftonline.com/{tenantId}")
    .WithCertificate(cert, sendX5C: true)
    .Build();

// MSAL caches in memory and only round-trips Entra when the token is near expiry.
AuthenticationResult result = await app
    .AcquireTokenForClient(new[] { "api://orders-api/.default" })
    .ExecuteAsync();

httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", result.AccessToken);

sendX5C: true is the line worth knowing

It sends the full public certificate with the assertion, which enables subject name / issuer authentication. Entra then trusts any certificate with the same subject and issuer rather than one specific thumbprint — so you can roll to a renewed certificate without touching the app registration, and old and new coexist during rollout. Without it, every renewal is a coordinated change across the registration and every deployed instance. This is the difference between a credential rotation that is routine and one that causes an outage at 2am.

The one-sentence version

The client generates a key pair, keeps the half that can sign, and sends you the half that can only verify. You upload that to their app registration. Entra then validates signatures made by a key it has never seen — and neither you nor Microsoft can impersonate the partner, because a public certificate cannot produce a signature.

If your onboarding process ever requires you to securely transmit something to the partner, you have drifted back to shared-secret territory and lost the benefit.