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.

docs/msi_v2/msiv2_revocation_spec.md

docs/msi_v2/slc_revocation_spec.md

bgavrilMS

Approved with comments

docs/msi_v2/msiv2_revocation_spec.md

docs/msi_v2/slc_revocation_spec.md

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.

I still don't see it

docs/msi_v2/msiv2_revocation_spec.md

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

Please explain the difference to me. Why aren't the diagrams the same for each condition?

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.

This isn't clear on the diagram. Can you use this wording on the diagram?

docs/msi_v2/msiv2_revocation_spec.md

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

You mention "retry" several times in this spec. I'm asking you: what retry policy are we using for these retries?

Updated revocation scenarios and clarified certificate request process.

bgavrilMS · 2025-10-21T16:52:02Z

docs/msi_v2/msiv2_revocation_spec.md

@@ -0,0 +1,196 @@
+# Certificate Revocation Specification


Is this going to be implemented for preview?

no, this is not for preview.

Robbie-Microsoft · 2025-10-24T15:06:03Z

docs/msi_v2/msiv2_revocation_spec.md

+
+This document outlines the design and implementation details for **certificate and token revocation** in MSI V2 scenarios.
+
+In the MSI v2 authentication flow, MSAL first obtains a credential (certificate) from IMDS and uses it to request a token from eSTS. In some cases, eSTS may respond with an error indicating that the certificate/attestation is no longer valid. When this occurs, **MSAL must obtain a new certificate** before retrying the token request with eSTS.


MSAL first "makes a CSR metadata request"

Robbie-Microsoft

I will re-review after you'd had a chance to respond to the comments I just left.

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

docs/msi_v2/msiv2_revocation_spec.md Show resolved Hide resolved

bgavrilMS reviewed Sep 24, 2025

View reviewed changes

docs/msi_v2/slc_revocation_spec.md Outdated Show resolved Hide resolved

bgavrilMS reviewed Sep 24, 2025

View reviewed changes

docs/msi_v2/slc_revocation_spec.md Outdated Show resolved Hide resolved

bgavrilMS reviewed Sep 24, 2025

View reviewed changes

docs/msi_v2/slc_revocation_spec.md Outdated Show resolved Hide resolved

bgavrilMS reviewed Sep 24, 2025

View reviewed changes

docs/msi_v2/slc_revocation_spec.md Outdated Show resolved Hide resolved

bgavrilMS approved these changes Sep 24, 2025

View reviewed changes

bgavrilMS reviewed Sep 24, 2025

View reviewed changes

docs/msi_v2/msiv2_revocation_spec.md Show resolved Hide resolved

bgavrilMS reviewed Sep 24, 2025

View reviewed changes

docs/msi_v2/slc_revocation_spec.md Outdated Show resolved Hide resolved

bgavrilMS reviewed Sep 24, 2025

View reviewed changes

docs/msi_v2/slc_revocation_spec.md Outdated Show resolved Hide resolved

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

bgavrilMS reviewed Oct 21, 2025

View reviewed changes

gladjohn requested a review from bgavrilMS October 22, 2025 13:22

Robbie-Microsoft reviewed Oct 24, 2025

View reviewed changes

Robbie-Microsoft requested changes Oct 24, 2025

View reviewed changes


		This document outlines the design and implementation details for certificate and token revocation in MSI V2 scenarios.

		In the MSI v2 authentication flow, MSAL first obtains a credential (certificate) from IMDS and uses it to request a token from eSTS. In some cases, eSTS may respond with an error indicating that the certificate/attestation is no longer valid. When this occurs, MSAL must obtain a new certificate before retrying the token request with eSTS.

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bgavrilMS left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

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!

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!

Robbie-Microsoft left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants