Revise MSI v2 token revocation spec to focus on certificate revocation #5498

gladjohn · 2025-09-23T23:37:14Z

Updated the document to reflect changes from 'Short-Lived Credential (SLC)' to 'Certificate' terminology and clarified the handling of certificate revocation scenarios.

Fixes - Spec update

Changes proposed in this request
This pull request updates the documentation for MSI V2 credential revocation, clarifying and expanding the specification to focus on certificate revocation (rather than short-lived credentials) and aligning terminology, flows, error handling, and acceptance tests with current implementation and Azure AD error codes. The changes provide detailed guidance on how MSAL should handle certificate revocation, claims challenges, and telemetry.

Key documentation improvements:

Terminology and Flow Updates:

Changed terminology throughout from "Short-Lived Credential (SLC)" to "certificate," clarifying that the revocation and renewal process is certificate-based. Sequence diagrams and flow descriptions are updated for accuracy. [1] [2]

Error Handling and Remediation:

Added explicit mapping of AADSTS error codes (1000610–1000614) to certificate/attestation failures and detailed required MSAL remediation steps, including bypassing the cache and minting a new certificate.
Provided updated pseudo-code and acceptance tests to reflect these flows, emphasizing auto-remediation and claims challenge handling.

Claims Challenge Handling:

Clarified the process for handling claims challenges: when an application receives a 401 with claims, it must pass the claims to MSAL, which then mints a new certificate and retries the token request with the claims.

Acceptance Tests and Telemetry:

Revised acceptance test scenarios to match the new flows, including auto-remediation, claims challenges, and telemetry validation.
Updated telemetry documentation for MsalMsiCounter to reflect the new tags and expected values for improved diagnostics.

Testing
n/a

Performance impact
n/a

Documentation
n/a

Updated the document to reflect changes from 'Short-Lived Credential (SLC)' to 'Certificate' terminology and clarified the handling of certificate revocation scenarios.

bgavrilMS · 2025-09-24T12:20:39Z

docs/msi_v2/msiv2_revocation_spec.md

@@ -1,46 +1,46 @@
-# Short-Lived Credential (SLC) Revocation Specification
+# Certificate Revocation Specification


The name of the file should also be changed.

bgavrilMS · 2025-09-24T12:21:12Z

docs/msi_v2/slc_revocation_spec.md


 ## Overview

-This document outlines the design and implementation details for short-lived credential (SLC) revocation in MSI V2 scenarios. 
+This document outlines the design and implementation details for **certificate revocation** in MSI V2 scenarios.


Should we have 1 document that discusses all credential revocation ? (cert and token)

bgavrilMS · 2025-09-24T12:22:14Z

docs/msi_v2/slc_revocation_spec.md

-    MSAL ->> IMDS: 2. Request Short-Lived Credential (SLC)
-    IMDS -->> MSAL: 3. Return SLC
-    MSAL ->> eSTS: 4. Exchange SLC for Access Token
+    MSAL ->> IMDS: 2. Request Credential (certificate)


I think it's safe to use "certificate" everywhere. I don't see a use case of another type of credential (jwt).

bgavrilMS · 2025-09-24T12:24:17Z

docs/msi_v2/slc_revocation_spec.md

- MSAL will **relay the response to IMDS as-is**, ensuring support for future suberror codes without requiring modifications.
+1. Call the certificate minting endpoint **`/issuecredential?bypass_cache=true`** to force a **new certificate** (ignore any cached/invalid state).
+2. Replace the current certificate with the newly issued one.
+3. **Retry** the token request with eSTS using the new certificate.


Please specify retry policy. IMO, retry once?

@Robbie-Microsoft keeping this as STS retry

bgavrilMS · 2025-09-24T12:25:44Z

docs/msi_v2/slc_revocation_spec.md

-| **Telemetry Validation**               | Ensure `MsalMsiCounter` correctly logs telemetry tags such as `MsiSource`, `TokenType`, `bypassCache`, and `CredentialOutcome`. | Telemetry records correct values for each token acquisition attempt, including failures. |
+| **Test Case**                                   | **Description**                                                                                         | **Expected Outcome** |
+|-------------------------------------------------|---------------------------------------------------------------------------------------------------------|----------------------|
+| **AADSTS1000610–14 Auto-Remediation**           | eSTS returns 401 `invalid_client` with any of 1000610–1000614.                                          | MSAL calls `/issuecredential?bypass_cache=true`, obtains a new certificate, retries; success or deterministic failure surfaced. |


I would split this into 2 - success after retry / failure after retry to make it clearer.

bgavrilMS

Approved with comments

bgavrilMS · 2025-09-24T12:29:48Z

docs/msi_v2/msiv2_revocation_spec.md

-7. **Platform**  
-   The runtime/OS environment.  
-   - Examples: `"net6.0-linux"`, `"net472-windows"`
+Each time we record `MsalMsiCounter`, include:


At this point in time, I do not feel that the client telemetry is significant. We can add a feature request for this, but I would not prioritize it today.

Is there any server telemetry that we want to capture?

yes, there is server-side telemetry that we send and also we know mTLS was used from ESTS

bgavrilMS · 2025-09-24T12:30:55Z

docs/msi_v2/slc_revocation_spec.md

+
+1. **MsiSource** — `"AppService"`, `"CloudShell"`, `"AzureArc"`, `"ImdsV1"`, `"ImdsV2"`, `"ServiceFabric"`  
+2. **TokenType** — `"Bearer"`, `"POP"`, `"mtls_pop"`  
+3. **bypassCache** — `"true"` / `"false"`  


Will this be captured in the server telemetry? In other words, given a correlation ID, can we identify the call made to the credential endpoint and to the token endpoint?

bgavrilMS · 2025-09-24T12:31:36Z

docs/msi_v2/slc_revocation_spec.md

+3. **bypassCache** — `"true"` / `"false"`  
+4. **CertType** — `"Platform"`, `"inMemory"`, `"UserProvided"`  
+5. **CredentialOutcome** — `Not found` / `Retry Failed` / `Retry Succeeded` / `Success`  
+6. **MsalVersion** — e.g., `"4.61.0"`  


version and platform are included by default in the counter, I think,.

bgavrilMS

Not sure about telemetry. Maybe start with having those values logged. Let's focus more on server telemetry.

Robbie-Microsoft · 2025-09-25T17:37:40Z

docs/msi_v2/msiv2_revocation_spec.md

+    participant eSTS
+
+    Application ->> MSAL: 1. Request Access Token
+    MSAL ->> IMDS: 2. Request Certificate


The CSR metadata request is part of the flow. I think you should add it here.

Robbie-Microsoft · 2025-09-25T17:38:58Z

docs/msi_v2/msiv2_revocation_spec.md

+    participant eSTS
+
+    Application ->> MSAL: 1. Request Access Token
+    MSAL ->> IMDS: 2. Request Certificate


Mention /issuecredential like you do below

Robbie-Microsoft · 2025-09-25T17:40:37Z

docs/msi_v2/msiv2_revocation_spec.md

+    MSAL ->> eSTS: 4. Exchange Certificate for Access Token
+    eSTS -->> MSAL: 5. Response (HTTP 200 / error)
+
+    alt Token Revoked / Attestation invalid


both alts are the same except for 5a and 5b. Do you need to repeat the entire portion of the graph after those sections? Can you just group 5a and 5b together on the graph?

these are two different error conditions

Robbie-Microsoft · 2025-09-25T17:42:09Z

docs/msi_v2/msiv2_revocation_spec.md

+    participant Application
+    participant MSAL
+    participant IMDS
+    participant eSTS


Why is there a "IMDS/eSTS" section? Why not point towards the already existing "IMDS" and "eSTS" sections?

one is for cert revocation, that MSAL handles internally. The other is for token revocation.

Robbie-Microsoft · 2025-09-25T17:48:46Z

docs/msi_v2/msiv2_revocation_spec.md

+    // Certificate/attestation validation failures
+    if (aadsts is 1000610 or 1000611 or 1000612 or 1000613 or 1000614 || aadsts == null)
+    {
+        // Force a NEW certificate and retry


We're going to force a second cert refresh?

you already do it above if claims are provided

these are two different use cases.

Robbie-Microsoft · 2025-09-25T17:50:41Z

docs/msi_v2/msiv2_revocation_spec.md

+| **AADSTS1000610–14 Auto-Remediation (Retry Fails)**      | Same initial condition as above. New cert minted, retry still fails deterministically (e.g., repeated same code). | Failure surfaced after retry. (`CredentialOutcome=Retry Failed`) |
+| **Unspecified Credential Issue**                         | eSTS returns `invalid_client` without codes. MSAL forces new certificate and retries.                           | Token succeeds or failure surfaced (assert correct `CredentialOutcome`). |
+| **Claims Challenge Path**                                | Resource 401 with claims; app supplies claims; MSAL re-mints cert (`bypass_cache=true`) and retries with claims. | New token with claims. (`CredentialOutcome=Success`) |
+| **IMDS/IssueCredential Failure Path**                    | `/issuecredential` call fails (network / service / malformed).                                                  | Failure returned; no infinite retry. (`CredentialOutcome=Retry Failed` if after a retry attempt) |


specify which retry policy

not sure I follow this comment

Updated revocation scenarios and clarified certificate request process.

Revise SLC document to focus on certificate revocation

192dcb7

Updated the document to reflect changes from 'Short-Lived Credential (SLC)' to 'Certificate' terminology and clarified the handling of certificate revocation scenarios.

gladjohn requested a review from a team as a code owner September 23, 2025 23:37

bgavrilMS reviewed Sep 24, 2025

View reviewed changes

bgavrilMS approved these changes Sep 24, 2025

View reviewed changes

bgavrilMS reviewed Sep 24, 2025

View reviewed changes

bgavrilMS requested changes Sep 24, 2025

View reviewed changes

address comments

84bbf84

gladjohn requested a review from bgavrilMS September 25, 2025 00:11

Robbie-Microsoft requested changes Sep 25, 2025

View reviewed changes

Revise certificate revocation documentation

f570454

Updated revocation scenarios and clarified certificate request process.

gladjohn requested a review from Robbie-Microsoft September 27, 2025 21:09

		@@ -1,46 +1,46 @@
		# Short-Lived Credential (SLC) Revocation Specification
		# Certificate Revocation Specification

Revise MSI v2 token revocation spec to focus on certificate revocation #5498

Are you sure you want to change the base?

Revise MSI v2 token revocation spec to focus on certificate revocation #5498

Uh oh!

Conversation

gladjohn commented Sep 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bgavrilMS left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bgavrilMS left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!