Microsoft.Identity.Client Namespace

Reference

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Microsoft.Identity.Client is the core namespace for the Microsoft Authentication Library (MSAL) for .NET, available through the Microsoft.Identity.Client package. It contains all the key components that you need to acquire a token from supported authentication providers.

Installation

Using the .NET Command-Line Interface (CLI):

dotnet add package Microsoft.Identity.Client

Using the NuGet Command Line Interface (CLI):

nuget install Microsoft.Identity.Client

Using the Package Manager Console:

Install-Package Microsoft.Identity.Client

Using Visual Studio:

Open the Solution Explorer.
Right-click on a project within the solution.
Click on Manage NuGet Packages...
Click on the Browse tab and search for Microsoft.Identity.Client.
Click on the Microsoft.Identity.Client package and click Install.

Documentation

To get started, check out the Microsoft Authentication Library for .NET guide.

Samples

Refer to Microsoft identity platform code samples and the Samples Browser.

Classes

AbstractAcquireTokenParameterBuilder<T>	Base class for builders of token requests, which attempt to acquire a token based on the provided parameters.
AbstractApplicationBuilder<T>
AbstractClientAppBaseAcquireTokenParameterBuilder<T>	Base class for parameter builders common to public client application and confidential client application token acquisition operations
AbstractConfidentialClientAcquireTokenParameterBuilder<T>	Base class for confidential client application token request builders
AbstractManagedIdentityAcquireTokenParameterBuilder<T>	Abstract base class for managed identity application token request builders.
AbstractPublicClientAcquireTokenParameterBuilder<T>	Base class for public client application token request builders
AccountExtensions	Extension methods for IAccount
AccountId	An identifier for an account in a specific tenant. Returned by IAccount.HomeAccountId
AcquireTokenByAuthorizationCodeParameterBuilder	Builder for AcquireTokenByAuthorizationCode
AcquireTokenByIntegratedWindowsAuthParameterBuilder	Builder for AcquireTokenByIntegratedWindowsAuth
AcquireTokenByRefreshTokenParameterBuilder	Parameter builder for the AcquireTokenByRefreshToken(IEnumerable<String>, String) method. See https://aka.ms/msal-net-migration-adal2-msal2
AcquireTokenByUsernamePasswordParameterBuilder	Parameter builder for the AcquireTokenByUsernamePassword(IEnumerable<String>, String, String) operation. See https://aka.ms/msal-net-up
AcquireTokenForClientParameterBuilder	Builder for AcquireTokenForClient (used in client credential flows, in daemon applications). See https://aka.ms/msal-net-client-credentials
AcquireTokenForManagedIdentityParameterBuilder	Builder for AcquireTokenForManagedIdentity (used to get token for managed identities). See https://aka.ms/msal-net-managed-identity
AcquireTokenInteractiveParameterBuilder	Builder for an Interactive token request. See https://aka.ms/msal-net-acquire-token-interactively
AcquireTokenOnBehalfOfParameterBuilder	Builder for AcquireTokenOnBehalfOf (OBO flow) See https://aka.ms/msal-net-on-behalf-of
AcquireTokenSilentParameterBuilder	Parameter builder for the AcquireTokenSilent(IEnumerable<String>, IAccount) operation. See https://aka.ms/msal-net-acquiretokensilent
AcquireTokenWithDeviceCodeParameterBuilder	Parameters builder for the AcquireTokenWithDeviceCode(IEnumerable<String>, Func<DeviceCodeResult,Task>) operation. See https://aka.ms/msal-net-device-code-flow
ApplicationBase	Interface used for creation of client applications. For details see https://aka.ms/msal-net-client-applications.
ApplicationOptions	Base class for options objects with string values loadable from a configuration file (for instance a JSON file, as in an asp.net configuration scenario) See https://aka.ms/msal-net-application-configuration See also derived classes PublicClientApplicationOptions and ConfidentialClientApplicationOptions
AssertionRequestOptions	Information about the client assertion that need to be generated See https://aka.ms/msal-net-client-assertion
AuthenticationHeaderParser	Parsed authentication headers to retrieve header values from HttpResponseHeaders.
AuthenticationInfoParameters	Parameters returned by the Authentication-Info header. This allows for scenarios such as proof-of-possession, etc. See https://www.rfc-editor.org/rfc/rfc7615
AuthenticationResult	Contains the results of one token acquisition operation in PublicClientApplication or ConfidentialClientApplication. For details see https://aka.ms/msal-net-authenticationresult
AuthenticationResultMetadata	Contains metadata of the authentication result. Metrics for additional MSAL-wide metrics.
BaseAbstractAcquireTokenParameterBuilder<T>	Base class for builders of token requests, which attempt to acquire a token based on the provided parameters.
BaseAbstractApplicationBuilder<T>
BaseApplicationOptions	Base class for options objects with string values loadable from a configuration file (for instance a JSON file, as in an asp.net configuration scenario) See https://aka.ms/msal-net-application-configuration See also derived classes ApplicationOptions
BrokerOptions	The class specifies the options for broker across OperatingSystems The common properties are direct members Platform specific properties (if they exist) are part of the corresponding options
CacheOptions	Options for MSAL token caches.
ClientApplicationBase	Abstract class containing common API methods and properties. Both PublicClientApplication and ConfidentialClientApplication extend this class. For details see https://aka.ms/msal-net-client-applications
ClientAssertionCertificate	Certificate for a client assertion. This class is used in one of the constructors of ClientCredential. ClientCredential is itself used in the constructor of ConfidentialClientApplication to pass to Azure AD a shared secret (registered in the Azure AD application)
ClientCredential	Meant to be used in confidential client applications, an instance of `ClientCredential` is passed to the constructors of (ConfidentialClientApplication) as credentials proving that the application (the client) is what it claims it is. These credentials can be either a client secret (an application password) or a certificate. This class has one constructor for each case. These credentials are added in the application registration portal (in the secret section).
ConfidentialClientApplication	Class to be used for confidential client applications (web apps, web APIs, and daemon applications).
ConfidentialClientApplicationBuilder
ConfidentialClientApplicationOptions	Configuration options for a confidential client application (web app / web API / daemon app). See https://aka.ms/msal-net/application-configuration
DeviceCodeResult	This object is returned as part of the device code flow and has information intended to be shown to the user about where to navigate to login and what the device code needs to be entered on that device. See https://aka.ms/msal-device-code-flow.
EmbeddedWebViewOptions	Options for using the embedded webview.
GetAuthorizationRequestUrlParameterBuilder	NOTE: a few of the methods in AbstractAcquireTokenParameterBuilder (e.g. account) don't make sense here. Do we want to create a further base that contains ALL of the common methods, and then have another one including account, etc that are only used for AcquireToken?
IntuneAppProtectionPolicyRequiredException	This exception is thrown when Intune requires app protection policy. The information in this exception can be used by app to obtain the required enrollment ID from Mobile App Management (MAM) SDK. See https://aka.ms/msal-net-trueMAM
Logger
ManagedIdentityApplication	Class to be used for managed identity applications (on Azure resources like App Services, Virtual Machines, Azure Arc, Service Fabric and Cloud Shell).
ManagedIdentityApplicationBuilder	Builder for managed identity applications.
Metrics	MSAL-wide metrics.
MsalClaimsChallengeException	This exception indicates that claims have been returned from the endpoint that need to be resolved. This can be achieved by using them in the next authentication request. See Conditional Access and claims challenges. See Handling multifactor auth (MFA), Conditional Access, and incremental consent.
MsalClientException	This exception class represents errors that are local to the library or the device. Contrary to MsalServiceException which represent errors happening from the Azure AD service or the network. For more details, see https://aka.ms/msal-net-exceptions
MsalError	Error code returned as a property in MsalException
MsalException	Base exception type thrown when an error occurs during token acquisition. For more details, see https://aka.ms/msal-net-exceptions
MsalManagedIdentityException	This exception class is for exceptions generated from Managed Identity sources. This class is deprecated and will be removed in a future release. Catch MsalServiceException instead. For more details, see https://aka.ms/msal-net-managed-identity
MsalServiceException	Exception type thrown when service returns an error response or other networking errors occur. For more details, see https://aka.ms/msal-net-exceptions
MsalThrottledServiceException	Exception type thrown when MSAL detects that an application is trying to acquire a token too often, as a result of: A previous request resulted in an HTTP response containing a Retry-After header which was not followed. A previous request resulted in an HTTP 429 or 5xx, which indicates a problem with the server. The properties of this exception are identical to the original exception For more details see https://aka.ms/msal-net-throttling
MsalThrottledUiRequiredException	Exception type thrown when MSAL detects that an application is trying to acquire a token even though an MsalUiRequiredException was recently thrown. To mitigate this, when a MsalUiRequiredException is encountered, the application should switch to acquiring a token interactively. To better understand why the MsalUiRequiredException was thrown, inspect the Classification property. The properties of this exception are identical to the original exception For more details see https://aka.ms/msal-net-throttling
MsalUiRequiredException	This exception class is to inform developers that UI interaction is required for authentication to succeed. It's thrown when calling AcquireTokenSilent(IEnumerable<String>, IAccount) or one of its overrides, and when the token does not exists in the cache, or the user needs to provide more content, or perform multiple factor authentication based on Azure AD policies, etc.. For more details, see https://aka.ms/msal-net-exceptions
OsCapabilitiesExtensions	Extension methods
PublicClientApplication	Abstract class containing common API methods and properties. For details see https://aka.ms/msal-net-client-applications
PublicClientApplicationBuilder
PublicClientApplicationExtensions	Extensibility methods for IPublicClientApplication
PublicClientApplicationOptions	Configuration options for a public client application (desktop/mobile app). See https://aka.ms/msal-net/application-configuration
RegionDetails	Contains the result of region when MSAL region discovery is used, published as part of AuthenticationResultMetadata. AuthenticationResultMetadata for additional metadata information of the authentication result.
SystemWebViewOptions	Options for using the default OS browser as a separate process to handle interactive auth. MSAL will be listening for the OS browser to finish authenticating, but it cannot close the browser. It can however respond with a 200 OK message or a 302 Redirect, which can be configured here. For more details see https://aka.ms/msal-net-os-browser
Telemetry
TenantProfile	Represents an account in a specific tenant. The same account can exist in its home tenant and also as a guest in multiple other tenants. Access tokens and Id Tokens are tenant specific and this object provides high level information about all the ID tokens associated with the account.
TokenCache	Token cache storing access and refresh tokens for accounts This class is used in the constructors of PublicClientApplication and ConfidentialClientApplication. In the case of ConfidentialClientApplication, two instances are used, one for the user token cache, and one for the application token cache (in the case of applications using the client credential flows).
TokenCacheExtensions	Extension methods for ITokenCache
TokenCacheNotificationArgs	Contains parameters used by the MSAL call accessing the cache. See also ITokenCacheSerializer which contains methods to customize the cache serialization. For more details about the token cache see https://aka.ms/msal-net-web-token-cache
TraceTelemetryConfig	A simple ITelemetryConfig implementation that writes data using System.Diagnostics.Trace.
UIParent
UserAssertion
WindowsBrokerOptions	Advanced options for using the Windows 10 broker. For more details see https://aka.ms/msal-net-wam
WwwAuthenticateParameters	Parameters returned by the WWW-Authenticate header. This allows for dynamic scenarios such as Claims challenge, Continuous Access Evaluation (CAE), and Conditional Access (CA). See https://aka.ms/msal-net/wwwAuthenticate.

Structs

Prompt	Structure containing static members that you can use to specify how the interactive overrides of AcquireTokenAsync in IPublicClientApplication should prompt the user.
UIBehavior	Structure containing static members that you can use to specify how the interactive overrides of AcquireTokenAsync in PublicClientApplication should prompt the user.

Interfaces

IAccount	The IAccount interface represents information about a single account. The same user can be present in different tenants, that is, a user can have multiple accounts. An `IAccount` is returned in the AuthenticationResult.Account property, and can be used as parameters of PublicClientApplication and ConfidentialClientApplication methods acquiring tokens such as AcquireTokenSilent(IEnumerable<String>, IAccount)
IAppConfig	Configuration properties used to build a public or confidential client application.
IApplicationBase	Interface used for creation of client applications. For details see https://aka.ms/msal-net-client-applications.
IByRefreshToken
IClientApplicationBase	Interface defining common API methods and properties. Both PublicClientApplication and ConfidentialClientApplication extend this class. For details see https://aka.ms/msal-net-client-applications
IConfidentialClientApplication	Represents confidential client applications - web apps, web APIs, daemon applications.
IConfidentialClientApplicationWithCertificate	Component to be used with confidential client applications like web apps/APIs. This component supports Subject Name + Issuer authentication in order to help, in the future, Azure AD certificates rollover.
ILongRunningWebApi	Methods for long-running or background processes in web APIs.
IManagedIdentityApplication	Component to be used with managed identity applications for Azure resources.
IMsalHttpClientFactory	Factory responsible for creating HttpClient. See https://learn.microsoft.com/dotnet/api/system.net.http.httpclient?view=net-7.0#instancing for more details.
IPublicClientApplication	Represents public client applications - desktop and mobile applications.
ITelemetryConfig
ITelemetryEventPayload	Data that represents a single snapshot in the series of events that are collected
ITokenCache	This is the interface that implements the public access to cache operations. With CacheV2, this should only be necessary if the caller is persisting the cache in their own store, since this will provide the serialize/deserialize and before/after notifications used in that scenario. See https://aka.ms/aka.ms/msal-net-token-cache-serialization
ITokenCacheSerializer	This interface will be available in TokenCacheNotificationArgs callback to enable serialization/deserialization of the cache.
IUser	In MSAL.NET 1.x, was representing a User. From MSAL 2.x use IAccount which represents an account (a user has several accounts). See https://aka.ms/msal-net-2-released for more details.

Enums

AadAuthorityAudience	Specifies which Microsoft accounts can be used for sign-in with a given application. See https://aka.ms/msal-net-application-configuration
AzureCloudInstance
BrokerOptions.OperatingSystems	Supported OperatingSystems
CacheRefreshReason	Specifies the reason for fetching the access token from the identity provider when using AcquireTokenSilent, AcquireTokenForClient or AcquireTokenOnBehalfOf.
LogLevel	Represents log level in MSAL. For details, see MSAL logging.
TelemetryAudienceType	Describes the types of audiences for telemetry. AudienceType
TokenSource	Specifies the source of the access and Id tokens in the authentication result.
UiRequiredExceptionClassification	Details about the cause of an MsalUiRequiredException, giving a hint about what the user can expect when they go through interactive authentication. See https://aka.ms/msal-net-UiRequiredException for details.

Delegates

LogCallback	Callback delegate that allows application developers to consume logs, and handle them in a custom manner. This callback is set using WithLogging(LogCallback, Nullable<LogLevel>, Nullable<Boolean>, Nullable<Boolean>). If `PiiLoggingEnabled` is set to `true`, when registering the callback this method will receive the messages twice: once with the `containsPii` parameter equals `false` and the message without PII, and a second time with the `containsPii` parameter equals to `true` and the message might contain PII. In some cases (when the message does not contain PII), the message will be the same. For details see https://aka.ms/msal-net-logging
Telemetry.Receiver
TokenCache.TokenCacheNotification	Notification for certain token cache interactions during token acquisition. This delegate is used in particular to provide a custom token cache serialization
TokenCacheCallback	Notification for certain token cache interactions during token acquisition. This delegate is used in particular to provide a custom token cache serialization. See https://aka.ms/aka.ms/msal-net-token-cache-serialization

Remarks

Contributions

We appreciate feedback and contributions to help make Microsoft Authentication Library for .NET better! Before you get started, please read the following documents:

Issues

To provide library feedback or report a bug, please open an issue on GitHub.