Interface IClientApplicationBase

Namespace

Microsoft.Identity.Client

Assembly

Microsoft.Identity.Client.dll

Interface used for creation of client applications. For details see https://aka.ms/msal-net-client-applications.

public interface IClientApplicationBase : IApplicationBase

Properties

AppConfig

Details on the configuration of the ClientApplication for debugging purposes.

IAppConfig AppConfig { get; }

Property Value

IAppConfig

Authority

Gets the URL of the authority, or the security token service (STS) from which MSAL.NET will acquire security tokens. The return value of this property is either the value provided by the developer in the constructor of the application, or otherwise the value of the Microsoft.Identity.Client.ApplicationBase.DefaultAuthority static member (that is https://login.microsoftonline.com/common/)

string Authority { get; }

Property Value

string

UserTokenCache

User token cache which holds ID tokens, access tokens, and refresh tokens for accounts. It's used and updated silently if needed when calling AcquireTokenSilent(IEnumerable<string>, IAccount) It is updated by each acquire token method, with the exception of AcquireTokenForClient(IEnumerable<string>) which only uses the application cache (see AppTokenCache).

ITokenCache UserTokenCache { get; }

Property Value

ITokenCache

Remarks

On .NET Framework and .NET Core you can also customize the token cache serialization. See https://aka.ms/msal-net-token-cache-serialization. This is taken care of by MSAL.NET on mobile platforms. It is recommended to use token cache serialization for web site and web api scenarios.

Methods

AcquireTokenSilent(IEnumerable<string>, IAccount)

Attempts to acquire an access token for the account from the user token cache, with advanced parameters controlling the network call. See Acquire tokens silently.

AcquireTokenSilentParameterBuilder AcquireTokenSilent(IEnumerable<string> scopes, IAccount account)

Parameters

scopes IEnumerable<string>

Scopes requested to access a protected API.

account IAccount

Account for which the token is requested. IAccount

Returns

AcquireTokenSilentParameterBuilder

An AcquireTokenSilentParameterBuilder used to build the token request, adding optional parameters.

Remarks

The access token is considered a match if it contains at least all the requested scopes. This means that an access token with more scopes than requested could be returned as well. If the access token is expired or close to expiration (within a 5 minute window), then the cached refresh token (if available) is used to acquire a new access token by making a silent network call.

Exceptions

MsalUiRequiredException

When an interaction is required with the end user of the application, for instance, if no refresh token was in the cache; the user needs to consent or to re-sign-in (for instance if the password expired); or the user needs to perform two factor authentication.

AcquireTokenSilent(IEnumerable<string>, string)

Attempts to acquire an access token for the loginHint from the user token cache, with advanced parameters controlling the network call. See Acquire tokens silently.

AcquireTokenSilentParameterBuilder AcquireTokenSilent(IEnumerable<string> scopes, string loginHint)

Parameters

scopes IEnumerable<string>

Scopes requested to access a protected API.

loginHint string

Typically the username, in UPN format, e.g. johnd@contoso.com.

Returns

AcquireTokenSilentParameterBuilder

An AcquireTokenSilentParameterBuilder used to build the token request, adding optional parameters.

Remarks

The access token is considered a match if it contains at least all the requested scopes. This means that an access token with more scopes than requested could be returned as well. If the access token is expired or close to expiration (within a 5 minute window), then the cached refresh token (if available) is used to acquire a new access token by making a silent network call.

Exceptions

MsalUiRequiredException

When an interaction is required with the end user of the application, for instance, if no refresh token was in the cache; the user needs to consent or to re-sign-in (for instance if the password expired); or the user needs to perform two factor authentication.

GetAccountAsync(string)

Get the IAccount by its identifier among the accounts available in the token cache and of the same environment (authority host) as Authority.

Task<IAccount> GetAccountAsync(string identifier)

Parameters

identifier string

Account identifier. The value of the identifier will probably have been stored value from the value of the Identifier property of AccountId. You typically get the account ID from an IAccount by using the HomeAccountId property.

Returns

Task<IAccount>

GetAccountsAsync()

Returns all the available accounts in the user token cache for the application.

Task<IEnumerable<IAccount>> GetAccountsAsync()

Returns

Task<IEnumerable<IAccount>>

GetAccountsAsync(string)

Only for Azure AD B2C scenarios, get the IAccount collection by its identifier among the accounts available in the token cache based on the user flow.

Task<IEnumerable<IAccount>> GetAccountsAsync(string userFlow)

Parameters

userFlow string

The identifier is the user flow being targeted by the specific B2C authority.

Returns

Task<IEnumerable<IAccount>>

RemoveAsync(IAccount)

Removes all tokens in the cache for the specified account.

Task RemoveAsync(IAccount account)

Parameters

account IAccount

Instance of the account that needs to be removed.

Returns

Task