ConfidentialClientApplication class

Package:

@azure/msal-node

This class is to be used to acquire tokens for confidential client applications (webApp, webAPI). Confidential client applications will configure application secrets, client certificates/assertions as applicable

Extends

ClientApplication

Constructors

ConfidentialClientApplication(Configuration)

Constructor for the ConfidentialClientApplication Required attributes in the Configuration object are: clientID: the application ID of your application. You can obtain one by registering your application with our application registration portal authority: the authority URL for your application. client credential: Must set either client secret, certificate, or assertion for confidential clients. You can obtain a client secret from the application registration portal. In Azure AD, authority is a URL indicating of the form https://login.microsoftonline.com/\{Enter_the_Tenant_Info_Here\} If your application supports Accounts in one organizational directory, replace "Enter_the_Tenant_Info_Here" value with the Tenant Id or Tenant name (for example, contoso.microsoft.com). If your application supports Accounts in any organizational directory, replace "Enter_the_Tenant_Info_Here" value with organizations. If your application supports Accounts in any organizational directory and personal Microsoft accounts, replace "Enter_the_Tenant_Info_Here" value with common. To restrict support to Personal Microsoft accounts only, replace "Enter_the_Tenant_Info_Here" value with consumers. In Azure B2C, authority is of the form https://{instance}/tfp/{tenant}/{policyName}/ Full B2C functionality will be available in this library in future versions.

Methods

acquireTokenByClientCredential(ClientCredentialRequest)	Acquires tokens from the authority for the application (not for an end user).
acquireTokenOnBehalfOf(OnBehalfOfRequest)	Acquires tokens from the authority for the application. Used in scenarios where the current app is a middle-tier service which was called with a token representing an end user. The current app can use the token (oboAssertion) to request another token to access downstream web API, on behalf of that user. The current middle-tier app has no user interaction to obtain consent. See how to gain consent upfront for your middle-tier app from this article. https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow#gaining-consent-for-the-middle-tier-application
SetAppTokenProvider(IAppTokenProvider)	This extensibility point only works for the client_credential flow, i.e. acquireTokenByClientCredential and is meant for Azure SDK to enhance Managed Identity support.

Inherited Methods

acquireTokenByCode(AuthorizationCodeRequest, AuthorizationCodePayload)	Acquires a token by exchanging the Authorization Code received from the first step of OAuth2.0 Authorization Code flow. getAuthCodeUrl(AuthorizationCodeUrlRequest) can be used to create the URL for the first step of OAuth2.0 Authorization Code flow. Ensure that values for redirectUri and scopes in AuthorizationCodeUrlRequest and AuthorizationCodeRequest are the same.
acquireTokenByRefreshToken(RefreshTokenRequest)	Acquires a token by exchanging the refresh token provided for a new set of tokens. This API is provided only for scenarios where you would like to migrate from ADAL to MSAL. Otherwise, it is recommended that you use acquireTokenSilent() for silent scenarios. When using acquireTokenSilent(), MSAL will handle the caching and refreshing of tokens automatically.
acquireTokenByUsernamePassword(UsernamePasswordRequest)	Acquires tokens with password grant by exchanging client applications username and password for credentials The latest OAuth 2.0 Security Best Current Practice disallows the password grant entirely. More details on this recommendation at https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13#section-3.4 Microsoft's documentation and recommendations are at: https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows#usernamepassword
acquireTokenSilent(SilentFlowRequest)	Acquires a token silently when a user specifies the account the token is requested for. This API expects the user to provide an account object and looks into the cache to retrieve the token if present. There is also an optional "forceRefresh" boolean the user can send to bypass the cache for access_token and id_token. In case the refresh_token is expired or not found, an error is thrown and the guidance is for the user to call any interactive token acquisition API (eg: acquireTokenByCode()).
clearCache()	Clear the cache
getAuthCodeUrl(AuthorizationUrlRequest)	Creates the URL of the authorization request, letting the user input credentials and consent to the application. The URL targets the /authorize endpoint of the authority configured in the application object. Once the user inputs their credentials and consents, the authority will send a response to the redirect URI sent in the request and should contain an authorization code, which can then be used to acquire tokens via acquireTokenByCode(AuthorizationCodeRequest).
getLogger()	Returns the logger instance
getTokenCache()	Gets the token cache for the application.
setLogger(Logger)	Replaces the default logger set in configurations with new Logger with new configurations

Constructor Details

ConfidentialClientApplication(Configuration)

Constructor for the ConfidentialClientApplication Required attributes in the Configuration object are:

• clientID: the application ID of your application. You can obtain one by registering your application with our application registration portal
• authority: the authority URL for your application.
• client credential: Must set either client secret, certificate, or assertion for confidential clients. You can obtain a client secret from the application registration portal.

In Azure AD, authority is a URL indicating of the form https://login.microsoftonline.com/\{Enter_the_Tenant_Info_Here\} If your application supports Accounts in one organizational directory, replace "Enter_the_Tenant_Info_Here" value with the Tenant Id or Tenant name (for example, contoso.microsoft.com). If your application supports Accounts in any organizational directory, replace "Enter_the_Tenant_Info_Here" value with organizations. If your application supports Accounts in any organizational directory and personal Microsoft accounts, replace "Enter_the_Tenant_Info_Here" value with common. To restrict support to Personal Microsoft accounts only, replace "Enter_the_Tenant_Info_Here" value with consumers.

In Azure B2C, authority is of the form https://{instance}/tfp/{tenant}/{policyName}/ Full B2C functionality will be available in this library in future versions.

new ConfidentialClientApplication(configuration: Configuration)

Parameters

configuration

Configuration

Method Details

acquireTokenByClientCredential(ClientCredentialRequest)

Acquires tokens from the authority for the application (not for an end user).

function acquireTokenByClientCredential(request: ClientCredentialRequest): Promise<AuthenticationResult | null>

Parameters

request

ClientCredentialRequest

Returns

Promise<AuthenticationResult | null>

acquireTokenOnBehalfOf(OnBehalfOfRequest)

Acquires tokens from the authority for the application. Used in scenarios where the current app is a middle-tier service which was called with a token representing an end user. The current app can use the token (oboAssertion) to request another token to access downstream web API, on behalf of that user.

The current middle-tier app has no user interaction to obtain consent. See how to gain consent upfront for your middle-tier app from this article. https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow#gaining-consent-for-the-middle-tier-application

function acquireTokenOnBehalfOf(request: OnBehalfOfRequest): Promise<AuthenticationResult | null>

Parameters

request

OnBehalfOfRequest

Returns

Promise<AuthenticationResult | null>

SetAppTokenProvider(IAppTokenProvider)

This extensibility point only works for the client_credential flow, i.e. acquireTokenByClientCredential and is meant for Azure SDK to enhance Managed Identity support.

function SetAppTokenProvider(provider: IAppTokenProvider)

Parameters

provider

IAppTokenProvider

Inherited Method Details

acquireTokenByCode(AuthorizationCodeRequest, AuthorizationCodePayload)

Acquires a token by exchanging the Authorization Code received from the first step of OAuth2.0 Authorization Code flow. getAuthCodeUrl(AuthorizationCodeUrlRequest) can be used to create the URL for the first step of OAuth2.0 Authorization Code flow. Ensure that values for redirectUri and scopes in AuthorizationCodeUrlRequest and AuthorizationCodeRequest are the same.

function acquireTokenByCode(request: AuthorizationCodeRequest, authCodePayLoad?: AuthorizationCodePayload): Promise<AuthenticationResult>

Parameters

request

AuthorizationCodeRequest

authCodePayLoad

AuthorizationCodePayload

Returns

Promise<AuthenticationResult>

Inherited From ClientApplication.acquireTokenByCode

acquireTokenByRefreshToken(RefreshTokenRequest)

Acquires a token by exchanging the refresh token provided for a new set of tokens. This API is provided only for scenarios where you would like to migrate from ADAL to MSAL. Otherwise, it is recommended that you use acquireTokenSilent() for silent scenarios. When using acquireTokenSilent(), MSAL will handle the caching and refreshing of tokens automatically.

function acquireTokenByRefreshToken(request: RefreshTokenRequest): Promise<AuthenticationResult | null>

Parameters

request

RefreshTokenRequest

Returns

Promise<AuthenticationResult | null>

Inherited From ClientApplication.acquireTokenByRefreshToken

acquireTokenByUsernamePassword(UsernamePasswordRequest)

Acquires tokens with password grant by exchanging client applications username and password for credentials The latest OAuth 2.0 Security Best Current Practice disallows the password grant entirely. More details on this recommendation at https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13#section-3.4 Microsoft's documentation and recommendations are at: https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows#usernamepassword

function acquireTokenByUsernamePassword(request: UsernamePasswordRequest): Promise<AuthenticationResult | null>

Parameters

request

UsernamePasswordRequest

UsenamePasswordRequest

Returns

Promise<AuthenticationResult | null>

Inherited From ClientApplication.acquireTokenByUsernamePassword

acquireTokenSilent(SilentFlowRequest)

Acquires a token silently when a user specifies the account the token is requested for. This API expects the user to provide an account object and looks into the cache to retrieve the token if present. There is also an optional "forceRefresh" boolean the user can send to bypass the cache for access_token and id_token. In case the refresh_token is expired or not found, an error is thrown and the guidance is for the user to call any interactive token acquisition API (eg: acquireTokenByCode()).

function acquireTokenSilent(request: SilentFlowRequest): Promise<AuthenticationResult | null>

Parameters

request

SilentFlowRequest

Returns

Promise<AuthenticationResult | null>

Inherited From ClientApplication.acquireTokenSilent

clearCache()

Clear the cache

function clearCache()

Inherited From ClientApplication.clearCache

getAuthCodeUrl(AuthorizationUrlRequest)

Creates the URL of the authorization request, letting the user input credentials and consent to the application. The URL targets the /authorize endpoint of the authority configured in the application object. Once the user inputs their credentials and consents, the authority will send a response to the redirect URI sent in the request and should contain an authorization code, which can then be used to acquire tokens via acquireTokenByCode(AuthorizationCodeRequest).

function getAuthCodeUrl(request: AuthorizationUrlRequest): Promise<string>

Parameters

request

AuthorizationUrlRequest

Returns

Promise<string>

Inherited From ClientApplication.getAuthCodeUrl

getLogger()

Returns the logger instance

function getLogger(): Logger

Returns

Logger

Inherited From ClientApplication.getLogger

getTokenCache()

Gets the token cache for the application.

function getTokenCache(): TokenCache

Returns

TokenCache

Inherited From ClientApplication.getTokenCache

setLogger(Logger)

Replaces the default logger set in configurations with new Logger with new configurations

function setLogger(logger: Logger)

Parameters

logger

Logger

Logger instance

Inherited From ClientApplication.setLogger