mTLS PoP: add SNI / S2S-FIC test coverage + docs

CHANGELOG.md

@@ -1,3 +1,10 @@
+Unreleased
+==========
+
+### Changes
+- Documented that mTLS Proof-of-Possession does **not** require a region: when no region is set, MSAL uses the global `mtlsauth.microsoft.com` endpoint. Corrected the stale `RegionRequiredForMtlsPop` / `MtlsPopWithoutRegion` / `MtlsBearerWithoutRegion` error-message text and doc comments (the public constants are retained for API compatibility; they are no longer raised).
+- Added end-to-end and unit coverage for the two-leg S2S (app) Federated Identity Credential (FIC) flow over mTLS PoP (SNI first leg → federated assertion → resource token bound to the same certificate), including an FMI-audience variant. No public API change; `user_fic` is not supported over mTLS.
+
 4.85.1
 ======
 

docs/mtls_pop_skills_guide.md

@@ -40,6 +40,31 @@ Which frameworks and platforms support mTLS PoP in MSAL.NET?
 
 Use these for token exchange and two-leg flows:
 
+> **Scope note:** FIC over mTLS PoP is supported for **S2S / app (client-credentials)** flows only.
+> A user-delegated **`user_fic`** flow is **not** supported over mTLS.
+
+#### SNI First Leg (S2S FIC)
+
+```
+How do I use an SNI certificate as the first leg of S2S FIC over mTLS PoP?
+```
+
+```
+Show me SNI first leg -> S2S FIC -> mtls_pop end to end in MSAL.NET
+```
+
+```
+How do I carry the Leg-1 BindingCertificate into Leg 2 with WithClientAssertion?
+```
+
+```
+Is user_fic supported over mTLS PoP? (No - S2S/app FIC only)
+```
+
+```
+What exchange audience do I use - api://AzureADTokenExchange vs api://AzureFMITokenExchange?
+```
+
 #### Understanding FIC Two-Leg Flow
 
 ```
@@ -170,6 +195,10 @@ What do I do if I get "MtlsCertificateNotProvided" error?
 What does "MtlsPopWithoutRegion" error mean?
 ```
 
+```
+Is a region required for mTLS PoP? (No - it is optional; MSAL falls back to the global mtlsauth.microsoft.com endpoint)
+```
+
 ```
 How do I troubleshoot mTLS PoP token acquisition failures?
 ```

docs/sni_mtls_pop_token_design.md

@@ -42,7 +42,12 @@ Bearer tokens are vulnerable to theft. Proof-of-Possession (PoP) tokens mitigate
 
 ### MTLS Endpoint Usage
 
-The mTLS PoP flow relies on tenanted endpoints with support for regional configurations. The behavior varies based on the cloud environment:
+The mTLS PoP flow relies on tenanted endpoints. A region is **optional** — it is recommended for performance, but when no region is configured (or auto-detection yields none) MSAL falls back to the **global** mTLS endpoint, which is production-ready. The behavior varies based on the cloud environment:
+
+#### Region is optional (global fallback)
+
+- **Regional (recommended):** `https://{region}.mtlsauth.microsoft.com/{tenant_id}` — set via `.WithAzureRegion(...)`.
+- **Global (no region):** `https://mtlsauth.microsoft.com/{tenant_id}` — used automatically when no region is set. There is **no "region required" error**; the earlier `RegionRequiredForMtlsPop` message is stale and retained only for API compatibility.
 
 #### Public Cloud
 
@@ -97,6 +102,77 @@ AuthenticationResult result = await app.AcquireTokenForClient(scopes).WithMtlsPr
     .ExecuteAsync();
 ```
 
+## Two-Leg S2S (App) FIC over mTLS PoP
+
+A confidential-client app can use its SNI certificate as the **first leg** of a Federated Identity
+Credential (FIC) exchange and obtain an **mTLS-bound PoP** token at the **second leg**. This reuses the
+existing `WithClientAssertion(...)` seam that accepts a `ClientSignedAssertion` carrying an optional
+`TokenBindingCertificate` — no new public API.
+
+> **Scope:** FIC over mTLS PoP is supported for **S2S / app (client-credentials)** flows only.
+> **`user_fic` (a user-delegated FIC) is _not_ supported over mTLS.**
+
+- **Leg 1 — SNI cert → federated assertion (cert-bound PoP).** `AcquireTokenForClient` against the
+  exchange audience with `WithMtlsProofOfPossession()`. Leg 1 being cert-bound PoP is what produces the
+  `cnf`. The result exposes `AuthenticationResult.BindingCertificate` (public material only — x5c +
+  `x5t#S256`; never a private key).
+- **Leg 2 — federated assertion → final app token (bound to the Leg-1 cert).** `AcquireTokenForClient`
+  against the final resource, supplying the Leg-1 assertion **and** the Leg-1 binding certificate via
+  `ClientSignedAssertion.TokenBindingCertificate`, again with `WithMtlsProofOfPossession()`. MSAL sends
+  `client_assertion` + `client_assertion_type = urn:ietf:params:oauth:client-assertion-type:jwt-pop`
+  over mTLS, and the returned token is `mtls_pop`, bound to the **same** certificate as Leg 1.
+
+```csharp
+X509Certificate2 sniCert = GetCertificateFromStore("Use The Lab Auth Cert");
+
+// Leg 1: SNI cert -> federated assertion (mtls_pop)
+var leg1App = ConfidentialClientApplicationBuilder.Create(clientId)
+    .WithAuthority(authority)
+    .WithCertificate(sniCert, sendX5C: true)
+    .Build();
+
+AuthenticationResult leg1 = await leg1App
+    .AcquireTokenForClient(new[] { "api://AzureADTokenExchange/.default" })
+    .WithMtlsProofOfPossession()
+    .ExecuteAsync();
+// leg1.TokenType == "mtls_pop"; leg1.BindingCertificate == the SNI cert (public material).
+
+// Leg 2: carry the Leg-1 assertion + binding cert -> resource token (mtls_pop)
+var leg2App = ConfidentialClientApplicationBuilder.Create(clientId)
+    .WithAuthority(authority)
+    .WithClientAssertion((options, ct) => Task.FromResult(new ClientSignedAssertion
+    {
+        Assertion = leg1.AccessToken,                 // the federated assertion
+        TokenBindingCertificate = leg1.BindingCertificate // carry the SAME cert forward
+    }))
+    .Build();
+
+AuthenticationResult leg2 = await leg2App
+    .AcquireTokenForClient(new[] { "https://vault.azure.net/.default" })
+    .WithMtlsProofOfPossession()
+    .ExecuteAsync();
+// leg2.TokenType == "mtls_pop", bound to leg1.BindingCertificate.Thumbprint.
+```
+
+### Exchange audience is caller-supplied
+
+MSAL does **not** hardcode the exchange audience — it passes through whatever scope the caller requests
+at Leg 1:
+
+- **Generic S2S FIC:** `api://AzureADTokenExchange/.default`.
+- **FMI variant:** `api://AzureFMITokenExchange/.default`, using the reserved client id
+  `urn:microsoft:identity:fmi`.
+
+Both produce the same PoP outcome; the choice is the caller's.
+
+### Transport ownership (mTLS requires MSAL's built-in handler)
+
+mTLS requires MSAL to **own the HTTP transport handler** so it can attach the client certificate to the
+outbound TLS connection. The built-in factory (`IMsalMtlsHttpClientFactory` / `SimpleHttpClientFactory`,
+which is the default) does this. A caller-supplied **plain** `IMsalHttpClientFactory` (a bare
+`HttpClient`) **cannot** carry the mTLS certificate — supply an mTLS-capable factory or rely on the
+built-in transport.
+
 ## Tests to Validate mTLS PoP Tokens
 
 ### Certificate Validation Tests
@@ -114,7 +190,7 @@ AuthenticationResult result = await app.AcquireTokenForClient(scopes).WithMtlsPr
 
 ### Region Validation Tests
 
-- Ensure `MsalClientException` is thrown when no region is set and `WithMtlsProofOfPossession()` is called.
+- Ensure a **no-region** `WithMtlsProofOfPossession()` request succeeds against the **global** `mtlsauth.microsoft.com` endpoint (region is optional; there is no "region required" failure).
 - Validate successful token acquisition with a specified region.
 - Test auto-detected region functionality and confirm the expected region is used.
 - Region is not required if the authority is DSTS.

src/client/Microsoft.Identity.Client/Instance/Discovery/RegionAndMtlsDiscoveryProvider.cs

@@ -17,7 +17,15 @@ internal class RegionAndMtlsDiscoveryProvider : IRegionDiscoveryProvider
         public const string PublicEnvForRegional = "login.microsoft.com";
         public const string PublicEnvForRegionalMtlsAuth = "mtlsauth.microsoft.com";
 
-        // Map of unsupported sovereign cloud hosts for mTLS PoP to their error messages
+        // ─────────────────────────────────────────────────────────────────────────────
+        // SOVEREIGN GUARDRAIL — single override point for mTLS cloud availability.
+        // mTLS PoP is currently rejected for sovereign clouds (US Gov, China) and any
+        // non-"login." host. mtlsauth.* is rolling out across clouds (Azure Government /
+        // AGC: available; Bleu / Delos: TBD). To enable a cloud, remove its entry here
+        // (and, if needed, relax the non-"login." host check below) — this is the ONLY
+        // place cloud eligibility is enforced, so do not scatter equivalent checks
+        // elsewhere in the codebase.
+        // ─────────────────────────────────────────────────────────────────────────────
         private static readonly Dictionary<string, string> s_unsupportedMtlsHosts =
             new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
             {
@@ -32,7 +40,8 @@ public RegionAndMtlsDiscoveryProvider(IHttpManager httpManager)
 
         public async Task<InstanceDiscoveryMetadataEntry> GetMetadataAsync(Uri authority, RequestContext requestContext)
         {
-            // Fail fast: Check for unsupported mTLS hosts before any region discovery
+            // SOVEREIGN GUARDRAIL (see s_unsupportedMtlsHosts above): fail fast for clouds
+            // where mTLS PoP is not yet available, before any region discovery.
             if (requestContext.IsMtlsRequested)
             {
                 string host = authority.Host;

src/client/Microsoft.Identity.Client/MsalError.cs

@@ -1185,14 +1185,14 @@ public static class MsalError
         public const string CryptographicError = "cryptographic_error";
 
         /// <summary>
-        /// <para>What happened?</para>mTLS Proof of Possession (mTLS PoP) is configured but a region was not specified.
-        /// <para>Mitigation</para>Ensure that the AzureRegion configuration is set when using mTLS PoP as it requires a regional endpoint.
+        /// <para>What happened?</para>Historical error code. A region is <b>not</b> required for mTLS Proof of Possession — when none is specified, MSAL uses the global mTLS endpoint (mtlsauth.microsoft.com). This code is no longer raised.
+        /// <para>Mitigation</para>No action needed. Optionally set AzureRegion for improved performance.
         /// </summary>
         public const string MtlsPopWithoutRegion = "mtls_pop_without_region";
 
         /// <summary>
-        /// <para>What happened?</para>mTLS Bearer is configured but a region was not specified.
-        /// <para>Mitigation</para>Ensure that the AzureRegion configuration is set when using mTLS Bearer as it requires a regional endpoint.
+        /// <para>What happened?</para>Historical error code. A region is <b>not</b> required for Bearer-over-mTLS — when none is specified, MSAL uses the global mTLS endpoint (mtlsauth.microsoft.com). This code is no longer raised.
+        /// <para>Mitigation</para>No action needed. Optionally set AzureRegion for improved performance.
         /// </summary>
         public const string MtlsBearerWithoutRegion = "mtls_bearer_without_region";
 
@@ -1203,8 +1203,8 @@ public static class MsalError
         public const string MtlsCertificateNotProvided = "mtls_certificate_not_provided";
 
         /// <summary>
-        /// <para>What happened?</para> mTLS Proof of Possession (mTLS PoP) requires a specific Azure region to be specified.
-        /// <para>Mitigation:</para> Ensure that the AzureRegion configuration is set when using mTLS PoP as it requires a regional endpoint.
+        /// <para>What happened?</para> Historical error code. A region is <b>not</b> required for mTLS Proof of Possession (mTLS PoP). When regional auto-detection does not yield a region, MSAL falls back to the global mTLS endpoint (mtlsauth.microsoft.com). This code is no longer raised.
+        /// <para>Mitigation:</para> No action needed. Optionally set AzureRegion via WithAzureRegion for improved performance.
         /// </summary>
         public const string RegionRequiredForMtlsPop = "region_required_for_mtls_pop";
 

src/client/Microsoft.Identity.Client/MsalErrorMessage.cs

@@ -437,15 +437,15 @@ public static string InvalidTokenProviderResponseValue(string invalidValueName)
         public const string SetCiamAuthorityAtRequestLevelNotSupported = "Setting the CIAM authority (ex. \"{tenantName}.ciamlogin.com\") at the request level is not supported. The CIAM authority must be set during application creation";
         public const string ClaimsChallenge = "The returned error contains a claims challenge. For additional info on how to handle claims related to multifactor authentication, Conditional Access, and incremental consent, see https://aka.ms/msal-conditional-access-claims. If you are using the On-Behalf-Of flow, see https://aka.ms/msal-conditional-access-claims-obo for details.";
         public const string CryptographicError = "A cryptographic exception occurred. Possible cause: the certificate has been disposed. See inner exception for full details.";
-        public const string MtlsPopWithoutRegion = "mTLS Proof of Possession requires a region to be specified. Please set AzureRegion in the configuration at the application level.";
+        public const string MtlsPopWithoutRegion = "mTLS Proof-of-Possession does not require a region. When no region is specified, MSAL uses the global mTLS endpoint (mtlsauth.microsoft.com). Setting AzureRegion is recommended for performance. See https://aka.ms/msal-net-pop for details.";
         public const string MtlsCertificateNotProvidedMessage = "mTLS Proof‑of‑Possession requires a certificate for this request. Either configure the application with .WithCertificate(...) or pass a certificate‑bound client‑assertion and chain .WithMtlsProofOfPossession() on the request builder. See https://aka.ms/msal-net-pop for details.";
         public const string MtlsNotSupportedWithClientClaimsMessage = "mTLS transport (Proof-of-Possession via .WithMtlsProofOfPossession() or Bearer-over-mTLS via CertificateOptions.SendCertificateOverMtls = true) is not supported when the credential is configured via .WithClientClaims(certificate, claimsToSign, ...). Custom client claims require a signed JWT-bearer client assertion, which is not produced in mTLS mode. To use mTLS, configure the application with .WithCertificate(certificate) without .WithClientClaims(...), or use .WithClientAssertion(...) with a signed assertion that carries the binding certificate. See https://aka.ms/msal-net-pop for details.";
-        public const string MtlsBearerWithoutRegion = "mTLS Bearer requires a region to be specified. Please set AzureRegion in the configuration at the application level.";
+        public const string MtlsBearerWithoutRegion = "Bearer-over-mTLS does not require a region. When no region is specified, MSAL uses the global mTLS endpoint (mtlsauth.microsoft.com). Setting AzureRegion is recommended for performance. See https://aka.ms/msal-net-pop for details.";
         public const string MtlsInvalidAuthorityTypeMessage = "mTLS PoP is only supported for AAD authority type. See https://aka.ms/msal-net-pop for details.";
         public const string MtlsNonTenantedAuthorityNotAllowedMessage = "mTLS authentication requires a tenanted authority. Using 'common', 'organizations', or similar non-tenanted authorities is not allowed. Please provide an authority with a specific tenant ID (e.g., 'https://login.microsoftonline.com/{tenantId}'). See https://aka.ms/msal-net-pop for details.";
         public const string MtlsNotSupportedForManagedIdentityMessage = "IMDSv2 flow is not supported on .NET Framework 4.6.2. Cryptographic operations required for managed identity authentication are unavailable on this platform.";
         public const string MtlsNotSupportedForNonWindowsMessage = "mTLS PoP with Managed Identity is not supported on this OS. See https://aka.ms/msal-net-pop.";
-        public const string RegionRequiredForMtlsPopMessage = "Regional auto-detect failed. mTLS Proof-of-Possession requires a region to be specified, as there is no global endpoint for mTLS. See https://aka.ms/msal-net-pop for details.";
+        public const string RegionRequiredForMtlsPopMessage = "mTLS Proof-of-Possession does not require a region. When regional auto-detection does not yield a region, MSAL falls back to the global mTLS endpoint (mtlsauth.microsoft.com). Setting AzureRegion via WithAzureRegion is recommended for performance. See https://aka.ms/msal-net-pop for details.";
         public const string MtlsPopNotSupportedForUsGovCloudApiMessage = "login.usgovcloudapi.net is not supported for mTLS PoP, please use login.microsoftonline.us";
         public const string MtlsPopNotSupportedForChinaCloudApiMessage = "login.chinacloudapi.cn is not supported for mTLS PoP, please use login.partner.microsoftonline.cn";
         public const string MtlsPopNotSupportedForNonLoginHostMessage = "mTLS PoP is only supported for hosts that start with 'login.'. The provided authority host does not meet this requirement. See https://aka.ms/msal-net-pop for details.";