Table of Contents

Class AbstractApplicationBuilder<T>

Namespace
Microsoft.Identity.Client
Assembly
Microsoft.Identity.Client.dll
public abstract class AbstractApplicationBuilder<T> : BaseAbstractApplicationBuilder<T> where T : BaseAbstractApplicationBuilder<T>

Type Parameters

T
Inheritance
AbstractApplicationBuilder<T>
Derived
Inherited Members

Methods

WithAdfsAuthority(string, bool)

Adds a known Authority corresponding to an ADFS server. See https://aka.ms/msal-net-adfs

public T WithAdfsAuthority(string authorityUri, bool validateAuthority = true)

Parameters

authorityUri string

Authority URL for an ADFS server

validateAuthority bool

Whether the authority should be validated against the server metadata.

Returns

T

The builder to chain the .With methods

Remarks

MSAL.NET will only support ADFS 2019 or later.

WithAuthority(AadAuthorityAudience, bool)

Adds a known Azure AD authority to the application to sign-in users specifying the sign-in audience (the cloud being the Azure public cloud). See https://aka.ms/msal-net-application-configuration.

public T WithAuthority(AadAuthorityAudience authorityAudience, bool validateAuthority = true)

Parameters

authorityAudience AadAuthorityAudience

Sign-in audience (one AAD organization, any work and school accounts, or any work and school accounts and Microsoft personal accounts

validateAuthority bool

Whether the authority should be validated against the server metadata.

Returns

T

The builder to chain the .With methods

WithAuthority(AzureCloudInstance, AadAuthorityAudience, bool)

Adds a known Azure AD authority to the application to sign-in users specifying the cloud instance and the sign-in audience. See https://aka.ms/msal-net-application-configuration.

public T WithAuthority(AzureCloudInstance azureCloudInstance, AadAuthorityAudience authorityAudience, bool validateAuthority = true)

Parameters

azureCloudInstance AzureCloudInstance

Instance of Azure Cloud (for instance Azure worldwide cloud, Azure German Cloud, US government ...)

authorityAudience AadAuthorityAudience

Sign-in audience (one AAD organization, any work and school accounts, or any work and school accounts and Microsoft personal accounts

validateAuthority bool

Whether the authority should be validated against the server metadata.

Returns

T

The builder to chain the .With methods

WithAuthority(AzureCloudInstance, Guid, bool)

Adds a known Azure AD authority to the application to sign-in users from a single organization (single tenant application) described by its cloud instance and its tenant ID. See https://aka.ms/msal-net-application-configuration.

public T WithAuthority(AzureCloudInstance azureCloudInstance, Guid tenantId, bool validateAuthority = true)

Parameters

azureCloudInstance AzureCloudInstance

Instance of Azure cloud (for example, Azure public cloud, Azure China, or Azure Government).

tenantId Guid

Tenant Id of the tenant from which to sign-in users

validateAuthority bool

Whether the authority should be validated against the server metadata.

Returns

T

The builder to chain the .With methods

WithAuthority(AzureCloudInstance, string, bool)

Adds a known Azure AD authority to the application to sign-in users from a single organization (single-tenant application) described by its cloud instance and its domain name or tenant ID. See https://aka.ms/msal-net-application-configuration.

public T WithAuthority(AzureCloudInstance azureCloudInstance, string tenant, bool validateAuthority = true)

Parameters

azureCloudInstance AzureCloudInstance

Instance of Azure cloud (for example, Azure public cloud, Azure China, or Azure Government).

tenant string

Domain name associated with the Azure AD tenant from which to sign-in users. This can also be a GUID.

validateAuthority bool

Whether the authority should be validated against the server metadata.

Returns

T

The builder to chain the .With methods.

Exceptions

ArgumentNullException

Thrown if tenant or tenant is null or empty.

WithAuthority(string, bool)

Adds a known Azure AD authority to the application to sign-in users specifying the full authority URI. See Application configuration options.

public T WithAuthority(string authorityUri, bool validateAuthority = true)

Parameters

authorityUri string

URI of the authority from which MSAL.NET will acquire the tokens. Authority endpoints for the Azure public Cloud are:

  • https://login.microsoftonline.com/tenant/ where tenant is the tenant ID of the Azure AD tenant or a domain associated with this Azure AD tenant, in order to sign-in users of a specific organization only
  • https://login.microsoftonline.com/common/ to sign-in users with any work and school accounts or personal Microsoft accounts
  • https://login.microsoftonline.com/organizations/ to sign-in users with any work and school accounts
  • https://login.microsoftonline.com/consumers/ to sign-in users with only personal Microsoft accounts (live)
Note that this setting needs to be consistent with what is declared in the application registration portal
validateAuthority bool

Whether the authority should be validated against the server metadata.

Returns

T

The builder to chain the .With methods

Exceptions

ArgumentNullException

Thrown if authorityUri is null or empty.

ArgumentException

Thrown if authorityUri is not well-formatted (for example, has spaces).

MsalClientException

Thrown in general exception scenarios (for example if the application was configured with multiple different authority hosts).

WithAuthority(string, Guid, bool)

Adds a known Azure AD authority to the application to sign-in users from a single organization (single-tenant application) specified by its tenant ID. See Application configuration options.

public T WithAuthority(string cloudInstanceUri, Guid tenantId, bool validateAuthority = true)

Parameters

cloudInstanceUri string

Azure cloud instance.

tenantId Guid

GUID of the tenant from which to sign-in users.

validateAuthority bool

Whether the authority should be validated against the server metadata.

Returns

T

The builder to chain the .With methods.

Exceptions

ArgumentNullException

Thrown if cloudInstanceUri is null or empty.

ArgumentException

Thrown if cloudInstanceUri is not well-formatted (for example, has spaces).

MsalClientException

Thrown in more general exception scenarios (for example if the application was configured with multiple different authority hosts).

WithAuthority(string, string, bool)

Adds a known Azure AD authority to the application to sign-in users from a single organization (single-tenant application) described by its domain name. See https://aka.ms/msal-net-application-configuration.

public T WithAuthority(string cloudInstanceUri, string tenant, bool validateAuthority = true)

Parameters

cloudInstanceUri string

Uri to the Azure cloud instance (for instance https://login.microsoftonline.com)

tenant string

Domain name associated with the tenant from which to sign-in users

validateAuthority bool

Whether the authority should be validated against the server metadata.

Returns

T

The builder to chain the .With methods

Remarks

tenant can also contain the string representation of a GUID (tenantId), or even common, organizations or consumers but in this case it's recommended to use another override (WithAuthority(AzureCloudInstance, Guid, bool) and WithAuthority(AzureCloudInstance, AadAuthorityAudience, bool)

Exceptions

ArgumentNullException

Thrown if cloudInstanceUri or tenant is null or empty.

ArgumentException

Thrown if cloudInstanceUri or tenant is not well-formatted (for example, has spaces).

MsalClientException

Thrown in more general exception scenarios (for example if the application was configured with multiple different authority hosts).

WithAuthority(Uri, bool)

Adds a known authority to the application. See Application configuration options. This constructor is mainly used for scenarios where the authority is not a standard Azure AD authority, nor an ADFS authority, nor an Azure AD B2C authority. For Azure AD, even in sovereign clouds, prefer using other overrides such as WithAuthority(AzureCloudInstance, AadAuthorityAudience, bool)

public T WithAuthority(Uri authorityUri, bool validateAuthority = true)

Parameters

authorityUri Uri

URI of the authority

validateAuthority bool

Whether the authority should be validated against the server metadata.

Returns

T

The builder to chain the .With methods

Exceptions

ArgumentNullException

Thrown if authorityUri is null.

ArgumentException

Thrown if authorityUri is not well-formatted (for example, has spaces).

MsalClientException

Thrown in general exception scenarios (for example if the application was configured with multiple different authority hosts).

WithB2CAuthority(string)

Adds a known authority corresponding to an Azure AD B2C policy. See https://aka.ms/msal-net-b2c-specificities

public T WithB2CAuthority(string authorityUri)

Parameters

authorityUri string

Azure AD B2C authority, including the B2C policy (for instance "https://fabrikamb2c.b2clogin.com/tfp/{Tenant}/{policy}

Returns

T

The builder to chain the .With methods

WithCacheOptions(CacheOptions)

Options for MSAL token caches.

MSAL maintains a token cache internally in memory. By default, this cache object is part of each instance of PublicClientApplication or ConfidentialClientApplication. This method allows customization of the in-memory token cache of MSAL.

MSAL's memory cache is different than token cache serialization. Cache serialization pulls the tokens from a cache (e.g. Redis, Cosmos, or a file on disk), where they are stored in JSON format, into MSAL's internal memory cache. Memory cache operations do not involve JSON operations.

External cache serialization remains the recommended way to handle desktop apps, web site and web APIs, as it provides persistence. These options do not currently control external cache serialization.

Detailed guidance for each application type and platform: https://aka.ms/msal-net-token-cache-serialization

public T WithCacheOptions(CacheOptions options)

Parameters

options CacheOptions

Options for the internal MSAL token caches.

Returns

T

WithClientCapabilities(IEnumerable<string>)

Microsoft Identity specific OIDC extension that allows resource challenges to be resolved without interaction. Allows configuration of one or more client capabilities, e.g. "llt"

public T WithClientCapabilities(IEnumerable<string> clientCapabilities)

Parameters

clientCapabilities IEnumerable<string>

Returns

T

Remarks

MSAL will transform these into special claims request. See https://openid.net/specs/openid-connect-core-1_0-final.html#ClaimsParameter for details on claim requests. For more details see https://aka.ms/msal-net-claims-request

WithClientId(string)

Sets the Client ID of the application

public T WithClientId(string clientId)

Parameters

clientId string

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

Returns

T

The builder to chain the .With methods

WithExtraQueryParameters(IDictionary<string, string>)

Sets Extra Query Parameters for the query string in the HTTP authentication request

public T WithExtraQueryParameters(IDictionary<string, string> extraQueryParameters)

Parameters

extraQueryParameters IDictionary<string, string>

This parameter will be appended as is to the query string in the HTTP authentication request to the authority as a string of segments of the form key=value separated by an ampersand character. The parameter can be null.

Returns

T

The builder to chain the .With methods

WithExtraQueryParameters(string)

Sets Extra Query Parameters for the query string in the HTTP authentication request

public T WithExtraQueryParameters(string extraQueryParameters)

Parameters

extraQueryParameters string

This parameter will be appended as is to the query string in the HTTP authentication request to the authority. The string needs to be properly URL-encoded and ready to send as a string of segments of the form key=value separated by an ampersand character.

Returns

T

WithInstanceDiscovery(bool)

Determines whether or not instance discovery is performed when attempting to authenticate. Setting this to false will completely disable instance discovery and authority validation. This will not affect the behavior of application configured with regional endpoints however.

public T WithInstanceDiscovery(bool enableInstanceDiscovery)

Parameters

enableInstanceDiscovery bool

Determines if instance discovery/Authority validation is performed

Returns

T

Remarks

If instance discovery is disabled and no user metadata is provided, MSAL will use the provided authority without any checks. WithInstanceDiscoveryMetadata(string) takes priority over enableInstanceDiscovery so instance metadata can be provided regardless of this configuration.

WithInstanceDiscoveryMetadata(string)

Allows developers to configure their own valid authorities. A json string similar to https://aka.ms/aad-instance-discovery should be provided. MSAL uses this information to:

  • Call REST APIs on the environment specified in the preferred_network
  • Identify an environment under which to save tokens and accounts in the cache
  • Use the environment aliases to match tokens issued to other authorities
For more details see https://aka.ms/msal-net-custom-instance-metadata 
public T WithInstanceDiscoveryMetadata(string instanceDiscoveryJson)

Parameters

instanceDiscoveryJson string

Returns

T

Remarks

Developers take responsibility for authority validation if they use this method. Should not be used when the authority is not known in advance. Has no effect on ADFS or B2C authorities, only for AAD authorities

WithInstanceDiscoveryMetadata(Uri)

Lets an organization setup their own service to handle instance discovery, which enables better caching for microservice/service environments. A Uri that returns a response similar to https://aka.ms/aad-instance-discovery should be provided. MSAL uses this information to:

  • Call REST APIs on the environment specified in the preferred_network
  • Identify an environment under which to save tokens and accounts in the cache
  • Use the environment aliases to match tokens issued to other authorities
For more details see https://aka.ms/msal-net-custom-instance-metadata 
public T WithInstanceDiscoveryMetadata(Uri instanceDiscoveryUri)

Parameters

instanceDiscoveryUri Uri

Returns

T

Remarks

Developers take responsibility for authority validation if they use this method. Should not be used when the authority is not known in advance. Has no effect on ADFS or B2C authorities, only for AAD authorities

WithLegacyCacheCompatibility(bool)

Enables legacy ADAL cache serialization and deserialization.

public T WithLegacyCacheCompatibility(bool enableLegacyCacheCompatibility = true)

Parameters

enableLegacyCacheCompatibility bool

Enable legacy ADAL cache compatibility.

Returns

T

The builder to chain the .With methods.

Remarks

ADAL is a previous legacy generation of MSAL.NET authentication library. If you don't use .WithLegacyCacheCompatibility(false), then by default, the ADAL cache is used (along with MSAL cache). true flag is only needed for specific migration scenarios from ADAL.NET to MSAL.NET when both library versions are running side-by-side. To improve performance add .WithLegacyCacheCompatibility(false) unless you care about migration scenarios.

WithOptions(ApplicationOptions)

Sets application options, which can, for instance have been read from configuration files. See https://aka.ms/msal-net-application-configuration.

protected T WithOptions(ApplicationOptions applicationOptions)

Parameters

applicationOptions ApplicationOptions

Application options

Returns

T

The builder to chain the .With methods

WithRedirectUri(string)

Sets the redirect URI of the application. The URI must also be registered in the application portal. See https://aka.ms/msal-net-application-configuration

public T WithRedirectUri(string redirectUri)

Parameters

redirectUri string

URL where the STS will call back the application with the security token. Public Client Applications - desktop, mobile, console apps - use different browsers (system browser, embedded browses) and brokers and each has its own rules.

Returns

T

The builder to chain the .With methods

WithTenantId(string)

Sets the tenant ID of the organization from which the application will let users sign-in. This is classically a GUID or a domain name. See https://aka.ms/msal-net-application-configuration. Although it is also possible to set tenantId to common, organizations, and consumers, it's recommended to use one of the overrides of WithAuthority(AzureCloudInstance, AadAuthorityAudience, bool).

public T WithTenantId(string tenantId)

Parameters

tenantId string

tenant ID of the Azure AD tenant or a domain associated with this Azure AD tenant, in order to sign-in a user of a specific organization only

Returns

T

The builder to chain the .With methods