PublicClientApplicationBuilder Class

Definition

public sealed class PublicClientApplicationBuilder : Microsoft.Identity.Client.AbstractApplicationBuilder<Microsoft.Identity.Client.PublicClientApplicationBuilder>
type PublicClientApplicationBuilder = class
    inherit AbstractApplicationBuilder<PublicClientApplicationBuilder>
Public NotInheritable Class PublicClientApplicationBuilder
Inherits AbstractApplicationBuilder(Of PublicClientApplicationBuilder)
Inheritance

Methods

Build()

Builds an instance of IPublicClientApplication from the parameters set in the PublicClientApplicationBuilder.

Create(String)

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

CreateWithApplicationOptions(PublicClientApplicationOptions)

Creates a PublicClientApplicationBuilder from public client application configuration options. See https://aka.ms/msal-net-application-configuration

IsBrokerAvailable()

Returns true if a broker can be used. This method is only needed to be used in mobile scenarios which support Mobile Application Management. In other supported scenarios, use WithBroker by itself, which will fall back to use a browser if broker is unavailable.

WithAdfsAuthority(String, Boolean)

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

(Inherited from AbstractApplicationBuilder<T>)
WithAuthority(AadAuthorityAudience, Boolean)

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.

(Inherited from AbstractApplicationBuilder<T>)
WithAuthority(AzureCloudInstance, AadAuthorityAudience, Boolean)

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.

(Inherited from AbstractApplicationBuilder<T>)
WithAuthority(AzureCloudInstance, Guid, Boolean)

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.

(Inherited from AbstractApplicationBuilder<T>)
WithAuthority(AzureCloudInstance, String, Boolean)

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.

(Inherited from AbstractApplicationBuilder<T>)
WithAuthority(String, Boolean)

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

(Inherited from AbstractApplicationBuilder<T>)
WithAuthority(String, Guid, Boolean)

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.

(Inherited from AbstractApplicationBuilder<T>)
WithAuthority(String, String, Boolean)

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.

(Inherited from AbstractApplicationBuilder<T>)
WithAuthority(Uri, Boolean)

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, Boolean)

(Inherited from AbstractApplicationBuilder<T>)
WithB2CAuthority(String)

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

(Inherited from AbstractApplicationBuilder<T>)
WithBroker(Boolean)

Brokers enable Single-Sign-On, device identification, and application identification verification. To enable one of these features, you need to set the WithBroker() parameters to true. See https://aka.ms/msal-net-wam for more information on platform specific settings required to enable the broker.

On iOS and Android, Authenticator and Company Portal serve as brokers. On Windows, WAM (Windows Account Manager) serves as broker. See https://aka.ms/msal-net-wam

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

(Inherited from AbstractApplicationBuilder<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"

(Inherited from AbstractApplicationBuilder<T>)
WithClientId(String)

Sets the Client ID of the application

(Inherited from AbstractApplicationBuilder<T>)
WithClientName(String)

Sets the name of the calling application for telemetry purposes.

(Inherited from AbstractApplicationBuilder<T>)
WithClientVersion(String)

Sets the version of the calling application for telemetry purposes.

(Inherited from AbstractApplicationBuilder<T>)
WithDebugLoggingCallback(LogLevel, Boolean, Boolean)

Sets the Debug logging callback to a default debug method which displays the level of the message and the message itself. For details see https://aka.ms/msal-net-logging

(Inherited from BaseAbstractApplicationBuilder<T>)
WithDefaultRedirectUri()

Configures the public client application to use the recommended reply URI for the platform. See https://aka.ms/msal-net-default-reply-uri.

Platform
.NET desktop
UWP
For system browser on .NET Core
NOTE:There will be an update to the default redirect URI in the future to accommodate for system browsers on the .NET desktop and .NET Core platforms.
WithExperimentalFeatures(Boolean)

Allows usage of experimental features and APIs. If this flag is not set, experimental features will throw an exception. For details see https://aka.ms/msal-net-experimental-features

(Inherited from BaseAbstractApplicationBuilder<T>)
WithExtraQueryParameters(IDictionary<String,String>)

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

(Inherited from AbstractApplicationBuilder<T>)
WithExtraQueryParameters(String)

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

(Inherited from AbstractApplicationBuilder<T>)
WithHttpClientFactory(IMsalHttpClientFactory)

Uses a specific IMsalHttpClientFactory to communicate with the IdP. This enables advanced scenarios such as setting a proxy, or setting the Agent.

(Inherited from BaseAbstractApplicationBuilder<T>)
WithHttpClientFactory(IMsalHttpClientFactory, Boolean)

Uses a specific IMsalHttpClientFactory to communicate with the IdP. This enables advanced scenarios such as setting a proxy, or setting the Agent.

(Inherited from BaseAbstractApplicationBuilder<T>)
WithInstanceDicoveryMetadata(String)
Obsolete.

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 (Inherited from AbstractApplicationBuilder<T>)
WithInstanceDicoveryMetadata(Uri)
Obsolete.

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 (Inherited from AbstractApplicationBuilder<T>)
WithInstanceDiscovery(Boolean)

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.

(Inherited from AbstractApplicationBuilder<T>)
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 (Inherited from AbstractApplicationBuilder<T>)
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 (Inherited from AbstractApplicationBuilder<T>)
WithIosKeychainSecurityGroup(String)

You can specify a Keychain Access Group to use for persisting the token cache across multiple applications. This enables you to share the token cache between several applications having the same Keychain access group. Sharing the token cache allows single sign-on between all of the applications that use the same Keychain access Group. See https://aka.ms/msal-net-ios-keychain-security-group for more information.

WithKerberosTicketClaim(String, KerberosTicketContainer)

Sets the parameters required to get a Kerberos Ticket from Azure AD service.

WithLegacyCacheCompatibility(Boolean)

Enables legacy ADAL cache serialization and deserialization.

(Inherited from AbstractApplicationBuilder<T>)
WithLogging(IIdentityLogger, Boolean)

Sets the Identity Logger. For details see https://aka.ms/msal-net-logging

(Inherited from BaseAbstractApplicationBuilder<T>)
WithLogging(LogCallback, Nullable<LogLevel>, Nullable<Boolean>, Nullable<Boolean>)

Sets the logging callback. For details see https://aka.ms/msal-net-logging

(Inherited from BaseAbstractApplicationBuilder<T>)
WithMultiCloudSupport(Boolean)

Enables multi cloud support for this instance of public client application. It enables applications to use in a global public cloud authority to the library and can still get tokens for resources from sovereign clouds.

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

WithOptions(ApplicationOptions)

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

(Inherited from AbstractApplicationBuilder<T>)
WithOptions(BaseApplicationOptions)

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

(Inherited from BaseAbstractApplicationBuilder<T>)
WithParentActivityOrWindow(Func<IntPtr>)

Sets a reference to the IntPtr to a window that triggers the browser to be shown. Used to center the browser that pop-up onto this window.

WithParentActivityOrWindow(Func<Object>)

Sets a reference to the ViewController (if using Xamarin.iOS), Activity (if using Xamarin.Android) IWin32Window or IntPtr (if using .Net Framework). Used for invoking the browser.

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

(Inherited from AbstractApplicationBuilder<T>)
WithTelemetry(ITelemetryConfig)
Obsolete.

Generate telemetry aggregation events.

(Inherited from AbstractApplicationBuilder<T>)
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, Boolean).

(Inherited from AbstractApplicationBuilder<T>)
WithWindowsBrokerOptions(WindowsBrokerOptions)
Obsolete.

Allows customization of the Windows 10 Broker experience.

Extension Methods

WithBroker(PublicClientApplicationBuilder, BrokerOptions)

Brokers enable Single-Sign-On, device identification,and application identification verification, while increasing the security of applications. Use this API to enable brokers on desktop platforms.

See https://aka.ms/msal-net-wam for more information on platform specific settings required to enable the broker such as redirect URIs.

WithBrokerPreview(PublicClientApplicationBuilder, Boolean)
Obsolete.

Enables MSAL to use Broker flows, which are more secure than browsers. For details about Windows broker, see https://aka.ms/msal-net-wam

WithSsoPolicy(PublicClientApplicationBuilder)
WithDesktopFeatures(PublicClientApplicationBuilder)
Obsolete.

Adds enhanced support for desktop applications, e.g. CLI, WinForms, WPF apps.

Support added is around:

WithWindowsDesktopFeatures(PublicClientApplicationBuilder, BrokerOptions)

Adds enhanced support for desktop applications, e.g. CLI, WinForms, WPF apps.

  • Windows Authentication Manager (WAM) broker, the recommended authentication mechanism on Windows 10+ - https://aka.ms/msal-net-wam
  • Embedded web view. AAD applications use the older WebBrowser control. Other applications (B2C, ADFS etc.) use WebView2, an embedded browser based on Microsoft Edge - https://aka.ms/msal-net-webview2
WithWindowsEmbeddedBrowserSupport(PublicClientApplicationBuilder)

Adds better embedded browser support to MSAL. AAD applications will use the older WebBrowser control. Other applications (B2C, ADFS etc.) will use an embedded browser based on Microsoft Edge - https://aka.ms/msal-net-webview2

WithBroker(PublicClientApplicationBuilder, BrokerOptions)

Brokers enable Single-Sign-On, device identification, and enhanced security. Use this API to enable brokers on desktop platforms.

See https://aka.ms/msal-net-wam for more information on platform specific settings required to enable the broker such as redirect URIs.

WithWindowsBroker(PublicClientApplicationBuilder, Boolean)
Obsolete.

Enables Windows broker flows on older platforms, such as .NET framework, where these are not available in the box with Microsoft.Identity.Client For details about Windows broker, see https://aka.ms/msal-net-wam

Applies to