@microsoft/teams-js/dist/esm/packages/teams-js/dts/public/authentication.d.ts

Microsoft Client SDK for building app for Microsoft hosts

/**
 * Module to interact with the authentication-specific part of the SDK.
 *
 * This object is used for starting or completing authentication flows.
 * @module
 */
/**
 * @deprecated
 * As of TeamsJS v2.0.0, this function has been deprecated in favor of a Promise-based pattern using {@link authentication.authenticate authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise\<string\>}
 *
 * Registers handlers to be called with the result of an authentication flow triggered using {@link authentication.authenticate authentication.authenticate(authenticateParameters?: AuthenticateParameters): void}
 *
 * @param authenticateParameters - Configuration for authentication flow pop-up result communication
 */
export declare function registerAuthenticationHandlers(authenticateParameters: AuthenticateParameters): void;
/**
 * 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](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/authentication/auth-flow-tab)
 *
 * This function is *not* needed for "standard" Microsoft Entra SSO usage. Using {@link getAuthToken} is usually sufficient in that case. For more, see
 * [Enable SSO for tab apps](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/authentication/tab-sso-overview))
 *
 * @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 [authentication flow](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/authentication/auth-flow-tab) starts and ends at an endpoint on
 * your own service (with a redirect round-trip to the 3rd party identity provider in the middle).
 *
 * @param authenticateParameters - Parameters describing the authentication window used for executing the authentication flow
 *
 * @returns `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 {@link authentication.notifySuccess authentication.notifySuccess(result?: string): void} in the pop-up window after returning from the identity provider redirect.
 *
 * @throws `Error` if the authentication request fails or is canceled by the user. This error is provided in the parameter passed by your app when it calls
 * {@link authentication.notifyFailure authentication.notifyFailure(result?: string): void} in the pop-up window after returning from the identity provider redirect. However, in some cases it can also be provided by
 * the infrastructure depending on the failure (e.g., a user cancelation)
 *
 */
export declare function authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>;
/**
 * @deprecated
 * As of TeamsJS v2.0.0, please use {@link authentication.authenticate authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise\<string\>} instead.
 *
 * The documentation for {@link authentication.authenticate 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.
 *
 * @param authenticateParameters - Parameters describing the authentication window used for executing the authentication flow and callbacks used for indicating the result
 *
 */
export declare function authenticate(authenticateParameters?: AuthenticateParameters): void;
/**
 * 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](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/authentication/tab-sso-overview)
 * for more details.
 *
 * @param authTokenRequest - An optional set of values that configure the token request.
 *
 * @returns `Promise` that will be resolved with the token, if successful.
 *
 * @throws `Error` if the request fails in some way
 */
export declare function getAuthToken(authTokenRequest?: AuthTokenRequestParameters): Promise<string>;
/**
 * @deprecated
 * As of TeamsJS v2.0.0, please use {@link authentication.getAuthToken authentication.getAuthToken(authTokenRequest: AuthTokenRequestParameters): Promise\<string\>} instead.
 *
 * The documentation {@link authentication.getAuthToken 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`.
 *
 * @param authTokenRequest - An optional set of values that configure the token request.
 * It contains callbacks to call in case of success/failure
 */
export declare function getAuthToken(authTokenRequest?: AuthTokenRequest): void;
/**
 * @hidden
 * Requests the decoded Microsoft Entra user identity on behalf of the app.
 *
 * @returns Promise that resolves with the {@link UserProfile}.
 *
 * @throws `Error` object in case of any problems, the most likely of which is that the calling app does not have appropriate permissions
 * to call this method.
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function getUser(): Promise<UserProfile>;
/**
 * @deprecated
 * As of TeamsJS v2.0.0, please use {@link authentication.getUser authentication.getUser(): Promise\<UserProfile\>} instead.
 *
 * @hidden
 * Requests the decoded Microsoft Entra user identity on behalf of the app.
 *
 * @param userRequest - It passes success/failure callbacks in the userRequest object(deprecated)
 *
 * @throws `Error` object in case of any problems, the most likely of which is that the calling app does not have appropriate permissions
 * to call this method.
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function getUser(userRequest: UserRequest): void;
/**
 * When using {@link authentication.authenticate authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise\<string\>}, the
 * window that was opened to execute the authentication flow should call this method after authentication to notify the caller of
 * {@link authentication.authenticate authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise\<string\>} that the
 * authentication request was successful.
 *
 * @remarks
 * The `result` parameter should **never** contain the token that was received from the identity provider, because a malicious app (rather than your own app) might have opened
 * the authentication window. If that was the case, passing the token in this parameter would leak it to them. More secure methods for completing the authentication flow include:
 * - For a purely browser-based experience (e.g., a personal app/tab app), you could store the token in browser local storage and then have your personal app retrieve it once
 * this `notifySuccess` call is received.
 * - For a server-based experience (e.g., a message extension), your authentication window could store the token on your service and then generate a unique code passed via this
 * `result` parameter. The caller can then use the unique code to retrieve the token from your service.
 *
 * This function is usable only from an authentication window opened with {@link authentication.authenticate authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise\<string\>}.
 * This call causes the authentication window to be closed.
 *
 * @param result - 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.
 *
 */
export declare function notifySuccess(result?: string): void;
/**
   * When using {@link authentication.authenticate 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
   * {@link authentication.authenticate authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise\<string\>} that the
   * authentication request failed.

   *
   * @remarks
   * This function is usable only on the authentication window.
   * This call causes the authentication window to be closed.
   *
   * @param result - 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
   * @param _callbackUrl - This parameter is deprecated and unused
   */
export declare function notifyFailure(result?: string): void;
/**
 * @deprecated
 * As of TeamsJS v2.0.0, this interface has been deprecated in favor of leveraging the `Promise` returned from {@link authentication.authenticate authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise\<string\>}
 *-------------------------
 * Used in {@link AuthenticateParameters} and {@link AuthTokenRequest}
 */
export interface LegacyCallBacks {
    /**
     * @deprecated
     * As of TeamsJS v2.0.0, this property has been deprecated in favor of a Promise-based pattern.
     *
     * A function that is called if the request succeeds.
     */
    successCallback?: (result: string) => void;
    /**
     * @deprecated
     * As of TeamsJS v2.0.0, this property has been deprecated in favor of a Promise-based pattern.
     *
     * A function that is called if the request fails, with the reason for the failure.
     */
    failureCallback?: (reason: string) => void;
}
/**
 * Describes the authentication pop-up parameters
 */
export interface AuthenticatePopUpParameters {
    /**
     * The URL for the authentication pop-up.
     */
    url: string;
    /**
     * The preferred width for the pop-up. This value can be ignored if outside the acceptable bounds.
     */
    width?: number;
    /**
     * The preferred height for the pop-up. This value can be ignored if outside the acceptable bounds.
     */
    height?: number;
    /**
     * Some identity providers restrict their authentication pages from being displayed in embedded browsers (e.g., a web view inside of a native application)
     * If the identity provider you are using prevents embedded browser usage, this flag should be set to `true` to enable the authentication page specified in
     * the {@link url} property to be opened in an external browser.
     * If this flag is `false`, the page will be opened directly within the current hosting application.
     *
     * This flag is ignored when the host for the application is a web app (as opposed to a native application) as the behavior is unnecessary in a web-only
     * environment without an embedded browser.
     */
    isExternal?: boolean;
}
/**
 * @deprecated
 * As of TeamsJS v2.0.0, please use {@link authentication.authenticate authentication.authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise\<string\>} and
 * the associated {@link AuthenticatePopUpParameters} instead.
 *
 * @see {@link LegacyCallBacks}
 */
export type AuthenticateParameters = AuthenticatePopUpParameters & LegacyCallBacks;
/**
 * Describes authentication token request parameters
 */
export interface AuthTokenRequestParameters {
    /**
     * @hidden
     * @internal
     * An list of resources for which to acquire the access token; only for internal Microsoft usage
     */
    resources?: string[];
    /**
     * An optional list of claims which to pass to Microsoft Entra when requesting the access token.
     */
    claims?: string[];
    /**
     * An optional flag indicating whether to attempt the token acquisition silently or allow a prompt to be shown.
     */
    silent?: boolean;
    /**
     * An optional identifier of the home tenant for which to acquire the access token for (used in cross-tenant shared channels).
     */
    tenantId?: string;
}
/**
 * @deprecated
 * As of TeamsJS v2.0.0, please use {@link AuthTokenRequestParameters} instead.
 */
export type AuthTokenRequest = AuthTokenRequestParameters & LegacyCallBacks;
/**
 * @hidden
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export interface UserProfile {
    /**
     * @hidden
     * The intended recipient of the token. The application that receives the token must verify that the audience
     * value is correct and reject any tokens intended for a different audience.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    aud: string;
    /**
     * @hidden
     * Identifies how the subject of the token was authenticated.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    amr: string[];
    /**
     * @hidden
     * Stores the time at which the token was issued. It is often used to measure token freshness.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    iat: number;
    /**
     * @hidden
     * Identifies the security token service (STS) that constructs and returns the token. In the tokens that Microsoft Entra
     * returns, the issuer is sts.windows.net. The GUID in the issuer claim value is the tenant ID of the Microsoft Entra
     * directory. The tenant ID is an immutable and reliable identifier of the directory.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    iss: string;
    /**
     * @hidden
     * Provides the last name, surname, or family name of the user as defined in the Microsoft Entra user object.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    family_name: string;
    /**
     * @hidden
     * Provides the first or "given" name of the user, as set on the Microsoft Entra user object.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    given_name: string;
    /**
     * @hidden
     * Provides a human-readable value that identifies the subject of the token. This value is not guaranteed to
     * be unique within a tenant and is designed to be used only for display purposes.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    unique_name: string;
    /**
     * @hidden
     * Contains a unique identifier of an object in Microsoft Entra. This value is immutable and cannot be reassigned or
     * reused. Use the object ID to identify an object in queries to Microsoft Entra.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    oid: string;
    /**
     * @hidden
     * Identifies the principal about which the token asserts information, such as the user of an application.
     * This value is immutable and cannot be reassigned or reused, so it can be used to perform authorization
     * checks safely. Because the subject is always present in the tokens the Microsoft Entra issues, we recommended
     * using this value in a general-purpose authorization system.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    sub: string;
    /**
     * @hidden
     * An immutable, non-reusable identifier that identifies the directory tenant that issued the token. You can
     * use this value to access tenant-specific directory resources in a multitenant application. For example,
     * you can use this value to identify the tenant in a call to the Graph API.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    tid: string;
    /**
     * @hidden
     * Defines the end of the time interval within which a token is valid. The service that validates the token
     * should verify that the current date is within the token lifetime; otherwise it should reject the token. The
     * service might allow for up to five minutes beyond the token lifetime to account for any differences in clock
     * time ("time skew") between Microsoft Entra and the service.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    exp: number;
    /**
     * @hidden
     * Defines the start of the time interval within which a token is valid. The service that validates the token
     * should verify that the current date is within the token lifetime; otherwise it should reject the token. The
     * service might allow for up to five minutes beyond the token lifetime to account for any differences in clock
     * time ("time skew") between Microsoft Entra and the service.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    nbf: number;
    /**
     * @hidden
     * Stores the user name of the user principal.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    upn: string;
    /**
     * @hidden
     * Stores the version number of the token.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    ver: string;
    /**
     * @hidden
     * Stores the data residency of the user.
     *
     * @internal
     * Limited to Microsoft-internal use
     */
    dataResidency?: DataResidency;
}
/**
 * @hidden
 * Limited set of data residencies information exposed to 1P application developers
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare enum DataResidency {
    /**
     * Public
     */
    Public = "public",
    /**
     * European Union Data Boundary
     */
    EUDB = "eudb",
    /**
     * Other, stored to cover fields that will not be exposed
     */
    Other = "other"
}
/**
 * @deprecated
 * As of TeamsJS v2.0.0, this interface has been deprecated in favor of a Promise-based pattern.
 * @hidden
 * Describes the UserRequest. Success callback describes how a successful request is handled.
 * Failure callback describes how a failed request is handled.
 * @internal
 * Limited to Microsoft-internal use
 */
export interface UserRequest {
    /**
     * A function that is called if the token request succeeds, with the resulting token.
     */
    successCallback?: (user: UserProfile) => void;
    /**
     * A function that is called if the token request fails, with the reason for the failure.
     */
    failureCallback?: (reason: string) => void;
}