OAuthPrompt class
Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) service.
- Extends
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
eventorinvokeactivity. - 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
messageactivity.
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
| OAuth |
Creates a new OAuthPrompt instance. |
Properties
| id | Unique ID of the dialog. Sets the unique ID of the dialog. |
| telemetry |
Gets the telemetry client for this dialog. Sets the telemetry client for this dialog. |
Inherited Properties
| End |
Gets a default end-of-turn result. |
Methods
| begin |
Called when a prompt dialog is pushed onto the dialog stack and is being activated. |
| continue |
Called when a prompt dialog is the active dialog and the user replied with a new activity. |
| get |
Attempts to retrieve the stored token for the current user. |
| recognize |
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. |
| send |
Sends an OAuth card. |
| sign |
Signs the user out of the service. |
Inherited Methods
| configure(Record<string, unknown>) | Fluent method for configuring the object. |
| end |
When overridden in a derived class, performs clean up for the dialog before it ends. |
| get |
|
| get |
An encoded string used to aid in the detection of bot changes on re-deployment. |
| on |
Called when an event has been raised, using |
| reprompt |
When overridden in a derived class, reprompts the user for input. |
| resume |
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 idProperty 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 telemetryClientProperty Value
BotTelemetryClient
The BotTelemetryClient to use for logging.
Inherited Property Details
EndOfTurn
Gets a default end-of-turn result.
static EndOfTurn: DialogTurnResultProperty Value
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
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
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
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>): thisParameters
- 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
Inherited From Dialog.endDialog
getConverter(string)
function getConverter(_property: string): Converter | ConverterFactoryParameters
- _property
-
string
The key of the conditional selector configuration.
Returns
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(): stringReturns
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
The dialog context for the current turn of conversation.
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
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
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
Inherited From Dialog.resumeDialog