MtlsPopParametersInitializer.cs

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

using System.Threading;
using System.Threading.Tasks;
using System.Security.Cryptography.X509Certificates;
using Microsoft.Identity.Client.AppConfig;
using Microsoft.Identity.Client.AuthScheme;
using Microsoft.Identity.Client.AuthScheme.PoP;
using Microsoft.Identity.Client.Instance;
using Microsoft.Identity.Client.Internal;
using Microsoft.Identity.Client.Internal.ClientCredential;
using Microsoft.Identity.Client.TelemetryCore;

namespace Microsoft.Identity.Client.ApiConfig.Parameters
{
    /// <summary>
    /// Encapsulates the mTLS/PoP initialization logic for token requests.
    /// Keeps AcquireTokenCommonParameters lean and makes the init logic testable in isolation.
    /// </summary>
    internal static class MtlsPopParametersInitializer
    {
        internal static async Task TryInitAsync(
            AcquireTokenCommonParameters p,
            IServiceBundle serviceBundle,
            CancellationToken ct)
        {
            if (p.IsMtlsPopRequested)
            {
                await InitExplicitMtlsPopAsync(p, serviceBundle, ct).ConfigureAwait(false);
                return;
            }

            await TryInitImplicitBearerOverMtlsAsync(p, serviceBundle, ct).ConfigureAwait(false);
        }

        /// <summary>
        /// NON-PoP request:
        /// We may still need mTLS transport in two situations:
        /// Case 1 – The app-level SendCertificateOverMtls option is set and the credential is certificate-based
        ///          (both static <see cref="CertificateClientCredential"/> and dynamic
        ///          <see cref="DynamicCertificateClientCredential"/> are supported).
        /// Case 2 – The credential is a signed-assertion provider that returns a TokenBindingCertificate.
        /// </summary>
        private static async Task TryInitImplicitBearerOverMtlsAsync(
            AcquireTokenCommonParameters tokenParameters,
            IServiceBundle serviceBundle,
            CancellationToken ct)
        {
            if (tokenParameters.MtlsCertificate != null)
            {
                return;
            }

            // Case 1 – App opted into mTLS Bearer via SendCertificateOverMtls on a certificate-based credential.
            if (serviceBundle.Config.CertificateOptions?.SendCertificateOverMtls == true &&
                serviceBundle.Config.ClientCredential is CertificateAndClaimsClientCredential certBasedCred)
            {
                // Static credentials have Certificate set directly
                tokenParameters.MtlsCertificate = certBasedCred.Certificate
                    ?? await certBasedCred.ResolveCertificateForMtlsAsync(
                           CreateAssertionRequestOptions(tokenParameters, serviceBundle, ct))
                       .ConfigureAwait(false);

                return;
            }

            // Case 2 – Only cert-capable credentials implement this capability interface.
            // No SendCertificateOverMtls guard here: the TokenBindingCertificate pattern is a
            // distinct opt-in where the assertion delegate itself signals mTLS intent by returning
            // a non-null cert. This is separate from Case 1 (SendCertificateOverMtls + cert-based
            // credential).
            //
            // Call pattern per request:
            //   - This call always fires (even cache hits) to check for TokenBindingCertificate
            //     and set MtlsCertificate for proper endpoint routing.
            //   - GetCredentialMaterialAsync (in ClientAssertionDelegateCredential) calls the
            //     delegate a second time on network requests to produce the signed assertion JWT.
            //   - Cache hits: delegate called once (here only). Network requests: twice.
            //   - Delegates are expected to be cheap (return a pre-generated/cached assertion).
            if (serviceBundle.Config.ClientCredential is IClientSignedAssertionProvider signedProvider)
            {
                var opts = CreateAssertionRequestOptions(tokenParameters, serviceBundle, ct);

                ClientSignedAssertion ar =
                    await signedProvider.GetAssertionAsync(opts, ct).ConfigureAwait(false);

                if (ar?.TokenBindingCertificate != null)
                {
                    tokenParameters.MtlsCertificate = ar.TokenBindingCertificate;
                }
            }
        }

        /// <summary>
        /// EXPLICIT PoP requested:
        /// Validate and initialize PoP parameters (auth scheme + cert + region check).
        /// </summary>
        private static async Task InitExplicitMtlsPopAsync(
            AcquireTokenCommonParameters p,
            IServiceBundle serviceBundle,
            CancellationToken ct)
        {
            // Case 1 – Certificate credential
            if (serviceBundle.Config.ClientCredential is CertificateClientCredential certCred)
            {
                if (certCred.Certificate == null)
                {
                    throw new MsalClientException(
                        MsalError.MtlsCertificateNotProvided,
                        MsalErrorMessage.MtlsCertificateNotProvidedMessage);
                }

                await InitMtlsPopParametersAsync(p, certCred.Certificate, serviceBundle, ct).ConfigureAwait(false);
                return;
            }

            // Case 2 – Signed assertion provider (JWT + optional cert)
            if (serviceBundle.Config.ClientCredential is IClientSignedAssertionProvider signedProvider)
            {
                var opts = CreateAssertionRequestOptions(p, serviceBundle, ct);

                ClientSignedAssertion ar =
                    await signedProvider.GetAssertionAsync(opts, ct).ConfigureAwait(false);

                if (ar?.TokenBindingCertificate == null)
                {
                    throw new MsalClientException(
                        MsalError.MtlsCertificateNotProvided,
                        MsalErrorMessage.MtlsCertificateNotProvidedMessage);
                }

                await InitMtlsPopParametersAsync(p, ar.TokenBindingCertificate, serviceBundle, ct).ConfigureAwait(false);
                return;
            }

            // Case 3 – Any other credential (client-secret etc.)
            throw new MsalClientException(
                MsalError.MtlsCertificateNotProvided,
                MsalErrorMessage.MtlsCertificateNotProvidedMessage);
        }

        private static AssertionRequestOptions CreateAssertionRequestOptions(
            AcquireTokenCommonParameters p,
            IServiceBundle serviceBundle,
            CancellationToken ct)
        {
            return new AssertionRequestOptions
            {
                ClientID = serviceBundle.Config.ClientId,
                ClientCapabilities = serviceBundle.Config.ClientCapabilities,
                Claims = p.Claims,
                CancellationToken = ct,
                ClientAssertionFmiPath = p.ClientAssertionFmiPath,
                CorrelationId = p.CorrelationId,

                // Best-effort context. IMPORTANT: use AbsoluteUri, not Uri.Authority (host only).
                TokenEndpoint = serviceBundle.Config.Authority.AuthorityInfo.CanonicalAuthority.AbsoluteUri
            };
        }

        private static async Task InitMtlsPopParametersAsync(
            AcquireTokenCommonParameters p,
            X509Certificate2 cert,
            IServiceBundle serviceBundle,
            CancellationToken ct = default)
        {
            // AAD only validation
            if (serviceBundle.Config.Authority.AuthorityInfo.AuthorityType == AuthorityType.Aad)
            {
                string tenant = AuthorityInfo.GetFirstPathSegment(serviceBundle.Config.Authority.AuthorityInfo.CanonicalAuthority);
                if (AadAuthority.IsCommonOrOrganizationsTenant(tenant))
                {
                    throw new MsalClientException(
                        MsalError.MissingTenantedAuthority,
                        MsalErrorMessage.MtlsNonTenantedAuthorityNotAllowedMessage);
                }
            }

            // If the current operation supports the AfterCredentialEvaluation lifecycle hook,
            // invoke it with the cert instead of replacing the operation. This enables
            // composition (e.g., CDT + mTLS POP) where the operation handles both concerns.
            if (p.AuthenticationOperation is IAuthenticationOperation3 op3)
            {
                await op3.AfterCredentialEvaluationAsync(new CredentialEvaluationContext(cert), ct).ConfigureAwait(false);
                p.MtlsCertificate = cert;
                return;
            }

            p.AuthenticationOperation = new MtlsPopAuthenticationOperation(cert);
            p.MtlsCertificate = cert;
        }

    }
}