Table of Contents

Class ConfidentialClientApplicationBuilder

Namespace
Microsoft.Identity.Client
Assembly
Microsoft.Identity.Client.dll
public class ConfidentialClientApplicationBuilder : AbstractApplicationBuilder<ConfidentialClientApplicationBuilder>
Inheritance
ConfidentialClientApplicationBuilder
Inherited Members
Extension Methods

Methods

Build()

Builds an instance of IConfidentialClientApplication from the parameters set in the ConfidentialClientApplicationBuilder.

public IConfidentialClientApplication Build()

Returns

IConfidentialClientApplication

An instance of IConfidentialClientApplication

Exceptions

MsalClientException

Thrown when errors occur locally in the library itself (for example, because of incorrect configuration).

Create(string)

Creates a ConfidentialClientApplicationBuilder from a clientID. See https://aka.ms/msal-net-application-configuration

public static ConfidentialClientApplicationBuilder Create(string clientId)

Parameters

clientId string

Client ID (also known as App ID) of the application as registered in the application registration portal (https://aka.ms/msal-net-register-app)/.

Returns

ConfidentialClientApplicationBuilder

A ConfidentialClientApplicationBuilder from which to set more parameters, and to create a confidential client application instance

CreateWithApplicationOptions(ConfidentialClientApplicationOptions)

Constructor of a ConfidentialClientApplicationBuilder from application configuration options. See https://aka.ms/msal-net-application-configuration

public static ConfidentialClientApplicationBuilder CreateWithApplicationOptions(ConfidentialClientApplicationOptions options)

Parameters

options ConfidentialClientApplicationOptions

Confidential client applications configuration options

Returns

ConfidentialClientApplicationBuilder

A ConfidentialClientApplicationBuilder from which to set more parameters, and to create a confidential client application instance

WithAzureRegion(string)

Instructs MSAL to use an Azure regional token service. This feature is currently available to first-party applications only.

public ConfidentialClientApplicationBuilder WithAzureRegion(string azureRegion = "TryAutoDetect")

Parameters

azureRegion string

Either the string with the region (preferred) or
use AttemptRegionDiscovery and MSAL will attempt to auto-detect the region.

Returns

ConfidentialClientApplicationBuilder

The builder to chain the .With methods

Remarks

The region value should be a short region name for the region where the service is deployed. For example, "centralus" is short name for region Central US. Currently only tokens for the client credential flow can be obtained from the regional service. Requires configuration at the tenant level. Auto-detection works on a limited number of Azure artifacts (VMs, Azure functions). If auto-detection fails, the non-regional endpoint will be used. If a specific region was provided and the token web request failed, verify that the region name is valid. See https://aka.ms/msal-net-region-discovery for more details.

WithCacheSynchronization(bool)

When set to true, MSAL will lock cache access at the ConfidentialClientApplication level, i.e. the block of code between BeforeAccessAsync and AfterAccessAsync callbacks will be synchronized. Apps can set this flag to false to enable an optimistic cache locking strategy, which may result in better performance at the cost of cache consistency. Setting this flag to false is only recommended for apps which create a new ConfidentialClientApplication per request.

public ConfidentialClientApplicationBuilder WithCacheSynchronization(bool enableCacheSynchronization)

Parameters

enableCacheSynchronization bool

Returns

ConfidentialClientApplicationBuilder

Remarks

This flag is true by default. The default behavior is recommended.

WithCertificate(X509Certificate2)

Sets the certificate associated with the application.

public ConfidentialClientApplicationBuilder WithCertificate(X509Certificate2 certificate)

Parameters

certificate X509Certificate2

The X509 certificate used as credentials to prove the identity of the application to Azure AD.

Returns

ConfidentialClientApplicationBuilder

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. Does not send the certificate (as x5c parameter) with the request by default.

WithCertificate(X509Certificate2, bool)

Sets the certificate associated with the application. Applicable to first-party applications only, this method also allows to specify if the x5c claim 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

public ConfidentialClientApplicationBuilder WithCertificate(X509Certificate2 certificate, bool sendX5C)

Parameters

certificate X509Certificate2

The X509 certificate used as credentials to prove the identity of the application to Azure AD.

sendX5C bool

To send X5C with every request or not. The default is false

Returns

ConfidentialClientApplicationBuilder

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.

WithClientAssertion(Func<AssertionRequestOptions, Task<string>>)

Configures an async delegate that creates a client assertion. The delegate is invoked only when a token cannot be retrieved from the cache. See https://aka.ms/msal-net-client-assertion

public ConfidentialClientApplicationBuilder WithClientAssertion(Func<AssertionRequestOptions, Task<string>> clientAssertionAsyncDelegate)

Parameters

clientAssertionAsyncDelegate Func<AssertionRequestOptions, Task<string>>

An async delegate that returns the client assertion. Assertion lifetime is the responsibility of the caller.

Returns

ConfidentialClientApplicationBuilder

The ConfidentialClientApplicationBuilder to chain more .With methods

Remarks

Callers can use this mechanism to cache their assertions

WithClientClaims(X509Certificate2, IDictionary<string, string>, bool)

Sets the certificate associated with the application along with the specific claims to sign. By default, this will merge the claimsToSign with the default required set of claims needed for authentication. If mergeWithDefaultClaims is set to false, you will need to provide the required default claims. See https://aka.ms/msal-net-client-assertion

public ConfidentialClientApplicationBuilder WithClientClaims(X509Certificate2 certificate, IDictionary<string, string> claimsToSign, bool mergeWithDefaultClaims)

Parameters

certificate X509Certificate2

The X509 certificate used as credentials to prove the identity of the application to Azure AD.

claimsToSign IDictionary<string, string>

The claims to be signed by the provided certificate.

mergeWithDefaultClaims bool

Determines whether or not to merge claimsToSign with the default claims required for authentication.

Returns

ConfidentialClientApplicationBuilder

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. Does not send the certificate (as x5c parameter) with the request by default.

WithClientClaims(X509Certificate2, IDictionary<string, string>, bool, bool)

Sets the certificate associated with the application along with the specific claims to sign. By default, this will merge the claimsToSign with the default required set of claims needed for authentication. If mergeWithDefaultClaims is set to false, you will need to provide the required default claims. See https://aka.ms/msal-net-client-assertion

public ConfidentialClientApplicationBuilder WithClientClaims(X509Certificate2 certificate, IDictionary<string, string> claimsToSign, bool mergeWithDefaultClaims = true, bool sendX5C = false)

Parameters

certificate X509Certificate2

The X509 certificate used as credentials to prove the identity of the application to Azure AD.

claimsToSign IDictionary<string, string>

The claims to be signed by the provided certificate.

mergeWithDefaultClaims bool

Determines whether or not to merge claimsToSign with the default claims required for authentication.

sendX5C bool

To send X5C with every request or not.

Returns

ConfidentialClientApplicationBuilder

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.

WithClientSecret(string)

Sets the application secret

public ConfidentialClientApplicationBuilder WithClientSecret(string clientSecret)

Parameters

clientSecret string

Secret string previously shared with AAD at application registration to prove the identity of the application (the client) requesting the tokens

Returns

ConfidentialClientApplicationBuilder

WithOidcAuthority(string)

Adds a known authority corresponding to a generic OpenIdConnect Identity Provider. MSAL will append ".well-known/openid-configuration" to the authority and retrieve the OIDC metadata from there, to figure out the endpoints. See https://openid.net/specs/openid-connect-core-1_0.html#Terminology

public ConfidentialClientApplicationBuilder WithOidcAuthority(string authorityUri)

Parameters

authorityUri string

Returns

ConfidentialClientApplicationBuilder

Remarks

Do not use this method with Entra ID authorities (e.g. https://login.microsfoftonline.com/common). Use WithAuthority(string) instead.