authentication module

Interfaces

AuthenticatePopUpParameters

Describes the authentication pop-up parameters

AuthTokenRequestParameters

Describes authentication token request parameters

LegacyCallBacks

Type Aliases

AuthenticateParameters

See LegacyCallBacks

AuthTokenRequest

Functions

authenticate(AuthenticateParameters)
authenticate(AuthenticatePopUpParameters)

Initiates an authentication flow which requires a new window. There are two primary uses for this function:

  1. When your app needs to authenticate using a 3rd-party identity provider (not Microsoft Entra ID)
  2. When your app needs to show authentication UI that is blocked from being shown in an iframe (e.g., Microsoft Entra consent prompts)

For more details, see Enable authentication using third-party OAuth provider

This function is not needed for "standard" Microsoft Entra SSO usage. Using getAuthToken is usually sufficient in that case. For more, see Enable SSO for tab apps)

getAuthToken(AuthTokenRequest)
getAuthToken(AuthTokenRequestParameters)

Requests an Microsoft Entra token to be issued on behalf of your app in an SSO flow. The token is acquired from the cache if it is not expired. Otherwise a request is sent to Microsoft Entra to obtain a new token. This function is used to enable SSO scenarios. See Enable SSO for tab apps for more details.

notifyFailure(string)

When using authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>, the window that was opened to execute the authentication flow should call this method after authentiction to notify the caller of authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string> that the authentication request failed.

notifySuccess(string)

When using authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>, the window that was opened to execute the authentication flow should call this method after authentiction to notify the caller of authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string> that the authentication request was successful.

registerAuthenticationHandlers(AuthenticateParameters)

Function Details

authenticate(AuthenticateParameters)

Warning

This API is now deprecated.

As of TeamsJS v2.0.0, please use authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string> instead.

The documentation for authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string> applies to this function. The one difference is that instead of the result being returned via the Promise, the result is returned to the callback functions provided in the authenticateParameters parameter.

function authenticate(authenticateParameters?: AuthenticateParameters)

Parameters

authenticateParameters
AuthenticateParameters

Parameters describing the authentication window used for executing the authentication flow and callbacks used for indicating the result

authenticate(AuthenticatePopUpParameters)

Initiates an authentication flow which requires a new window. There are two primary uses for this function:

  1. When your app needs to authenticate using a 3rd-party identity provider (not Microsoft Entra ID)
  2. When your app needs to show authentication UI that is blocked from being shown in an iframe (e.g., Microsoft Entra consent prompts)

For more details, see Enable authentication using third-party OAuth provider

This function is not needed for "standard" Microsoft Entra SSO usage. Using getAuthToken is usually sufficient in that case. For more, see Enable SSO for tab apps)

function authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>

Parameters

authenticateParameters
AuthenticatePopUpParameters

Parameters describing the authentication window used for executing the authentication flow

Returns

Promise<string>

Promise that will be fulfilled with the result from the authentication pop-up, if successful. The string in this result is provided in the parameter passed by your app when it calls authentication.notifySuccess(result?: string): void in the pop-up window after returning from the identity provider redirect.

Remarks

The authentication flow must start and end from the same domain, otherwise success and failure messages won't be returned to the window that initiated the call. The Teams authentication flow starts and ends at an endpoint on your own service (with a redirect round-trip to the 3rd party identity provider in the middle).

getAuthToken(AuthTokenRequest)

Warning

This API is now deprecated.

As of TeamsJS v2.0.0, please use authentication.getAuthToken(authTokenRequest: AuthTokenRequestParameters): Promise<string> instead.

The documentation authentication.getAuthToken(authTokenRequest: AuthTokenRequestParameters): Promise<string> applies to this function as well. The one difference when using this function is that the result is provided in the callbacks in the authTokenRequest parameter instead of as a Promise.

function getAuthToken(authTokenRequest?: AuthTokenRequest)

Parameters

authTokenRequest
AuthTokenRequest

An optional set of values that configure the token request. It contains callbacks to call in case of success/failure

getAuthToken(AuthTokenRequestParameters)

Requests an Microsoft Entra token to be issued on behalf of your app in an SSO flow. The token is acquired from the cache if it is not expired. Otherwise a request is sent to Microsoft Entra to obtain a new token. This function is used to enable SSO scenarios. See Enable SSO for tab apps for more details.

function getAuthToken(authTokenRequest?: AuthTokenRequestParameters): Promise<string>

Parameters

authTokenRequest
AuthTokenRequestParameters

An optional set of values that configure the token request.

Returns

Promise<string>

Promise that will be resolved with the token, if successful.

notifyFailure(string)

When using authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>, the window that was opened to execute the authentication flow should call this method after authentiction to notify the caller of authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string> that the authentication request failed.

function notifyFailure(result?: string)

Parameters

result

string

Specifies a result for the authentication. If specified, the frame that initiated the authentication pop-up receives this value in its callback or via the Promise return value

Remarks

This function is usable only on the authentication window. This call causes the authentication window to be closed.

notifySuccess(string)

When using authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>, the window that was opened to execute the authentication flow should call this method after authentiction to notify the caller of authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string> that the authentication request was successful.

function notifySuccess(result?: string)

Parameters

result

string

Specifies a result for the authentication. If specified, the frame that initiated the authentication pop-up receives this value in its callback or via the Promise return value

Remarks

This function is usable only from the authentication window. This call causes the authentication window to be closed.

registerAuthenticationHandlers(AuthenticateParameters)

Warning

This API is now deprecated.

As of TeamsJS v2.0.0, this function has been deprecated in favor of a Promise-based pattern using authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>

Registers handlers to be called with the result of an authentication flow triggered using authentication.authenticate(authenticateParameters?: AuthenticateParameters): void

function registerAuthenticationHandlers(authenticateParameters: AuthenticateParameters)

Parameters

authenticateParameters
AuthenticateParameters

Configuration for authentication flow pop-up result communication