@microsoft/teams-js/dist/esm/packages/teams-js/dts/private/externalAppAuthentication.d.ts

Microsoft Client SDK for building app for Microsoft hosts

/**
 * @hidden
 * Module to delegate authentication and message extension requests to the host
 * @internal
 * Limited to Microsoft-internal use
 * @module
 */
import { ResponseHandler } from '../internal/responseHandler';
import { UUID } from '../public';
import { ISerializable } from '../public/serializable.interface';
/*********** BEGIN REQUEST TYPE ************/
/**
 * @hidden
 * Information about the bot request that should be resent by the host
 * @internal
 * Limited to Microsoft-internal use
 */
export type IOriginalRequestInfo = IQueryMessageExtensionRequest | IActionExecuteInvokeRequest;
/**
 * @hidden
 * Parameters OauthWindow
 * @internal
 * Limited to Microsoft-internal use
 */
export type OauthWindowProperties = {
    /**
     * 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
     * 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;
};
/**
 * @hidden
 * Parameters for the authentication pop-up. This interface is used exclusively with the externalAppAuthentication APIs
 * @internal
 * Limited to Microsoft-internal use
 */
export type AuthenticatePopUpParameters = {
    /**
     * The URL for the authentication pop-up.
     */
    url: URL;
    /**
     * 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;
};
/**
 * @hidden
 * Parameters for SSO authentication. This interface is used exclusively with the externalAppAuthentication APIs
 * @internal
 * Limited to Microsoft-internal use
 */
export type AuthTokenRequestParameters = {
    /**
     * 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;
};
/**
 * @hidden
 * Information about the message extension request that should be resent by the host. Corresponds to request schema in https://learn.microsoft.com/microsoftteams/platform/resources/messaging-extension-v3/search-extensions#receive-user-requests
 * @internal
 * Limited to Microsoft-internal use
 */
export interface IQueryMessageExtensionRequest {
    requestType: OriginalRequestType.QueryMessageExtensionRequest;
    commandId: string;
    parameters: {
        name: string;
        value: string;
    }[];
    queryOptions?: {
        count: number;
        skip: number;
    };
}
/**
 * @hidden
 * Information about the Action.Execute request that should be resent by the host. Corresponds to schema in https://adaptivecards.io/explorer/Action.Execute.html
 * @internal
 * Limited to Microsoft-internal use
 */
export interface IActionExecuteInvokeRequest {
    requestType: OriginalRequestType.ActionExecuteInvokeRequest;
    type: string;
    id: string;
    verb: string;
    data: string | Record<string, unknown>;
}
/**
 * @hidden
 * @internal
 * Limited to Microsoft-internal use
 */
export declare class SerializableActionExecuteInvokeRequest implements ISerializable {
    private invokeRequest;
    constructor(invokeRequest: IActionExecuteInvokeRequest);
    serialize(): object | string;
}
/**
 * @beta
 * @hidden
 * Determines if the provided response object is an instance of IActionExecuteResponse
 * @internal
 * Limited to Microsoft-internal use
 * @param response The object to check whether it is of IActionExecuteResponse type
 */
export declare function isActionExecuteResponse(response: unknown): response is IActionExecuteResponse;
/**
 * @hidden
 * This is the only allowed value for IActionExecuteInvokeRequest.type. Used for validation
 * @internal
 * Limited to Microsoft-internal use
 */
export declare const ActionExecuteInvokeRequestType = "Action.Execute";
/**
 * @hidden
 * Used to differentiate between IOriginalRequestInfo types
 * @internal
 * Limited to Microsoft-internal use
 */
export declare enum OriginalRequestType {
    ActionExecuteInvokeRequest = "ActionExecuteInvokeRequest",
    QueryMessageExtensionRequest = "QueryMessageExtensionRequest"
}
/*********** END REQUEST TYPE ************/
/*********** BEGIN RESPONSE TYPE ************/
/**
 * @hidden
 * The response from the bot returned via the host
 * @internal
 * Limited to Microsoft-internal use
 */
export type IInvokeResponse = IQueryMessageExtensionResponse | IActionExecuteResponse;
/**
 * @hidden
 * Used to differentiate between IInvokeResponse types
 * @internal
 * Limited to Microsoft-internal use
 */
export declare enum InvokeResponseType {
    ActionExecuteInvokeResponse = "ActionExecuteInvokeResponse",
    QueryMessageExtensionResponse = "QueryMessageExtensionResponse"
}
/**
 * @hidden
 * The response from the bot returned via the host for a message extension query request.
 * @internal
 * Limited to Microsoft-internal use
 */
export interface IQueryMessageExtensionResponse {
    responseType: InvokeResponseType.QueryMessageExtensionResponse;
    composeExtension?: ComposeExtensionResponse;
}
/**
 * @hidden
 * The response from the bot returned via the host for an Action.Execute request.
 * @internal
 * Limited to Microsoft-internal use
 */
export interface IActionExecuteResponse {
    responseType: InvokeResponseType.ActionExecuteInvokeResponse;
    value: Record<string, unknown>;
    signature?: string;
    statusCode: number;
    type: string;
}
/**
 * @hidden
 * @internal
 * Limited to Microsoft-internal use
 */
export declare class ActionExecuteResponseHandler extends ResponseHandler<IActionExecuteResponse, IActionExecuteResponse> {
    validate(response: IActionExecuteResponse): boolean;
    deserialize(response: IActionExecuteResponse): IActionExecuteResponse;
}
/**
 * @hidden
 * The compose extension response returned for a message extension query request. `suggestedActions` will be present only when the type is is 'config' or 'auth'.
 * @internal
 * Limited to Microsoft-internal use
 */
export type ComposeExtensionResponse = {
    attachmentLayout: AttachmentLayout;
    type: ComposeResultTypes;
    attachments?: QueryMessageExtensionAttachment[];
    suggestedActions?: QueryMessageExtensionSuggestedActions;
    text?: string;
};
/**
 * @hidden
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export type QueryMessageExtensionSuggestedActions = {
    actions: Action[];
};
/**
 * @hidden
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export type Action = {
    type: string;
    title: string;
    value: string;
};
/**
 * @hidden
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export type QueryMessageExtensionCard = {
    contentType: string;
    content: Record<string, unknown>;
    fallbackHtml?: string;
    signature?: string;
};
/**
 * @hidden
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export type QueryMessageExtensionAttachment = QueryMessageExtensionCard & {
    preview?: QueryMessageExtensionCard;
};
/**
 * @hidden
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export type AttachmentLayout = 'grid' | 'list';
/**
 * @hidden
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export type ComposeResultTypes = 'auth' | 'config' | 'message' | 'result' | 'silentAuth';
/*********** END RESPONSE TYPE ************/
/*********** BEGIN ERROR TYPE ***********/
export interface InvokeError {
    errorCode: InvokeErrorCode;
    message?: string;
}
/**
 * @beta
 * @hidden
 * Determines if the provided error object is an instance of InvokeError
 * @internal
 * Limited to Microsoft-internal use
 * @param err The error object to check whether it is of InvokeError type
 */
export declare function isInvokeError(err: unknown): err is InvokeError;
/**
 * @hidden
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare enum InvokeErrorCode {
    INTERNAL_ERROR = "INTERNAL_ERROR"
}
/**
 * @hidden
 * Wrapper to differentiate between InvokeError and IInvokeResponse response from host
 * @internal
 * Limited to Microsoft-internal use
 */
export type InvokeErrorWrapper = InvokeError & {
    responseType: undefined;
};
/**
 * @beta
 * @hidden
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function validateActionExecuteInvokeRequest(actionExecuteRequest: IActionExecuteInvokeRequest): void;
/**
 * @beta
 * @hidden
 * Signals to the host to perform authentication using the given authentication parameters and then resend the request to the application specified by the app ID with the authentication result.
 * @internal
 * Limited to Microsoft-internal use
 * @param appId ID of the application backend to which the request and authentication response should be sent. This must be a UUID
 * @param authenticateParameters Parameters for the authentication pop-up
 * @param originalRequestInfo Information about the original request that should be resent
 * @returns A promise that resolves to the IInvokeResponse from the application backend and rejects with InvokeError if the host encounters an error while authenticating or resending the request
 */
export declare function authenticateAndResendRequest(appId: string, authenticateParameters: AuthenticatePopUpParameters, originalRequestInfo: IOriginalRequestInfo): Promise<IInvokeResponse>;
/**
 * @beta
 * @hidden
 * Signals to the host to perform SSO authentication for the application specified by the app ID
 * @internal
 * Limited to Microsoft-internal use
 * @param appId ID of the application backend for which the host should attempt SSO authentication. This must be a UUID
 * @param authTokenRequest Parameters for SSO authentication
 * @returns A promise that resolves when authentication and succeeds and rejects with InvokeError on failure
 */
export declare function authenticateWithSSO(appId: string, authTokenRequest: AuthTokenRequestParameters): Promise<void>;
/**
 * @beta
 * @hidden
 * Signals to the host to perform SSO authentication for the application specified by the app ID and then resend the request to the application backend with the authentication result
 * @internal
 * Limited to Microsoft-internal use
 * @param appId ID of the application backend for which the host should attempt SSO authentication and resend the request and authentication response. This must be a UUID.
 * @param authTokenRequest Parameters for SSO authentication
 * @param originalRequestInfo Information about the original request that should be resent
 * @returns A promise that resolves to the IInvokeResponse from the application backend and rejects with InvokeError if the host encounters an error while authenticating or resending the request
 */
export declare function authenticateWithSSOAndResendRequest(appId: string, authTokenRequest: AuthTokenRequestParameters, originalRequestInfo: IOriginalRequestInfo): Promise<IInvokeResponse>;
/**
 * @beta
 * @hidden
 * Signals to the host to perform Oauth2 authentication for the application specified by the title ID
 * @internal
 * Limited to Microsoft-internal use
 * @param titleId ID of the acquisition
 * @param oauthConfigId lookup ID in token store
 * @param oauthWindowParameters parameters for the signIn window
 * @returns A promise that resolves when authentication succeeds and rejects with InvokeError on failure
 */
export declare function authenticateWithOauth2(titleId: string, oauthConfigId: string, oauthWindowParameters: OauthWindowProperties): Promise<void>;
/**
 * @beta
 * @hidden
 * API to authenticate power platform connector plugins
 * @internal
 * Limited to Microsoft-internal use
 * @param titleId ID of the acquisition
 * @param signInUrl signInUrl for the connctor page listing the connector. This is optional
 * @param oauthWindowParameters parameters for the signIn window
 * @returns A promise that resolves when authentication succeeds and rejects with InvokeError on failure
 */
export declare function authenticateWithPowerPlatformConnectorPlugins(titleId: string, signInUrl?: URL, oauthWindowParameters?: OauthWindowProperties): Promise<void>;
/**
 * Parameters required to authenticate with connectors.
 *
 * @beta
 * @hidden
 * @internal
 * Limited to Microsoft-internal use
 *
 * @property connectorId - The unique identifier for the connector.
 * @property oauthConfigId - The OAuth configuration ID associated with the connector.
 * @property correlationVector - The correlation vector (UUID) for tracking the authentication request. If not provided, one will be generated.
 */
export interface ConnectorParameters {
    /** The unique identifier for the connector. */
    connectorId: string;
    /** The OAuth configuration ID associated with the connector. */
    oAuthConfigId: string;
    /** The trace ID (UUID) for tracking the authentication request. */
    traceId: UUID;
    /** Optional parameters for the OAuth sign-in window. */
    windowParameters?: OauthWindowProperties;
}
export declare class SerializableConnectorParameters implements ISerializable {
    private param;
    constructor(param: ConnectorParameters);
    serialize(): object;
}
/**
 * @beta
 * @hidden
 * Signals to the host to perform authentication with connectors using the provided parameters.
 *
 * @internal
 * Limited to Microsoft-internal use
 *
 * @param input - The parameters required for connectors authentication, including connectorId, oauthConfigId, and optional oauthWindowParameters.
 * @returns A promise that resolves when authentication succeeds and rejects with InvokeError on failure.
 * @throws Error if {@linkcode app.initialize} has not successfully completed
 */
export declare function authenticateWithConnector(input: ConnectorParameters): Promise<void>;
/**
 * @hidden
 * Represents the possible authentication states for a user in the context of federated connectors.
 *
 * @enum {number}
 * @property {number} Invalid - The authentication state is invalid or not established.
 * @property {number} Valid - The authentication state is valid and the user is authenticated.
 * @property {number} Expired - The authentication state has expired and re-authentication is required.
 * @internal
 * Limited to Microsoft-internal use
 */
export declare enum UserAuthenticationState {
    /** The authentication state is invalid or not established. */
    Invalid = "Invalid",
    /** The authentication state is valid and the user is authenticated. */
    Valid = "Valid",
    /** The authentication state has expired and re-authentication is required. */
    Expired = "Expired"
}
/**
 * @beta
 * @hidden
 * Retrieves the authentication state for a user for a given federated connector.
 *
 * @internal
 * Limited to Microsoft-internal use
 *
 * @param connectorId - The unique identifier for the federated connector.
 * @param oauthConfigId - The OAuth configuration ID associated with the connector.
 * @returns A promise that resolves to the user's authentication state for the federated connector.
 * @throws Error if the capability is not supported or if initialization has not completed.
 */
export declare function getUserAuthenticationStateForConnector(input: ConnectorParameters): Promise<UserAuthenticationState>;
/**
 * @beta
 * @hidden
 * Retrieves the authentication state for a user for a given federated connector.
 *
 * @internal
 * Limited to Microsoft-internal use
 *
 * @param connectorId - The unique identifier for the federated connector.
 * @param oauthConfigId - The OAuth configuration ID associated with the connector.
 * @returns A promise that resolves when the connector is successfully disconnected and rejects with InvokeError on failure.
 * @throws Error if the capability is not supported or if initialization has not completed.
 */
export declare function disconnectConnector(input: ConnectorParameters): Promise<void>;
/**
 * @hidden
 * Checks if the externalAppAuthentication capability is supported by the host
 * @returns boolean to represent whether externalAppAuthentication capability is supported
 *
 * @throws Error if {@linkcode app.initialize} has not successfully completed
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function isSupported(): boolean;