botbuilder-dialogs
Version:
A dialog stack based conversation manager for Microsoft BotBuilder.
238 lines • 9.38 kB
TypeScript
/**
* @module botbuilder-dialogs
*/
/**
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License.
*/
import { Activity, CoreAppCredentials, TokenResponse, TurnContext } from 'botbuilder-core';
import { Dialog, DialogTurnResult } from '../dialog';
import { DialogContext } from '../dialogContext';
import { PromptOptions, PromptRecognizerResult, PromptValidator } from './prompt';
/**
* Settings used to configure an `OAuthPrompt` instance.
*/
export interface OAuthPromptSettings {
/**
* AppCredentials for OAuth.
*/
oAuthAppCredentials?: CoreAppCredentials;
/**
* Name of the OAuth connection being used.
*/
connectionName: string;
/**
* Title of the cards signin button.
*/
title: string;
/**
* (Optional) additional text to include on the signin card.
*/
text?: string;
/**
* (Optional) number of milliseconds the prompt will wait for the user to authenticate.
* Defaults to a value `900,000` (15 minutes.)
*/
timeout?: number;
/**
* (Optional) value indicating whether the OAuthPrompt should end upon
* receiving an invalid message. Generally the OAuthPrompt will ignore
* incoming messages from the user during the auth flow, if they are not related to the
* auth flow. This flag enables ending the OAuthPrompt rather than
* ignoring the user's message. Typically, this flag will be set to 'true', but is 'false'
* by default for backwards compatibility.
*/
endOnInvalidMessage?: boolean;
/**
* (Optional) value to force the display of a Sign In link overriding the default behavior.
* True to display the SignInLink.
*/
showSignInLink?: boolean;
}
/**
* Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO)
* service.
*
* @remarks
* The prompt will attempt to retrieve the users current token and if the user isn't signed in, it
* will send them an `OAuthCard` containing a button they can press to signin. Depending on the
* channel, the user will be sent through one of two possible signin flows:
*
* - The automatic signin flow where once the user signs in and the SSO service will forward the bot
* the users access token using either an `event` or `invoke` activity.
* - The "magic code" flow where where once the user signs in they will be prompted by the SSO
* service to send the bot a six digit code confirming their identity. This code will be sent as a
* standard `message` activity.
*
* Both flows are automatically supported by the `OAuthPrompt` and the only thing you need to be
* careful of is that you don't block the `event` and `invoke` activities that the prompt might
* be waiting on.
*
* > [!NOTE]
* > You should avoid persisting the access token with your bots other state. The Bot Frameworks
* > SSO service will securely store the token on your behalf. If you store it in your bots state
* > it could expire or be revoked in between turns.
* >
* > When calling the prompt from within a waterfall step you should use the token within the step
* > following the prompt and then let the token go out of scope at the end of your function.
*
* #### Prompt Usage
*
* When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named
* dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either
* `DialogContext.beginDialog()` or `DialogContext.prompt()`. The user will be prompted to signin as
* needed and their access token will be passed as an argument to the callers next waterfall step:
*
* ```JavaScript
* const { ConversationState, MemoryStorage, OAuthLoginTimeoutMsValue } = require('botbuilder');
* const { DialogSet, OAuthPrompt, WaterfallDialog } = require('botbuilder-dialogs');
*
* const convoState = new ConversationState(new MemoryStorage());
* const dialogState = convoState.createProperty('dialogState');
* const dialogs = new DialogSet(dialogState);
*
* dialogs.add(new OAuthPrompt('loginPrompt', {
* connectionName: 'GitConnection',
* title: 'Login To GitHub',
* timeout: OAuthLoginTimeoutMsValue // User has 15 minutes to login
* }));
*
* dialogs.add(new WaterfallDialog('taskNeedingLogin', [
* async (step) => {
* return await step.beginDialog('loginPrompt');
* },
* async (step) => {
* const token = step.result;
* if (token) {
*
* // ... continue with task needing access token ...
*
* } else {
* await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
* return await step.endDialog();
* }
* }
* ]));
* ```
*/
export declare class OAuthPrompt extends Dialog {
private settings;
private validator?;
private readonly PersistedCaller;
/**
* Creates a new OAuthPrompt instance.
*
* @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
* @param settings Settings used to configure the prompt.
* @param validator (Optional) validator that will be called each time the user responds to the prompt.
*/
constructor(dialogId: string, settings: OAuthPromptSettings, validator?: PromptValidator<TokenResponse>);
/**
* Called when a prompt dialog is pushed onto the dialog stack and is being activated.
*
* @param dc The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current
* turn of the conversation.
* @param options Optional. [PromptOptions](xref:botbuilder-dialogs.PromptOptions),
* additional information to pass to the prompt being started.
* @returns A `Promise` representing the asynchronous operation.
* @remarks
* If the task is successful, the result indicates whether the prompt is still
* active after the turn has been processed by the prompt.
*/
beginDialog(dc: DialogContext, options?: PromptOptions): Promise<DialogTurnResult>;
/**
* Called when a prompt dialog is the active dialog and the user replied with a new activity.
*
* @param dc The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn
* of the conversation.
* @returns A `Promise` representing the asynchronous operation.
* @remarks
* If the task is successful, the result indicates whether the dialog is still
* active after the turn has been processed by the dialog.
* The prompt generally continues to receive the user's replies until it accepts the
* user's reply as valid input for the prompt.
*/
continueDialog(dc: DialogContext): Promise<DialogTurnResult>;
/**
* Attempts to retrieve the stored token for the current user.
*
* @param context Context reference the user that's being looked up.
* @param code (Optional) login code received from the user.
* @returns The token response.
*/
getUserToken(context: TurnContext, code?: string): Promise<TokenResponse | undefined>;
/**
* Signs the user out of the service.
*
* @remarks
* This example shows creating an instance of the prompt and then signing out the user.
*
* ```JavaScript
* const prompt = new OAuthPrompt({
* connectionName: 'GitConnection',
* title: 'Login To GitHub'
* });
* await prompt.signOutUser(context);
* ```
* @param context Context referencing the user that's being signed out.
* @returns A promise representing the asynchronous operation.
*/
signOutUser(context: TurnContext): Promise<void>;
/**
* Sends an OAuth card.
*
* @param {OAuthPromptSettings} settings OAuth settings.
* @param {TurnContext} turnContext Turn context.
* @param {string | Partial<Activity>} prompt Message activity.
*/
static sendOAuthCard(settings: OAuthPromptSettings, turnContext: TurnContext, prompt?: string | Partial<Activity>): Promise<void>;
/**
* Shared implementation of the RecognizeTokenAsync function. This is intended for internal use, to consolidate
* the implementation of the OAuthPrompt and OAuthInput. Application logic should use those dialog classes.
*
* @param dc The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of the conversation.
* @returns A Promise that resolves to the result
*/
recognizeToken(dc: DialogContext): Promise<PromptRecognizerResult<TokenResponse>>;
/**
* @private
*/
private static createCallerInfo;
/**
* @private
*/
private getTokenExchangeInvokeResponse;
/**
* @private
*/
private static isFromStreamingConnection;
/**
* @private
*/
private static isTokenResponseEvent;
/**
* @private
*/
private static isTeamsVerificationInvoke;
/**
* @private
*/
private static isOAuthCardSupported;
/**
* @private
*/
private static isTokenExchangeRequestInvoke;
/**
* @private
*/
private static isTokenExchangeRequest;
/**
* @private
*/
private static channelSupportsOAuthCard;
/**
* @private
*/
private static channelRequiresSignInLink;
}
//# sourceMappingURL=oauthPrompt.d.ts.map