Microsoft.Identity.Client Namespace
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 |
AcquireTokenByUsernameAndPasswordConfidentialParameterBuilder |
Parameter builder for the AcquireTokenByUsernamePassword(IEnumerable<String>, String, String) operation. See https://aka.ms/msal-net-up |
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 |
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:
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 |
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 | |
IByUsernameAndPassword |
Provides an explicit interface for using Resource Owner Password Grant on Confidential Client. |
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 Understanding MsalUiRequiredException 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 |
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.