MSAL MSI with Credentials - Authentication Design #5096

gladjohn · 2025-01-22T18:27:38Z

This pull request includes several important changes that provide detailed guidance on implementing and handling the MSI V2 /credential endpoint, including token acquisition, SLC revocation, and probing logic for VM/VMSS. The key changes are summarized below:

Implementation of MSI V2 `/credential` Endpoint:

Added a design document outlining the token acquisition process for MSI V2 using the /credential endpoint, including steps for certificate handling and source detection logic.

SLC Revocation Specification:

Introduced a specification for handling short-lived credential (SLC) revocation scenarios, detailing the process for obtaining new credentials when an existing one is revoked or invalid.

VM/VMSS Credential Endpoint Probe Logic:

Added documentation on the probe logic to determine the availability of the MSI V2 /credential endpoint in IMDS for VM/VMSS, including handling IMDS restart scenarios and expected responses.

bgavrilMS · 2025-01-28T10:40:09Z

docs/msi_with_credential_design.md

+
+To start the flow, MSAL requires a certificate. MSAL follows these steps:
+
+1. **Check for an existing certificate**: MSAL looks for a specific certificate (`devicecert.mtlsauth.local`).


Where does it look?

bgavrilMS · 2025-01-28T10:41:25Z

docs/msi_with_credential_design.md

+This section outlines the necessary steps to acquire an access token using the MSI V2 `/credential` endpoint. 
+
+### 1. Check for an Existing (Platform) Certificate
+- Search for a specific certificate (`devicecert.mtlsauth.local`) in `Cert:\LocalMachine\My`.


What about Linux?

bgavrilMS · 2025-01-28T10:42:19Z

docs/msi_with_credential_design.md

+- If found, extract its thumbprint and use it for authentication.
+
+### 2. Generate a New Certificate (if specific certificate is not found)
+- Create a new self-signed certificate with a 90-day validity.


Please detail how to create it - in memory, or create it and place it in a cert store etc.
And what to do after 90 days.

bgavrilMS · 2025-01-28T10:57:58Z

docs/msi_with_credential_design.md

+- Send a POST request to the IMDS `/credential` endpoint with the certificate details.
+- The request must include:
+  - `Metadata: true` header.
+  - `X-ms-Client-Request-id` header with a GUID.


Presumably this is the CorrelationID similar to CCA's correlation ID? And it also implies that we should add WithCorrelationID API to MSIApplication?

bgavrilMS · 2025-01-28T11:15:32Z

docs/msi_with_credential_design.md

+- The request must include:
+  - `Metadata: true` header.
+  - `X-ms-Client-Request-id` header with a GUID.
+  - JSON body containing the certificate's public key in `jwk` format.


Do you want to reference the RFC? https://datatracker.ietf.org/doc/html/rfc7517#appendix-A.1

bgavrilMS · 2025-01-28T11:16:51Z

docs/msi_with_credential_design.md

+    # Create a new self-signed certificate
+    $cert = New-SelfSignedCertificate `
+        -Subject $certSubject `
+        -CertStoreLocation "Cert:\LocalMachine\My" `


But in MSAL we shoudl store it in memory no?

bgavrilMS · 2025-01-28T11:17:28Z

docs/msi_with_credential_design.md

+    kty = "RSA"
+    use = "sig"
+    alg = "RS256"
+    kid = $cert.Thumbprint


Do not use Thumbprint. This is SHA1 driven and is banned by the Crypto board. Use SHA256 thrumbprint.

bgavrilMS · 2025-01-28T11:18:55Z

docs/msi_with_credential_design.md

+| `WithClaims()`                   | Allows passing of claims (bypasses cache).                |
+| `GetBindingCertificate()`        | Helper method to get the binding certificate.             |
+| `GetManagedIdentitySourceAsync()`| Helper method to get the managed identity source.         |
+| `WithProofOfPossession()`        | Requests a PoP token instead of a default Bearer token.   |


Not the actual API name and I don't think you should bring it here.

bgavrilMS · 2025-01-28T11:19:07Z

docs/msi_with_credential_design.md

+| `WithClientCapabilities()`       | Allows client capabilities                                |
+| `WithClaims()`                   | Allows passing of claims (bypasses cache).                |
+| `GetBindingCertificate()`        | Helper method to get the binding certificate.             |
+| `GetManagedIdentitySourceAsync()`| Helper method to get the managed identity source.         |


This alraedy exists in all MSALs no? For Azure SDK. Do we add an extra source?

bgavrilMS · 2025-01-28T11:19:25Z

docs/msi_with_credential_design.md

+
+## Summary of New APIs
+
+| API Name                         | Purpose                                                   |


You need to specify where these API will be exposed.

bgavrilMS · 2025-01-28T11:20:18Z

docs/slc_revocation_spec.md

@@ -0,0 +1,59 @@
+# Short-Lived Credential (SLC) Revocation Specification


There are quite a few docs here. How about creating a directory for MSIv2 and adding a short index.md to organize everything?

bgavrilMS · 2025-01-28T11:21:48Z

docs/msi_with_credential_design.md

+|----------------------------------|-----------------------------------------------------------|
+| `WithClientCapabilities()`       | Allows client capabilities                                |
+| `WithClaims()`                   | Allows passing of claims (bypasses cache).                |
+| `GetBindingCertificate()`        | Helper method to get the binding certificate.             |


What does this do when not hosted on VM?

bgavrilMS · 2025-01-28T11:22:58Z

docs/msi_with_credential_design.md

+- Convert the certificate to a Base64-encoded string (`x5c`).
+- Format the JSON payload containing the certificate details for request authentication.
+
+### 4. Request MSI Credential


What about credential caching? Where do we cache this?

bgavrilMS · 2025-01-28T11:24:54Z

docs/vm_vmss_credential_probe.md

+| **1️⃣** | Send a **POST request** to `/metadata/identity/credential` **without headers**, using `.` as the body. | | |
+| **2️⃣** | **Check HTTP response status.** | | |
+| **3️⃣** | If **400 Bad Request**, the `/credential` endpoint **is available**. | Proceed with token acquisition. |
+| **4️⃣** | If **500 Internal Server Error**, check the **Server** header. | `"Microsoft-IIS/10.0"` (no `IMDS/`) | Retry the request (IMDS might be restarting). |


Please give details about retry mechanism

bgavrilMS · 2025-01-28T11:45:14Z

docs/msi_with_credential_design.md

+
+- **[SLC Design Document](https://microsoft.sharepoint.com/:w:/t/AzureMSI/EURnTEtFXPlDngpYhCUioqUBvbSUWEX7vZjP0nm8bxUsQA?e=Ejok1n&wdLOR=cE6820299-49AF-4D7A-B7F7-F58D65C232B6)**
+- **[MSAL EPIC](https://identitydivision.visualstudio.com/Engineering/_workitems/edit/3027078)**
+


There needs to be a telemetry chapter. At a minimum we'd want to know if we are dealing with a self-generated cert or one read from the store. Anything else?

bgavrilMS · 2025-01-28T11:46:42Z

docs/vm_vmss_credential_probe.md

+| **4️⃣** | If **500 Internal Server Error**, check the **Server** header. | `"Microsoft-IIS/10.0"` (no `IMDS/`) | Retry the request (IMDS might be restarting). |
+| **5️⃣** | If the response does not match the above cases, treat it as **unexpected behavior**. | | Log the issue or fallback to IMDS `/token` if applicable. |
+
+---


Telemetry chapter? Smth like Probe outcome - "found the endpoint with no retries", "found with retries" and "not found"

bgavrilMS · 2025-01-28T11:47:37Z

docs/slc_revocation_spec.md

+## **MSAL Behavior to Relay the Signal to IMDS**
+
+- MSAL can only determine that an `{ "error": "invalid_client" }` response is caused by a credential issue but cannot handle suberrors explicitly.
+- For SLC-related errors, MSAL will retry obtaining a new SLC from IMDS and retry with eSTS.


retry logic needs details.

bgavrilMS · 2025-01-28T11:48:18Z

docs/slc_revocation_spec.md

+
+return tokenResponse;
+```
+


Telemetyry chapter and acceptance tests chapter are missing.

bgavrilMS · 2025-01-28T11:48:52Z

docs/slc_revocation_spec.md

+
+- MSAL can only determine that an `{ "error": "invalid_client" }` response is caused by a credential issue but cannot handle suberrors explicitly.
+- For SLC-related errors, MSAL will retry obtaining a new SLC from IMDS and retry with eSTS.
+- For claims challenges, MSAL does not get a signal from eSTS but rather from the app developer when passing claims to MSAL.


Probably deserves its own chapter?

init

54cfce2

gladjohn requested a review from a team as a code owner January 22, 2025 18:27

GladwinJohnson and others added 7 commits January 22, 2025 10:35

doc links

837ef5b

apis

4bda98e

typo

8f09566

Update MSI V2 authentication steps and API table

b55a948

Create slc_revocation_spec.md

7cdffc2

Add MSAL EPIC link to related documents.

8a1ebe3

Update revocation spec with unspecified credential issue

ff0c095

bgavrilMS reviewed Jan 28, 2025

View reviewed changes

docs/slc_revocation_spec.md

return tokenResponse;

```

Copy link

Member

bgavrilMS Jan 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Telemetyry chapter and acceptance tests chapter are missing.

bgavrilMS reviewed Jan 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MSAL MSI with Credentials - Authentication Design #5096

MSAL MSI with Credentials - Authentication Design #5096

gladjohn commented Jan 22, 2025 •

edited

Loading

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025 •

edited

Loading

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025

bgavrilMS Jan 28, 2025


		To start the flow, MSAL requires a certificate. MSAL follows these steps:

		1. Check for an existing certificate: MSAL looks for a specific certificate (`devicecert.mtlsauth.local`).

		@@ -0,0 +1,59 @@
		# Short-Lived Credential (SLC) Revocation Specification


		- [SLC Design Document](https://microsoft.sharepoint.com/:w:/t/AzureMSI/EURnTEtFXPlDngpYhCUioqUBvbSUWEX7vZjP0nm8bxUsQA?e=Ejok1n&wdLOR=cE6820299-49AF-4D7A-B7F7-F58D65C232B6)
		- [MSAL EPIC](https://identitydivision.visualstudio.com/Engineering/_workitems/edit/3027078)

MSAL MSI with Credentials - Authentication Design #5096

Are you sure you want to change the base?

MSAL MSI with Credentials - Authentication Design #5096

Conversation

gladjohn commented Jan 22, 2025 • edited Loading

Implementation of MSI V2 /credential Endpoint:

SLC Revocation Specification:

VM/VMSS Credential Endpoint Probe Logic:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bgavrilMS Jan 28, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gladjohn commented Jan 22, 2025 •

edited

Loading

Implementation of MSI V2 `/credential` Endpoint:

bgavrilMS Jan 28, 2025 •

edited

Loading