@microsoft/teams-ai/lib/authentication/Authentication.d.ts

SDK focused on building AI based applications for Microsoft Teams.

/**
 * @module teams-ai
 */
/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */
import { Storage, TurnContext } from 'botbuilder';
import { OAuthPromptSettings } from 'botbuilder-dialogs';
import { Application, Selector } from '../Application';
import { TurnState } from '../TurnState';
import { AdaptiveCardAuthenticationBase } from './AdaptiveCardAuthenticationBase';
import { BotAuthenticationBase } from './BotAuthenticationBase';
import { MessageExtensionAuthenticationBase } from './MessageExtensionAuthenticationBase';
import { TeamsSsoSettings } from './TeamsSsoSettings';
/**
 * User authentication service.
 */
export declare class Authentication<TState extends TurnState> {
    private readonly _adaptiveCardAuth;
    private readonly _messageExtensionAuth;
    private readonly _botAuth;
    private readonly _name;
    private readonly _msal?;
    /**
     * The authentication settings.
     */
    readonly settings: OAuthSettings | TeamsSsoSettings;
    /**
     * Creates a new instance of the `Authentication` class.
     * @param {Application} app - The application instance.
     * @param {string} name - The name of the connection.
     * @param {OAuthSettings} settings - Authentication settings.
     * @param {Storage} storage - A storage instance otherwise Memory Storage is used.
     * @param {MessageExtensionAuthenticationBase} messageExtensionsAuth - Handles message extension flow authentication.
     * @param {BotAuthenticationBase} botAuth - Handles bot-flow authentication.
     * @param {AdaptiveCardAuthenticationBase} adaptiveCardAuth - Handles adaptive card authentication.
     */
    constructor(app: Application<TState>, name: string, settings: OAuthSettings | TeamsSsoSettings, storage?: Storage, messageExtensionsAuth?: MessageExtensionAuthenticationBase, botAuth?: BotAuthenticationBase<TState>, adaptiveCardAuth?: AdaptiveCardAuthenticationBase);
    /**
     * Signs in a user.
     * This method will be called automatically by the Application class.
     * @template TState
     * @param {TurnContext} context - Current turn context.
     * @param {TState} state Application state.
     * @returns {string | undefined} The authentication token or undefined if the user is still login in.
     */
    signInUser(context: TurnContext, state: TState): Promise<string | undefined>;
    /**
     * Signs out a user.
     * @template TState
     * @param {TurnContext} context - Current turn context.
     * @param {TState} state - Application state.
     * @returns {Promise<void>} A Promise representing the asynchronous operation.
     */
    signOutUser(context: TurnContext, state: TState): Promise<void>;
    /**
     * Check if the user is signed, if they are then return the token.
     * @param {TurnContext} context Current turn context.
     * @returns {string | undefined} The token string or undefined if the user is not signed in.
     */
    isUserSignedIn(context: TurnContext): Promise<string | undefined>;
    /**
     * The handler function is called when the user has successfully signed in.
     * This only applies if sign in was initiated by the user sending a message to the bot.
     * This handler will not be triggered if a message extension triggered the authentication flow.
     * @template TState
     * @param {(context: TurnContext, state: TState) => Promise<void>} handler The handler function to call when the user has successfully signed in
     */
    onUserSignInSuccess(handler: (context: TurnContext, state: TState) => Promise<void>): void;
    /**
     * This handler function is called when the user sign in flow fails.
     * This only applies if sign in was initiated by the user sending a message to the bot.
     * This handler will not be triggered if a message extension triggered the authentication flow.
     * @template TState
     * @param {(context: TurnContext, state: TState, error: AuthError) => Promise<void>} handler The handler function to call when the user failed to signed in.
     */
    onUserSignInFailure(handler: (context: TurnContext, state: TState, error: AuthError) => Promise<void>): void;
    private isOAuthSettings;
    private acquireTokenFromMsalCache;
    private removeTokenFromMsalCache;
}
/**
 * The user authentication manager.
 */
export declare class AuthenticationManager<TState extends TurnState> {
    private readonly _authentications;
    readonly default: string;
    /**
     * Creates a new instance of the `AuthenticationManager` class.
     * @param {Application} app - The application instance.
     * @param {AuthenticationOptions} options - Authentication options.
     * @param {Storage} storage - A storage instance otherwise Memory Storage is used.
     */
    constructor(app: Application<TState>, options: AuthenticationOptions, storage?: Storage);
    /**
     * @template TState
     * Gets the authentication instance for the specified connection name.
     * @param {string} name The setting name.
     * @returns {Authentication<TState>} The authentication instance.
     */
    get(name: string): Authentication<TState>;
    /**
     * Signs in a user.
     * @template TState
     * @param {TurnContext} context The turn context.
     * @param {TState} state The turn state.
     * @param {string} settingName Optional. The name of the setting to use. If not specified, the default setting name is used.
     * @returns {Promise<SignInResponse>} The sign in response.
     */
    signUserIn(context: TurnContext, state: TState, settingName?: string): Promise<SignInResponse>;
    /**
     * Signs out a user.
     * @template TState
     * @param {TurnContext} context The turn context.
     * @param {TState} state The turn state.
     * @param {string} settingName Optional. The name of the setting to use. If not specified, the default setting name is used.
     */
    signOutUser(context: TurnContext, state: TState, settingName?: string): Promise<void>;
}
/**
 * Settings used to configure user authentication through the OAuthPrompt.
 */
export type OAuthSettings = OAuthPromptSettings & {
    /**
     * Optional. Set this to enable SSO when authentication user using adaptive cards.
     */
    tokenExchangeUri?: string;
    /**
     * Optional. Set to `true` to enable SSO when authenticating using AAD.
     */
    enableSso?: boolean;
};
/**
 * The options to configure the authentication manager
 */
export interface AuthenticationOptions {
    /**
     * The authentication settings.
     * Key uniquely identifies the connection string.
     */
    settings: {
        [key: string]: OAuthSettings | TeamsSsoSettings;
    };
    /**
     * Describes the setting the bot should use if the user does not specify a setting name.
     */
    default?: string;
    /**
     * Defaults to true.
     * Indicates whether the bot should start the sign in flow when the user sends a message to the bot or triggers a message extension.
     * If set to false, the bot will not start the sign in flow before routing the activity to the bot logic.
     *
     * To set custom logic, set this property to the selector function.
     */
    autoSignIn?: boolean | Selector;
}
/**
 * The sign in response.
 */
export type SignInResponse = {
    /**
     * The sign in status.
     */
    status: SignInStatus;
    /**
     * The error returned.
     */
    error?: unknown;
    /**
     * The cause of the error.
     */
    cause?: AuthErrorReason;
};
/**
 * An error thrown when an authentication error occurs.
 */
export declare class AuthError extends Error {
    /**
     * The cause of the error.
     */
    readonly cause: AuthErrorReason;
    /**
     * Creates a new instance of the `AuthError` class.
     * @param {string} message The error message.
     * @param {AuthErrorReason} reason Optional. Cause of the error. Defaults to `other`.
     */
    constructor(message?: string, reason?: AuthErrorReason);
}
/**
 * Cause of an authentication error.
 * @remarks
 * `invalidActivity` - The activity is not a valid activity to initiate authentication flow.
 * `completionWithoutToken` - The authentication flow completed without a token.
 * `other` - Other error.
 */
export type AuthErrorReason = 'invalidActivity' | 'completionWithoutToken' | 'other';
/**
 * The sign in status.
 * @remarks
 * `pending` - The user is not signed in and the bot has initiated the sign in flow.
 * `complete` - The user has successfully signed in.
 * `error` - An error occurred while signing the user in.
 */
export type SignInStatus = 'pending' | 'complete' | 'error';
//# sourceMappingURL=Authentication.d.ts.map