{tocify} $title={Table of Contents}
In Bot Framework Composer, you can use the user's OAuth login to enable your bot to access external resources using permissions granted by the end user. This article explains how to use basic OAuth to authenticate your bot with an external service such as GitHub.
Configure OAuth connection settings in Azure
The
following steps show how to configure OAuth connection settings to allow a bot
to access an external service, GitHub in the example.
• In
the Azure portal, go to the Azure Bot resource.
• In
the left pane, in the Settings section, select Configuration.
• In
the right pane, select Add OAuth Connection Settings.
• OAuth
setting in Azure portal
• In the New Connection Settings, enter the required information to configure the OAuth connection. Note that the options will differ depending on the service to access. The figure below shows the settings for configuring GitHub OAuth connection.
Note
• Record
the Name of your connection. you will need to enter this value in Composer
exactly as it is displayed in this setting.
• Enter
the values of Client ID, Client Secret, and optionally Scopes. To obtain these
values in this example of GitHub, follow the steps described below.
• Go
to your GitHub Developer settings and register a new OAuth app. GitHub will
open a Register a new OAuth application page. Enter the required values for
your application:
• Application
name: a name you would like to give to your OAuth application, such as Composer
• Homepage
URL: the full URL to your application homepage, such as http://microsoft.com
• Authorization
callback URL: the callback URL of your application, such as https://token.botframework.com/.auth/web/redirect.
Read about Authorizing OAuth Apps in the GitHub developer docs.
• Select
Register application. Then you will see the Client ID, Client Secret values
generated in the application webpage as shown below.
• OAuth
app credentials
• Save
the Client ID and Client Secret values.
• Go
back to Azure and paste the values you saved in the New Connection Settings.
These values configure the connection between your Azure resource and GitHub.
• Optionally,
enter user, repo, admin in Scopes. This field specifies the permission you want
to grant to the bot.
• Select
Save.
• You
can test the connection. In the right pane, select the connection you created,
GitHubLogin in the example.
• Select
Test Connection.
• Test
OAuth setting in Azure
• If
the test succeeds, you get the connection token back.
• Now,
with the Name , Client ID, Client Secret, and Scopes of your new OAuth
connection setting in Azure, you are ready to configure your bot.
Configure OAuth connection settings in Composer
• In
the Composer menu, select Project Settings.
• In
the right pane, select Development Resources tab.
• At
the bottom of the window, in the Microsoft App ID section, in the fields of
Microsoft App Id and Microsoft App Password, enter the app ID and app password
values from your Azure Bot registration.
• In
the left menu, select Design and add the OAuth login action to your dialog.
• Select
OAuth login from the Access external resources menu.
• OAuth menu
• The
Connection Name in the properties pane must be set to the same value you used
in Azure for the Name of the connection setting.
• Configure
at least the Text and Title values, which configure the message that will be
displayed alongside the log-in button, and the Property field, which will bind
the results of the OAuth action to a variable in your bot's memory.
• OAuth
sign-in properties
• This
will open a New Connection Settings, where you can configure the OAuth
connection. The options will differ depending on the service you are
authenticating with. Pictured below is the settings pane for configuring a
login to GitHub:
Use
the OAuth token in your bot
• When
you launch the bot in the Emulator and trigger the appropriate dialog, the bot
will present a log-in card. Selecting the log-in button in the card will launch
the OAuth process in a new window.
• OAuth
card in emulator
• You'll
be asked to log in to whatever external resource you've specified. Once
complete, the window will close automatically, and your bot will continue with
the dialog.
• The
results of the OAuth action will now be stored into the property you specified.
To reference the user's OAuth token, use .token. For example, if the OAuth
prompt is bound to turn.oauth, the token will be turn.oauth.token.
• To
use this to access the protected resources, pass the token into any API calls
you make with the HTTP Request action. You can refer to the token value in URL,
body, or headers of the HTTP request using the normal LG syntax, for example:
${turn.oauth.token}.
Best
Practices from this issue Discussion by Bot Framework Composer Product team:
https://github.com/microsoft/BotFramework-Composer/issues/5611#issuecomment-767775387
The
best practice we recommend for using the OAuth Login is to always
just call it immediately before you need access to the token. You should
save your token to a temporary variable like turn.token . You shouldn't ever
save it to user.token as that's not secure and the token will expire (maybe
that's what you're trying to do in the true flow... refresh it.)
If
you call the OAuth Login before each use it will automatically refresh the
access token so you never have to worry about tokens expiring.
The
logic of oauth prompt is like this: 1) retrieve token from service 2) if
failed, prompt. When in step 1, the service help you refresh token and always
return a useful token if user log in. There is nothing special to set for OAuth
prompt (the only thing you need to notice is don't enable the alwaysPrompt
flag). So that means, if a user is log in, the OAuth Prompt won't prompt, if
user is not log in, the OAuth prompt will prompt. It does not prompt everytime.
So be free to add many OAuth prompts in your flow.
The
oauth prompt will help you refresh token.
Note: please do not store the token by yourself, when you want to use token, get it from oauth prompt. Then it will help you manage your token