Add CertificateOptions and update the WithCertificate APIs to use CertificateOptions

src/client/Microsoft.Identity.Client/AppConfig/CertificateOptions.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Identity.Client.AppConfig
+{
+    /// <summary>
+    /// Represents configuration options for certificate handling or management.
+    /// </summary>
+    public record CertificateOptions
+    {
+        /// <summary>
+        /// Gets or sets a value indicating whether the X.509 certificate chain (x5c) should be included in the token
+        /// request.
+        /// </summary>
+        /// <remarks>Set this property to <see langword="true"/> to include X5C in the token request 
+        /// otherwise, set it to <see langword="false"/>.</remarks>
+        public bool SendX5C { get; init; } = false;
+
+        /// <summary>
+        /// Gets or sets a value indicating if the application tokens acquired from Azure AD are associated with the certificate serial number.
+        /// This property when set, allow you to associate the tokens acquired from Azure AD with the certificate serial number. 
+        /// This can be used to partition the cache by certificate. Tokens acquired with one certificate will not be accessible to another certificate with a different serial number.
+        /// <remarks>Set this property to <see langword="true"/> to indicate that the tokens acquired from Azure AD are associated with the certificate serial number,
+        /// by default it is set to <see langword="false"/> /></remarks>
+        /// </summary>
+        public bool AssociateTokensWithCertificate { get; init; } = false;
+    }
+}

src/client/Microsoft.Identity.Client/AppConfig/ConfidentialClientApplicationBuilder.cs

@@ -5,6 +5,7 @@
 using System.Collections.Generic;
 using System.ComponentModel;
 using System.Linq;
+using System.Reflection;
 using System.Security.Cryptography.X509Certificates;
 using System.Threading;
 using System.Threading.Tasks;
@@ -130,6 +131,42 @@ public ConfidentialClientApplicationBuilder WithCertificate(X509Certificate2 cer
             return this;
         }
 
+        /// <summary>
+        /// Sets the certificate associated with the application.
+        /// Applicable to first-party applications only, this method also allows to specify 
+        /// if the <see href="https://datatracker.ietf.org/doc/html/rfc7517#section-4.7">x5c claim</see> should be sent to Azure AD.
+        /// Sending the x5c enables application developers to achieve easy certificate roll-over in Azure AD:
+        /// this method will send the certificate chain to Azure AD along with the token request,
+        /// so that Azure AD can use it to validate the subject name based on a trusted issuer policy.
+        /// This saves the application admin from the need to explicitly manage the certificate rollover
+        /// (either via portal or PowerShell/CLI operation). For details see https://aka.ms/msal-net-sni
+        /// </summary>
+        /// <param name="certificate">The X509 certificate used as credentials to prove the identity of the application to Azure AD.</param>
+        /// <param name="certificateOptions">Configuration options for certificate handling. See <see cref="CertificateOptions"/> for more information.</param>
+        /// <remarks>You should use certificates with a private key size of at least 2048 bytes. Future versions of this library might reject certificates with smaller keys. </remarks>
+        public ConfidentialClientApplicationBuilder WithCertificate(X509Certificate2 certificate, CertificateOptions certificateOptions)
+        {
+            if (certificate == null)
+            {
+                throw new ArgumentNullException(nameof(certificate));
+            }
+
+            if (!certificate.HasPrivateKey)
+            {
+                throw new MsalClientException(MsalError.CertWithoutPrivateKey, MsalErrorMessage.CertMustHavePrivateKey(nameof(certificate)));
+            }
+
+            if (certificateOptions?.AssociateTokensWithCertificate ?? false)
+            {
+                Config.CertificateIdToAssociateWithToken = certificate.SerialNumber;
+            }
+
+            Config.ClientCredential = new CertificateClientCredential(certificate);
+            Config.SendX5C = certificateOptions?.SendX5C ?? false;
+
+            return this;
+        }
+
         /// <summary>
         /// Sets the certificate associated with the application along with the specific claims to sign.
         /// By default, this will merge the <paramref name="claimsToSign"/> with the default required set of claims needed for authentication.

src/client/Microsoft.Identity.Client/Extensibility/ConfidentialClientApplicationBuilderExtensions.cs

@@ -4,6 +4,7 @@
 using System;
 using System.Security.Cryptography.X509Certificates;
 using System.Threading.Tasks;
+using Microsoft.Identity.Client.AppConfig;
 using Microsoft.Identity.Client.Internal.ClientCredential;
 
 namespace Microsoft.Identity.Client.Extensibility
@@ -41,8 +42,8 @@ public static ConfidentialClientApplicationBuilder WithAppTokenProvider(
         /// <param name="certificateProvider">
         /// An async callback that provides the certificate based on the application configuration.
         /// Called before each network request to acquire a token.
-        /// Must return a valid <see cref="X509Certificate2"/> with a private key.
-        /// </param>
+        /// Must return a valid <see cref="X509Certificate2"/> with a private key.</param>
+        /// <param name="certificateOptions">Configuration options for the certificate handling.</param>
         /// <returns>The builder to chain additional configuration calls.</returns>
         /// <exception cref="ArgumentNullException">Thrown when <paramref name="certificateProvider"/> is null.</exception>
         /// <exception cref="MsalClientException">
@@ -58,8 +59,11 @@ public static ConfidentialClientApplicationBuilder WithAppTokenProvider(
         /// </remarks>
         public static ConfidentialClientApplicationBuilder WithCertificate(
             this ConfidentialClientApplicationBuilder builder,
-            Func<AssertionRequestOptions, Task<X509Certificate2>> certificateProvider)
+            Func<AssertionRequestOptions, Task<X509Certificate2>> certificateProvider, 
+            CertificateOptions certificateOptions)
         {
+            builder.ValidateUseOfExperimentalFeature();
+
             if (certificateProvider == null)
             {
                 throw new ArgumentNullException(nameof(certificateProvider));
@@ -69,7 +73,9 @@ public static ConfidentialClientApplicationBuilder WithCertificate(
             // The certificate will be resolved dynamically via the provider in ResolveCertificateAsync
             builder.Config.ClientCredential = new DynamicCertificateClientCredential(
                 certificateProvider: certificateProvider);
-
+
+            builder.Config.SendX5C = certificateOptions?.SendX5C ?? false;
+
             return builder;
         }
 
@@ -118,6 +124,8 @@ public static ConfidentialClientApplicationBuilder OnMsalServiceFailure(
             this ConfidentialClientApplicationBuilder builder,
             Func<AssertionRequestOptions, ExecutionResult, Task<bool>> onMsalServiceFailure)
         {
+            builder.ValidateUseOfExperimentalFeature();
+
             if (onMsalServiceFailure == null)
                 throw new ArgumentNullException(nameof(onMsalServiceFailure));
 

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

@@ -0,0 +1,11 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#if NETSTANDARD || NET462 || NET472
+namespace System.Runtime.CompilerServices
+{
+    internal static class IsExternalInit
+    {
+    }
+}
+#endif

src/client/Microsoft.Identity.Client/Microsoft.Identity.Client.csproj

@@ -80,6 +80,7 @@
     <Compile Include="$(PathToMsalSources)\**\*.cs" Exclude="$(PathToMsalSources)\obj\**\*.*" />
     <Compile Remove="$(PathToMsalSources)\Platforms\**\*.*;$(PathToMsalSources)\Resources\*.cs" />
     <Compile Remove="$(PathToMsalSources)\PlatformsCommon\PlatformNotSupported\ApiConfig\SystemWebViewOptions.cs" />
+    <None Remove="IsExternalInit.cs" />
     <EmbeddedResource Include="$(PathToMsalSources)\Properties\Microsoft.Identity.Client.rd.xml" />
     <None Include="$(PathToMsalSources)\..\..\..\README.md" Pack="true" PackagePath="\" />
     <None Include="Platforms\net\JsonObjectAttribute.cs" />
@@ -162,4 +163,8 @@
     <AdditionalFiles Include="PublicAPI/$(TargetFramework)/PublicAPI.Unshipped.txt" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Compile Include="IsExternalInit.cs" />
+  </ItemGroup>
+
 </Project>

src/client/Microsoft.Identity.Client/PublicApi/net462/PublicAPI.Shipped.txt

@@ -1109,7 +1109,6 @@ Microsoft.Identity.Client.Extensibility.ExecutionResult.Result.get -> Microsoft.
 Microsoft.Identity.Client.Extensibility.ExecutionResult.Successful.get -> bool
 static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.OnCompletion(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, Microsoft.Identity.Client.Extensibility.ExecutionResult, System.Threading.Tasks.Task> onCompletion) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
 static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.OnMsalServiceFailure(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, Microsoft.Identity.Client.Extensibility.ExecutionResult, System.Threading.Tasks.Task<bool>> onMsalServiceFailure) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
-static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.WithCertificate(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, System.Threading.Tasks.Task<System.Security.Cryptography.X509Certificates.X509Certificate2>> certificateProvider) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySourceResult
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySourceResult.ImdsV1FailureReason.get -> string
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySourceResult.ImdsV1FailureReason.set -> void

src/client/Microsoft.Identity.Client/PublicApi/net462/PublicAPI.Unshipped.txt

@@ -1,4 +1,11 @@
+Microsoft.Identity.Client.AppConfig.CertificateOptions
+Microsoft.Identity.Client.AppConfig.CertificateOptions.AssociateTokensWithCertificate.get -> bool
+Microsoft.Identity.Client.AppConfig.CertificateOptions.AssociateTokensWithCertificate.init -> void
+Microsoft.Identity.Client.AppConfig.CertificateOptions.SendX5C.get -> bool
+Microsoft.Identity.Client.AppConfig.CertificateOptions.SendX5C.init -> void
+Microsoft.Identity.Client.ConfidentialClientApplicationBuilder.WithCertificate(System.Security.Cryptography.X509Certificates.X509Certificate2 certificate, Microsoft.Identity.Client.AppConfig.CertificateOptions certificateOptions) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
 static Microsoft.Identity.Client.Extensibility.AbstractConfidentialClientAcquireTokenParameterBuilderExtension.WithExtraClientAssertionClaims<T>(this Microsoft.Identity.Client.AbstractAcquireTokenParameterBuilder<T> builder, string clientAssertionClaims) -> Microsoft.Identity.Client.AbstractAcquireTokenParameterBuilder<T>
 Microsoft.Identity.Client.ManagedIdentityPopExtensions
 static Microsoft.Identity.Client.ManagedIdentityPopExtensions.WithMtlsProofOfPossession(this Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder builder) -> Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder
 Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder.WithAttributes(string attributeJson) -> Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder
+static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.WithCertificate(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, System.Threading.Tasks.Task<System.Security.Cryptography.X509Certificates.X509Certificate2>> certificateProvider, Microsoft.Identity.Client.AppConfig.CertificateOptions certificateOptions) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder

src/client/Microsoft.Identity.Client/PublicApi/net472/PublicAPI.Shipped.txt

@@ -1109,7 +1109,6 @@ Microsoft.Identity.Client.Extensibility.ExecutionResult.Result.get -> Microsoft.
 Microsoft.Identity.Client.Extensibility.ExecutionResult.Successful.get -> bool
 static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.OnCompletion(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, Microsoft.Identity.Client.Extensibility.ExecutionResult, System.Threading.Tasks.Task> onCompletion) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
 static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.OnMsalServiceFailure(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, Microsoft.Identity.Client.Extensibility.ExecutionResult, System.Threading.Tasks.Task<bool>> onMsalServiceFailure) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
-static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.WithCertificate(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, System.Threading.Tasks.Task<System.Security.Cryptography.X509Certificates.X509Certificate2>> certificateProvider) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySourceResult
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySourceResult.ImdsV1FailureReason.get -> string
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySourceResult.ImdsV1FailureReason.set -> void

src/client/Microsoft.Identity.Client/PublicApi/net472/PublicAPI.Unshipped.txt

@@ -1,4 +1,11 @@
 static Microsoft.Identity.Client.Extensibility.AbstractConfidentialClientAcquireTokenParameterBuilderExtension.WithExtraClientAssertionClaims<T>(this Microsoft.Identity.Client.AbstractAcquireTokenParameterBuilder<T> builder, string clientAssertionClaims) -> Microsoft.Identity.Client.AbstractAcquireTokenParameterBuilder<T>
 Microsoft.Identity.Client.ManagedIdentityPopExtensions
+Microsoft.Identity.Client.AppConfig.CertificateOptions
+Microsoft.Identity.Client.AppConfig.CertificateOptions.AssociateTokensWithCertificate.get -> bool
+Microsoft.Identity.Client.AppConfig.CertificateOptions.AssociateTokensWithCertificate.init -> void
+Microsoft.Identity.Client.AppConfig.CertificateOptions.SendX5C.get -> bool
+Microsoft.Identity.Client.AppConfig.CertificateOptions.SendX5C.init -> void
+Microsoft.Identity.Client.ConfidentialClientApplicationBuilder.WithCertificate(System.Security.Cryptography.X509Certificates.X509Certificate2 certificate, Microsoft.Identity.Client.AppConfig.CertificateOptions certificateOptions) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
+static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.WithCertificate(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, System.Threading.Tasks.Task<System.Security.Cryptography.X509Certificates.X509Certificate2>> certificateProvider, Microsoft.Identity.Client.AppConfig.CertificateOptions certificateOptions) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
 static Microsoft.Identity.Client.ManagedIdentityPopExtensions.WithMtlsProofOfPossession(this Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder builder) -> Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder
 Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder.WithAttributes(string attributeJson) -> Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder

src/client/Microsoft.Identity.Client/PublicApi/net8.0-android/PublicAPI.Shipped.txt

@@ -1075,7 +1075,6 @@ Microsoft.Identity.Client.Extensibility.ExecutionResult.Result.get -> Microsoft.
 Microsoft.Identity.Client.Extensibility.ExecutionResult.Successful.get -> bool
 static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.OnCompletion(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, Microsoft.Identity.Client.Extensibility.ExecutionResult, System.Threading.Tasks.Task> onCompletion) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
 static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.OnMsalServiceFailure(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, Microsoft.Identity.Client.Extensibility.ExecutionResult, System.Threading.Tasks.Task<bool>> onMsalServiceFailure) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
-static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.WithCertificate(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, System.Threading.Tasks.Task<System.Security.Cryptography.X509Certificates.X509Certificate2>> certificateProvider) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySourceResult
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySourceResult.ImdsV1FailureReason.get -> string
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySourceResult.ImdsV1FailureReason.set -> void

src/client/Microsoft.Identity.Client/PublicApi/net8.0-android/PublicAPI.Unshipped.txt

@@ -1,3 +1,10 @@
+Microsoft.Identity.Client.AppConfig.CertificateOptions
+Microsoft.Identity.Client.AppConfig.CertificateOptions.AssociateTokensWithCertificate.get -> bool
+Microsoft.Identity.Client.AppConfig.CertificateOptions.AssociateTokensWithCertificate.init -> void
+Microsoft.Identity.Client.AppConfig.CertificateOptions.SendX5C.get -> bool
+Microsoft.Identity.Client.AppConfig.CertificateOptions.SendX5C.init -> void
+Microsoft.Identity.Client.ConfidentialClientApplicationBuilder.WithCertificate(System.Security.Cryptography.X509Certificates.X509Certificate2 certificate, Microsoft.Identity.Client.AppConfig.CertificateOptions certificateOptions) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
+static Microsoft.Identity.Client.Extensibility.ConfidentialClientApplicationBuilderExtensions.WithCertificate(this Microsoft.Identity.Client.ConfidentialClientApplicationBuilder builder, System.Func<Microsoft.Identity.Client.AssertionRequestOptions, System.Threading.Tasks.Task<System.Security.Cryptography.X509Certificates.X509Certificate2>> certificateProvider, Microsoft.Identity.Client.AppConfig.CertificateOptions certificateOptions) -> Microsoft.Identity.Client.ConfidentialClientApplicationBuilder
 static Microsoft.Identity.Client.Extensibility.AbstractConfidentialClientAcquireTokenParameterBuilderExtension.WithExtraClientAssertionClaims<T>(this Microsoft.Identity.Client.AbstractAcquireTokenParameterBuilder<T> builder, string clientAssertionClaims) -> Microsoft.Identity.Client.AbstractAcquireTokenParameterBuilder<T>
 Microsoft.Identity.Client.ManagedIdentityPopExtensions
 static Microsoft.Identity.Client.ManagedIdentityPopExtensions.WithMtlsProofOfPossession(this Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder builder) -> Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder