What Passes Between

Chapter 2 told you what an integration is. This chapter follows what actually travels when it works: what your system sends to Entra, what Entra sends back, and what your system must check before it believes the answer. Once you know the steps, a failure stops being "the integration is broken" and becomes "step four failed, and step four is where the credential is used".

Pattern 1: An OpenID Connect Sign-in, Step by Step

This is the usual "Sign in with Microsoft" flow. Microsoft calls it the OAuth 2.0 authorization code flow combined with OpenID Connect. Here it is as one picture, then in detail:

Step 1: your system sends the browser to Entra

Your system redirects the user to the tenant's /authorize endpoint, with details in the address. For the authorization code flow, Microsoft documents these parameters:

Step 2: Entra signs the user in

This happens entirely inside the client's tenant. Entra shows the sign-in page, checks credentials, applies the tenant's policies (Conditional Access, MFA; Chapter 6), and makes sure the user has consented to the permissions requested in scope. Some permissions are admin-restricted, and a user who can't consent to them gets an error saying so. Nothing in your system is involved in this step, and it is where "it works for most users but not one" problems usually live.

Step 3: Entra sends the browser back with a code

On success Entra redirects to your redirect_uri carrying a code (an authorization code) and your state. Microsoft notes that authorization codes are short-lived and typically expire after about one minute. On failure it sends back error and error_description instead. Your system should check that the returned state matches what it sent.

Step 4: your server redeems the code, and proves who it is

This is the one step where your system speaks to Entra directly, as itself. It POSTs to the tenant's /token endpoint with:

For a web application the credential is required. It can be a client secret, or a certificate credential (the request then carries a client_assertion, a signed token, instead of client_secret). Microsoft says that for best security it recommends certificates. Public clients such as native apps and single-page apps must not use secrets or certificates here.

Step 5: Entra returns tokens

The reply is a block of data (JSON) with these parts, per Microsoft:

Step 6: your system checks the ID token and starts a session

Microsoft says that web apps must validate ID tokens that reach them through the browser (the hybrid flow), and libraries validate them in every case. In outline, your system checks the token's signature against the public keys published in the tenant's OpenID metadata document, and then checks claims such as iss (who issued it and for which tenant), aud (that it was issued for your application), exp (not expired), and nonce (matches what was sent). Libraries do this for you. Entra rotates its signing keys periodically, so a system has to fetch the key set again rather than cache one forever; Microsoft suggests checking for key updates about every 24 hours.

The Tokens, Side by Side

Remember the ID token and access token division from Chapter 1: who are you versus what may you do. Chapter 4 returns to these lifetimes, and the important distinction between a credential expiring (the client secret) and a token expiring.

The claims in an ID token

A claim is a statement the identity provider makes about the user or the token. In an ID token the most useful ones for support are:

Reading an Error From Entra

When a token request fails, Entra returns an error in a standard shape. This is Microsoft's own example (the values are samples):

The error codes at the token step

Pattern 2: What Passes in a SAML Sign-in

SAML follows the same shape with different messages. Your system (the "service provider") sends the browser to Entra with a sign-in request; Entra authenticates the user and sends the browser back to your Reply URL (the Assertion Consumer Service) with a signed SAML token. There is no separate server-to-server step and no client secret: the trust rests on the signing certificate. Your system has Entra's certificate (Chapter 2) and checks the signature on every assertion.

What the SAML token carries, according to Microsoft:

• the subject, also called the name identifier (nameID), which identifies the user; by default Entra puts the user's username (user principal name) there, and if the sign-in request includes a NameIDPolicy with a specific format, Entra honours that format;
• an attribute statement of claims; by default these include the user's email address, first name and last name;
• the issuer and audience (your Identifier / Entity ID), and the signature; and
• group claims, only if configured, subject to the 150-group limit for SAML.

Claims are configured under Entra ID > Enterprise apps > All applications > (the app) > Single sign-on > Attributes & Claims > Edit, as at least a Cloud Application Administrator. The classic SAML failure after a certificate renewal: the client renews or rotates the signing certificate in Entra, but your system still holds the old one, so every signature check fails for every user at once. The other classic one: the nameID is a username but your system expects an email address (or the other way round), so the user is authenticated yet can't be matched to an account.

Pattern 3: What Passes With API Access (Client Credentials)

This is the same step-4 conversation, without any user or browser. Your system asks the token endpoint for a token for itself:

The scope is the resource followed by /.default, meaning "all the application permissions an administrator has granted to this app for that resource". The reply carries no refresh token and no ID token; when the access token expires, the application simply asks again using its own credential. So if the credential has expired, the next request fails and the job stops. This is why background jobs fail at a particular moment, often overnight, with nobody signed in.

Pattern 4: What Passes in Provisioning (SCIM)

Here Entra sends requests to your system. The provisioning service connects to your SCIM 2.0 endpoint, using the credential that was entered in the client's tenant, and uses the SCIM user schema and REST calls to manage users (and groups where supported), over HTTPS with TLS 1.2. Which events cause which calls, according to Microsoft:

Entra runs an initial cycle over everything in scope and then repeated incremental cycles, remembering the ID your system gives each user. It records what it did, and what your system answered, in the provisioning logs. If the connection credential is rejected, most calls fail, the job goes into quarantine (Chapter 2), and your own server logs will show refused calls, not Entra sign-ins. Provisioning has no user, no browser and no tokens to look at: just calls to your system, and your system's answers.

Where Can Each Step Fail?

This table pulls the chapter together. Use it as a first guess; the evidence in Chapter 7 confirms it.

Hands-On Exercises

All three use fictional values. Never practise with real tokens, secrets or tenant details.