OAuthPrompt class

Package:

botbuilder-dialogs

Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) service.

Extends

Dialog

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:

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();
         }
     }
]));

Constructors

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

Creates a new OAuthPrompt instance.

Properties

id	Unique ID of the dialog. Sets the unique ID of the dialog.
telemetryClient	Gets the telemetry client for this dialog. Sets the telemetry client for this dialog.

Inherited Properties

EndOfTurn

Gets a default end-of-turn result.

Methods

beginDialog(DialogContext, PromptOptions)	Called when a prompt dialog is pushed onto the dialog stack and is being activated.
continueDialog(DialogContext)	Called when a prompt dialog is the active dialog and the user replied with a new activity.
getUserToken(TurnContext, string)	Attempts to retrieve the stored token for the current user.
recognizeToken(DialogContext)	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.
sendOAuthCard(OAuthPromptSettings, TurnContext, string | Partial<Activity>)	Sends an OAuth card.
signOutUser(TurnContext)	Signs the user out of the service.

Inherited Methods

configure(Record<string, unknown>)	Fluent method for configuring the object.
endDialog(TurnContext, DialogInstance, DialogReason)	When overridden in a derived class, performs clean up for the dialog before it ends.
getConverter(string)
getVersion()	An encoded string used to aid in the detection of bot changes on re-deployment.
onDialogEvent(DialogContext, DialogEvent)	Called when an event has been raised, using DialogContext.emitEvent(), by either the current dialog or a dialog that the current dialog started.
repromptDialog(TurnContext, DialogInstance)	When overridden in a derived class, reprompts the user for input.
resumeDialog(DialogContext, DialogReason, any)	When overridden in a derived class, resumes the dialog after the dialog above it on the stack completes.

Constructor Details

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

Creates a new OAuthPrompt instance.

new OAuthPrompt(dialogId: string, settings: OAuthPromptSettings, validator?: PromptValidator<TokenResponse>)

Parameters

dialogId

string

Unique ID of the dialog within its parent DialogSet or ComponentDialog.

settings

OAuthPromptSettings

Settings used to configure the prompt.

validator

PromptValidator<TokenResponse>

(Optional) validator that will be called each time the user responds to the prompt.

Property Details

id

Unique ID of the dialog. Sets the unique ID of the dialog.

string id

Property Value

string

The Id for the dialog.

Remarks

This will be automatically generated if not specified.

telemetryClient

Gets the telemetry client for this dialog. Sets the telemetry client for this dialog.

BotTelemetryClient telemetryClient

Property Value

BotTelemetryClient

The BotTelemetryClient to use for logging.

Inherited Property Details

EndOfTurn

Gets a default end-of-turn result.

static EndOfTurn: DialogTurnResult

Property Value

DialogTurnResult

Remarks

This result indicates that a dialog (or a logical step within a dialog) has completed processing for the current turn, is still active, and is waiting for more input.

Inherited From Dialog.EndOfTurn

Method Details

beginDialog(DialogContext, PromptOptions)

Called when a prompt dialog is pushed onto the dialog stack and is being activated.

function beginDialog(dc: DialogContext, options?: PromptOptions): Promise<DialogTurnResult>

Parameters

dc

DialogContext

The DialogContext for the current turn of the conversation.

options

PromptOptions

Optional. PromptOptions, additional information to pass to the prompt being started.

Returns

Promise<DialogTurnResult>

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.

continueDialog(DialogContext)

Called when a prompt dialog is the active dialog and the user replied with a new activity.

function continueDialog(dc: DialogContext): Promise<DialogTurnResult>

Parameters

dc

DialogContext

The DialogContext for the current turn of the conversation.

Returns

Promise<DialogTurnResult>

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.

getUserToken(TurnContext, string)

Attempts to retrieve the stored token for the current user.

function getUserToken(context: TurnContext, code?: string): Promise<TokenResponse | undefined>

Parameters

context

TurnContext

Context reference the user that's being looked up.

code

string

(Optional) login code received from the user.

Returns

Promise<TokenResponse | undefined>

The token response.

recognizeToken(DialogContext)

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.

function recognizeToken(dc: DialogContext): Promise<PromptRecognizerResult<TokenResponse>>

Parameters

dc

DialogContext

The DialogContext for the current turn of the conversation.

Returns

Promise<PromptRecognizerResult<TokenResponse>>

A Promise that resolves to the result

sendOAuthCard(OAuthPromptSettings, TurnContext, string | Partial<Activity>)

Sends an OAuth card.

static function sendOAuthCard(settings: OAuthPromptSettings, turnContext: TurnContext, prompt?: string | Partial<Activity>): Promise<void>

Parameters

settings

OAuthPromptSettings

OAuth settings.

turnContext

TurnContext

Turn context.

prompt

string | Partial<Activity>

Message activity.

Returns

Promise<void>

signOutUser(TurnContext)

Signs the user out of the service.

function signOutUser(context: TurnContext): Promise<void>

Parameters

context

TurnContext

Context referencing the user that's being signed out.

Returns

Promise<void>

A promise representing the asynchronous operation.

Remarks

This example shows creating an instance of the prompt and then signing out the user.

const prompt = new OAuthPrompt({
   connectionName: 'GitConnection',
   title: 'Login To GitHub'
});
await prompt.signOutUser(context);

Inherited Method Details

configure(Record<string, unknown>)

Fluent method for configuring the object.

function configure(config: Record<string, unknown>): this

Parameters

config

Record<string, unknown>

Configuration settings to apply.

Returns

this

The Configurable after the operation is complete.

Inherited From Configurable.configure

endDialog(TurnContext, DialogInstance, DialogReason)

When overridden in a derived class, performs clean up for the dialog before it ends.

function endDialog(_context: TurnContext, _instance: DialogInstance, _reason: DialogReason): Promise<void>

Parameters

_context

TurnContext

The context object for the turn.

_instance

DialogInstance

Current state information for this dialog.

_reason

DialogReason

The reason the dialog is ending.

Returns

Promise<void>

Remarks

Derived dialogs that need to perform logging or cleanup before ending should override this method. By default, this method has no effect.

The DialogContext calls this method when the current dialog is ending.

See also

• DialogContext.cancelAllDialogs
• DialogContext.endDialog
• DialogContext.replaceDialog

Inherited From Dialog.endDialog

getConverter(string)

function getConverter(_property: string): Converter | ConverterFactory

Parameters

_property

string

The key of the conditional selector configuration.

Returns

Converter | ConverterFactory

The converter for the selector configuration.

Inherited From Configurable.getConverter

getVersion()

An encoded string used to aid in the detection of bot changes on re-deployment.

function getVersion(): string

Returns

string

Unique string which should only change when dialog has changed in a way that should restart the dialog.

Remarks

This defaults to returning the dialogs id but can be overridden to provide more precise change detection logic. Any dialog on the stack that has its version change will result in a versionChanged event will be raised. If this event is not handled by the bot, an error will be thrown resulting in the bots error handler logic being run.

Returning an empty string will disable version tracking for the component all together.

Inherited From Dialog.getVersion

onDialogEvent(DialogContext, DialogEvent)

Called when an event has been raised, using DialogContext.emitEvent(), by either the current dialog or a dialog that the current dialog started.

function onDialogEvent(dc: DialogContext, e: DialogEvent): Promise<boolean>

Parameters

dc

DialogContext

The dialog context for the current turn of conversation.

e

DialogEvent

The event being raised.

Returns

Promise<boolean>

True if the event is handled by the current dialog and bubbling should stop.

Inherited From Dialog.onDialogEvent

repromptDialog(TurnContext, DialogInstance)

When overridden in a derived class, reprompts the user for input.

function repromptDialog(_context: TurnContext, _instance: DialogInstance): Promise<void>

Parameters

_context

TurnContext

The context object for the turn.

_instance

DialogInstance

Current state information for this dialog.

Returns

Promise<void>

Remarks

Derived dialogs that support validation and re-prompt logic should override this method. By default, this method has no effect.

The DialogContext calls this method when the current dialog should re-request input from the user. This method is implemented for prompt dialogs.

See also

• DialogContext.repromptDialog
• Prompt

Inherited From Dialog.repromptDialog

resumeDialog(DialogContext, DialogReason, any)

When overridden in a derived class, resumes the dialog after the dialog above it on the stack completes.

function resumeDialog(dc: DialogContext, reason: DialogReason, result?: any): Promise<DialogTurnResult>

Parameters

dc

DialogContext

The context for the current dialog turn.

reason

DialogReason

The reason the dialog is resuming. This will typically be DialogReason.endCalled

result

any

Optional. The return value, if any, from the dialog that ended.

Returns

Promise<DialogTurnResult>

A promise resolving to the dialog turn result.

Remarks

Derived dialogs that support multiple-turn conversations should override this method. By default, this method signals that the dialog is complete and returns.

The DialogContext calls this method when it resumes the dialog. If the previous dialog on the stack returned a value, that value is in the result parameter.

To start a child dialog, use DialogContext.beginDialog or DialogContext.prompt; however, this dialog will not necessarily be the one that started the child dialog. To signal to the dialog context that this dialog has completed, await DialogContext.endDialog before exiting this method.

See also

• DialogContext.endDialog

Inherited From Dialog.resumeDialog