Fixing Expired Credentials

This is the chapter the course was built for. A client's users can't reach your system, the integration's validation fails, and the suspicion is that something expired. You now have all the pieces: what the credentials are (Chapters 2 and 4), where to find them (Chapter 5), what else could be blocking sign-in (Chapter 6), and where the evidence lives (Chapter 7). Here they are joined into one repeatable procedure: stop, preserve, decode, confirm, fix in the safe order, prove it, tell the client.

Step 0: Stop and Preserve

Before anyone changes anything:

1. Save the evidence (Chapter 7): the failed sign-in entry's fields, the correlation ID, the time and time zone, and a download of the filtered log. On the Free edition the sign-in and audit logs go back only seven days.
2. Note the exact error that your system or the client saw, as text, including every identifier you can find (redacted when it leaves your team).
3. Don't "try a new secret" blindly. A rushed new secret that is pasted wrongly creates a second problem on top of the first and muddies the logs.

Step 1: Decode the Message

Error text from Entra has a predictable shape (Chapter 3): a short error name, a longer error_description that begins with an AADSTS number, then a timestamp, a trace ID and a correlation ID. Here is a fictional, redacted example of an app-only (client credentials) failure:

Different credentials fail with different numbers. Match the number to the right kind of expiry before touching anything:

Step 2: Confirm the Cause in Three Places

Never act on the error alone. Three independent checks, each from an earlier chapter:

1. The log (Chapter 7). The service-principal sign-in entry for the failure: same error code, same application ID, right time.
2. The portal (Chapter 5). Entra ID > App registrations > <app> > Certificates & secrets: which credentials exist, and their expiry dates, against today's date. For SAML: Enterprise apps > <app> > Single sign-on > SAML Certificates.
3. The audit log (Chapter 7). Filter the application and look for "Update application – Certificates and secrets management" or certificate activities in the days before the failure. Did anyone rotate, delete or replace a credential?

The three together usually produce one of four stories:

Step 3: Fix in the Safe Order

The principle is the same for every credential type, and it comes straight from Microsoft's own renewal guidance: add the new credential alongside the old one, update the application, prove the new one works, and only then remove the old one. Four verbs: create, install, prove, remove. Reversing "prove" and "remove" is the commonest self-inflicted outage.

Fix A: Client secret (create, install, prove, remove)

1. Create. The app registration's owner or an Application Administrator opens Entra ID > App registrations > <app> > Certificates & secrets > Client secrets > New client secret. They add a description (a good one: the system and the date, such as "AcmeReports prod 2026-10"), choose an expiry, and select Add. Microsoft limits the lifetime to 24 months or less and recommends less than 12.
2. Copy the Value, not the Secret ID. Microsoft is explicit that the secret Value is shown only on this page and never again after leaving it. If it's lost, create another. Pasting the Secret ID in place of the value is a well-known cause of 7000215.
3. Transfer it safely. The value goes straight into your product's credential field (or your secrets store) by the person who holds it. Never email it, paste it into a ticket or chat, or screenshot it. If a handover is unavoidable, use a secure channel your organisation approves.
4. Install. Update the credential in your system (your product's connection settings, or the secrets store it reads), then restart or reload anything that caches it.
5. Prove. Trigger the connection (a validation, a job run or a test sign-in) and open the service-principal sign-in log: it should now show Success. Microsoft's guidance is to use the sign-in logs to validate that the Key ID of the credential matches the one just added; check the sign-in details for the credential identifier, and if it doesn't show in the tenant you are using, a clean Success after the change is the practical proof.
6. Remove. Only after proving it (and after any other system that shares the registration has been updated), delete the old credential. Wait for a safe window, such as a full business cycle for overnight jobs.

Fix B: Certificate credential

1. Create/obtain a new certificate and key pair. Microsoft recommends a certificate over a client secret for production, and a certificate from a well-known certificate authority managed in a vault such as Azure Key Vault, rather than a self-signed one (self-signed is acceptable for testing).
2. Upload the public part under Certificates & secrets > Certificates > Upload certificate (file types .cer, .pem, .crt), then select Add. The private key never goes into Entra.
3. Record the thumbprint Entra shows, and compare it with the certificate your system will sign with. A thumbprint mismatch is the commonest certificate error (50012).
4. Install the new certificate and private key in your system, prove a successful service-principal sign-in, then remove the old certificate.

Fix C: SAML signing certificate

A SAML signing certificate is created by Entra (Chapter 4: three-year default; the date can't be edited after saving, so you create another). Because your system must trust whichever certificate Entra signs with, both sides must change, and the order matters. From Microsoft's certificate-management tutorial, which needs at least Cloud Application Administrator or Application Administrator:

1. Create a new certificate: Enterprise apps > <app> > Single sign-on > SAML Certificates > Edit (pencil) > New Certificate. Choose an expiry (default is three years from today, and you can pick any date up to three years), then Save. It appears with status Inactive.
2. Download it in the format your application expects (Base64 .cer, raw, PEM or federation metadata XML, as your product's setup guide says).
3. Upload it to your system as a trusted signing certificate. If your system supports more than one certificate, add it while the old one still works.
4. Make certificate active (ellipsis on the new row). The new certificate becomes Active and the old one Inactive. From now on Entra signs assertions with the new key.
5. Prove: sign in to your product with a test user. Then remove the old certificate from your system once confirmed.

For a better long-term design, Microsoft's ISV guidance is that your application should read the per-tenant federation metadata URL regularly (at least every 24 hours), accept additional signing certificates, and promote the new one when it's activated. That's the way to stop SAML certificate expiry from needing any human action. Chapter 9 returns to this.

Fix D: Provisioning (SCIM) credential

A SCIM connection has a Tenant URL (your SCIM endpoint) and a way of authenticating to it. Microsoft documents that a request carries an OAuth 2.0 bearer token. Options include a long-lived bearer token entered in the optional Secret Token field (supported for existing and non-gallery apps, not for new apps), an OAuth 2.0 client-credentials grant, or leaving the Secret Token field blank so that Entra sends its own Entra-issued token. Which one applies depends on how your product set it up.

1. Create/issue the new credential on your side (a new bearer token in your product, or a new client secret for the client-credentials option).
2. Install it in the client's tenant: Enterprise apps > <app> > Provisioning, where the client's administrator pastes the new value into Secret Token (or the client ID and secret fields).
3. Prove: select Test Connection. Microsoft says it queries the SCIM endpoint for a user that doesn't exist using a random GUID, and expects HTTP 200 OK with an empty SCIM ListResponse; a failure shows error information. Then confirm in the provisioning log (Chapter 7) that new cycles succeed.
4. If the job was in quarantine, check the provisioning status after the fix and use the provisioning log to confirm that normal operation has resumed (Chapter 2 described quarantine; confirm the current restart behaviour in Microsoft's provisioning pages for the client's setup).

Whichever way your product handles the credentials, "Test Connection" is a useful word to know: it is probably what the client calls "validate the connection". Confirm with the client's administrator which button or page they mean.

Step 4: Prove It Properly

Only then remove the old credential, and record the fix (below).

If It Still Fails

While You Work: What to Tell the Client

Record the Fix

A short, searchable ticket note makes the next occurrence (and Chapter 9's register) far easier:

Hands-On Exercises

All three use fictional organisations and values. Never put real secrets, tokens or tenant details into practice notes.