Dela via


Microsoft.Identity.Client Namespace

NuGet NuGet downloads GitHub Repo stars

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:

  1. Open the Solution Explorer.
  2. Right-click on a project within the solution.
  3. Click on Manage NuGet Packages...
  4. Click on the Browse tab and search for Microsoft.Identity.Client.
  5. 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 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
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 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.