[JS] feat: Authentication

[singhk97]

Linked issues

closes: #738, #739

Details

Foundations of handling user authentication.

1. Authentication class encapsulates logic to authentication for a single connection.
   • It currently supports bot and messaging extension authentication through the OAuthPrompt, using BF Token service implicitly.
   • Subsequent PR will include support bot and messaging extension authentication without BF Token service.
2. AuthenticationManager class handles multiple user configured connections and exposes signInUser and signOutUser methods for application code initiate authentication.
3. Users create AuthenticationOptions object to configure authentication:
   • settings: contains one or more user authentication settings
   • default: the default setting to use in the auto sign in flow.
   • autoSignIn: whether to sign user in by default at the start of every turn. Set to true by default.

Public api:

Authentication.ts

/**
 * User authentication service.
 */
export class Authentication<TState extends TurnState = DefaultTurnState> {
    public readonly settings: OAuthPromptSettings;

    /**
     * Creates a new instance of the `Authentication` class.
     * @param {Application} app - The application instance.
     * @param {string} name - The name of the connection.
     * @param {OAuthPromptSettings} settings - Authentication settings.
     * @param {Storage} storage - A storage instance otherwise Memory Storage is used.
     * @param {MessagingExtensionAuthentication} messagingExtensionsAuth - Handles messaging extension flow authentication.
     * @param {BotAuthentication} botAuth - Handles bot-flow authentication.
     */
    constructor(
        app: Application<TState>,
        name: string,
        settings: OAuthPromptSettings,
        storage?: Storage,
        messagingExtensionsAuth?: MessagingExtensionAuthentication,
        botAuth?: BotAuthentication<TState>
    );

    /**
     * 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.
     */
    public 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.
     */
    public signOutUser(context: TurnContext, state: TState): Promise<void>;

    /**
     * Check is the user is signed, if they are then returns the token.
     * @param {TurnContext} context Current turn context.
     * @returns {string | undefined} The token string or undefined if the user is not signed in.
     */
    public 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 messaging 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
     */
    public onUserSignInSuccess(handler: (context: TurnContext, state: TState) => Promise<void>): Promise<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 messaging 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.
     */
    public onUserSignInFailure(
        handler: (context: TurnContext, state: TState, error: AuthError) => Promise<void>
    ): Promise<void>;
}

AuthenticationManager.ts

/**
 * The user authentication manager.
 */
export class AuthenticationManager<TState extends TurnState = DefaultTurnState> {
    /**
     * 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.
     */
    public 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.
     */
    public 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.
     */
    public signOutUser(context: TurnContext, state: TState, settingName?: string): Promise<void>;

AuthenticationOptions

/**
 * The options to configure the authentication manager
 */
export interface AuthenticationOptions {
    /**
     * The authentication settings.
     * Key uniquely identifies the connection string.
     */
    settings: { [key: string]: OAuthPromptSettings };

    /**
     * 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;
}

 

Task list

• Sso-auth bot sample
• Sso-auth message extension sample
• Support for multiple auth configurations (ex. AADv2, github auth...etc)
• Unit tests