Table of Contents

Class ConfidentialClientApplication

Namespace
Microsoft.Identity.Client
Assembly
Microsoft.Identity.Client.dll

Represents confidential client applications - web apps, web APIs, daemon applications.

public sealed class ConfidentialClientApplication : ClientApplicationBase, IConfidentialClientApplication, IClientApplicationBase, IApplicationBase, IConfidentialClientApplicationWithCertificate, IByRefreshToken, ILongRunningWebApi, IByUsernameAndPassword
Inheritance
ConfidentialClientApplication
Implements
Inherited Members
Extension Methods

Remarks

Confidential client applications are typically applications which run on servers (web apps, web API, or even service/daemon applications). They are considered difficult to access, and therefore capable of keeping an application secret (hold configuration time secrets as these values would be difficult for end users to extract). A web app is the most common confidential client. The client ID is exposed through the web browser, but the secret is passed only in the back channel and never directly exposed. For details, see Client Applications.

Fields

AttemptRegionDiscovery

Instructs MSAL to try to auto discover the Azure region.

public const string AttemptRegionDiscovery = "TryAutoDetect"

Field Value

string

Properties

AppTokenCache

Application token cache which holds access tokens for this application. It's maintained and updated silently when calling AcquireTokenForClient(IEnumerable<string>)

public ITokenCache AppTokenCache { get; }

Property Value

ITokenCache

Remarks

On .NET Framework and .NET Core you can also customize the token cache serialization. See Token Cache Serialization. This is taken care of by MSAL.NET on other platforms.

Certificate

The certificate used to create this ConfidentialClientApplication, if any.

public X509Certificate2 Certificate { get; }

Property Value

X509Certificate2

Methods

AcquireTokenByAuthorizationCode(IEnumerable<string>, string)

Acquires a token from the authority configured in the app using the authorization code previously received from the identity provider using the OAuth 2.0 authorization code flow. See Authorization Code Flow. This flow is usually used in web apps (for instance, ASP.NET and ASP.NET Core web apps) which sign-in users and can request an authorization code. This method does not look in the token cache, but stores the result in it. Before calling this method, use other methods such as AcquireTokenSilent(IEnumerable<string>, IAccount) to check the token cache.

public AcquireTokenByAuthorizationCodeParameterBuilder AcquireTokenByAuthorizationCode(IEnumerable<string> scopes, string authorizationCode)

Parameters

scopes IEnumerable<string>

Scopes requested to access a protected API.

authorizationCode string

The authorization code received from the service authorization endpoint.

Returns

AcquireTokenByAuthorizationCodeParameterBuilder

A builder enabling you to add optional parameters before executing the token request.

AcquireTokenForClient(IEnumerable<string>)

Acquires a token from the authority configured in the app for the confidential client itself (not for a user) using the client credentials flow. See Client Credentials Flow. During this operation MSAL will first search in the cache for an unexpired token before acquiring a new one from Microsoft Entra ID.

public AcquireTokenForClientParameterBuilder AcquireTokenForClient(IEnumerable<string> scopes)

Parameters

scopes IEnumerable<string>

Scopes requested to access a protected API. For this flow (client credentials), the scopes should be in the form of "{ResourceIdUri/.default}" for instance https://management.azure.net/.default or, for Microsoft Graph, https://graph.microsoft.com/.default as the requested scopes are defined statically in the application registration in the portal, and cannot be overridden in the application.

Returns

AcquireTokenForClientParameterBuilder

A builder enabling you to add optional parameters before executing the token request.

AcquireTokenInLongRunningProcess(IEnumerable<string>, string)

Retrieves an access token from the cache using the provided cache key that can be used to access another downstream protected web API on behalf of a user using the OAuth 2.0 On-Behalf-Of flow. See Long-running OBO in MSAL.NET. Use StopLongRunningProcessInWebApiAsync(ILongRunningWebApi, string, CancellationToken) to stop the long running process and remove the associated tokens from the cache.

public AcquireTokenOnBehalfOfParameterBuilder AcquireTokenInLongRunningProcess(IEnumerable<string> scopes, string longRunningProcessSessionKey)

Parameters

scopes IEnumerable<string>

Scopes requested to access a protected API.

longRunningProcessSessionKey string

Key by which to look up the token in the cache.

Returns

AcquireTokenOnBehalfOfParameterBuilder

A builder enabling you to add other parameters before executing the token request.

Remarks

This method should be called during the long-running session to retrieve the token from the cache.

Exceptions

MsalClientException

The token cache does not contain a token with an OBO cache key that matches the longRunningProcessSessionKey.

AcquireTokenOnBehalfOf(IEnumerable<string>, UserAssertion)

Acquires an access token for this application (usually a web API) from the authority configured in the application, in order to access another downstream protected web API on behalf of a user using the OAuth 2.0 On-Behalf-Of flow. During this operation MSAL will first search in the cache for an unexpired token before acquiring a new one from Microsoft Entra ID. See On-Behalf-Of Flow.

public AcquireTokenOnBehalfOfParameterBuilder AcquireTokenOnBehalfOf(IEnumerable<string> scopes, UserAssertion userAssertion)

Parameters

scopes IEnumerable<string>

Scopes requested to access a protected API.

userAssertion UserAssertion

Instance of UserAssertion containing credential information about the user on behalf of whom to get a token.

Returns

AcquireTokenOnBehalfOfParameterBuilder

A builder enabling you to add optional parameters before executing the token request.

Remarks

Pass an access token (not an ID token) which was used to access this application in the userAssertion parameter. For long-running or background processes in web API, see Long-running OBO in MSAL.NET.

GetAuthorizationRequestUrl(IEnumerable<string>)

Computes the URL of the authorization request letting the user sign-in and consent to the application accessing specific scopes in the user's name. The URL targets the /authorize endpoint of the authority configured in the application.

public GetAuthorizationRequestUrlParameterBuilder GetAuthorizationRequestUrl(IEnumerable<string> scopes)

Parameters

scopes IEnumerable<string>

Scopes requested to access a protected API.

Returns

GetAuthorizationRequestUrlParameterBuilder

A builder enabling you to add optional parameters before executing the token request to get the URL of the authorization endpoint with the specified parameters.

InitiateLongRunningProcessInWebApi(IEnumerable<string>, string, ref string)

Acquires an access token for this web API from the authority configured in the application, in order to access another downstream protected web API on behalf of a user using the OAuth 2.0 On-Behalf-Of flow. See Long-running OBO in MSAL.NET. Pass an access token (not an ID token) which was used to call this confidential client application in the userToken parameter. Use StopLongRunningProcessInWebApiAsync(ILongRunningWebApi, string, CancellationToken) to stop the long running process and remove the associated tokens from the cache.

public AcquireTokenOnBehalfOfParameterBuilder InitiateLongRunningProcessInWebApi(IEnumerable<string> scopes, string userToken, ref string longRunningProcessSessionKey)

Parameters

scopes IEnumerable<string>

Scopes requested to access a protected API.

userToken string

A JSON Web Token which was used to call this web API and contains the credential information about the user on behalf of whom to get a token.

longRunningProcessSessionKey string

Key by which to look up the token in the cache. If null, it will be set to the assertion hash of the userToken by default.

Returns

AcquireTokenOnBehalfOfParameterBuilder

A builder enabling you to add other parameters before executing the token request.

Remarks

This method should be called once when the long-running session is started.

StopLongRunningProcessInWebApiAsync(string, CancellationToken)

Stops an in-progress long-running on-behalf-of session by removing the tokens associated with the provided cache key. See Long-running OBO in MSAL.NET.

public Task<bool> StopLongRunningProcessInWebApiAsync(string longRunningProcessSessionKey, CancellationToken cancellationToken = default)

Parameters

longRunningProcessSessionKey string

OBO cache key used to remove the tokens.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

True if tokens are removed from the cache; false, otherwise.

Exceptions

ArgumentNullException

longRunningProcessSessionKey is not set.