If your bot needs to access external resources using permissions granted by the end user, it will need to use the OAuth Login action within the Access external resources menu, along with a an OAuth configuration that lives in the Azure Bot Service Channels Registration. In this article, you will cover how to use basic OAuth to authenticate your bot with your GitHub account. (It is not necessary to deploy your bot to Azure for this to work.)
- Microsoft Azure subscription
- a basic bot you build using Composer
- a service provider your bot is authenticating with such as GitHub
- basic knowledge of Bot Channels Registration and how to create one
- basic knowledge of user authentication within a conversation
If you've already got an Azure Bot Service channel registration, you can skip to the next step
If you don't, follow these instructions to create a registration in the Azure portal.
Make sure you note the app ID and app password that is generated during this process. You'll need it in this step.
From the bot channel registration inside Azure, click the "Settings" tab on the left. At the bottom of the resulting pane, you'll see a section titled "OAuth Connection Settings". Click "Add Setting".
This will open a new settings pane, where you can configure the OAuth connection. Depending on the service you are authenticating with, the options will differ. Pictured below is the settings pane for configuring a login to Github:
Note the Name of your connection - you will need to enter this value in Composer exactly as it is displayed in this setting.
You should fill in the values of Client ID, Client Secret, and optionally Scopes depending on the service you are authenticating with. In this example of GitHub, follow the steps to get these values:
-
Go to GitHub developer's setting webpage and click
New OAuth Appon the right upper corner. This will redirect you to the GitHub OAuth App registration website. Fill in the values as instructed in the following:Application name: a name you would like to give to your OAuth application, e.g.ComposerHomepage URL: the full URL to your application homepage, e.g.http://microsoft.comAuthorization callback URL: the callback URL of your application, e.g.https://token.botframework.com/.auth/web/redirect. read more here. -
Click
Register application. Then you will see theClient ID,Client Secretvalues generated in the application webpage as the following:
- Copy the
Client IDandClient Secretvalues and paste them to your Azure's Service Provider Connection Setting. These values configure the connection between your Azure resource and GitHub. Optionally, you can filluser, repo, admininScopes. This field specifies the permission you want to grant to the caller. Save this setting.
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.
First, click on the settings tab in Composer, and add update the Dialog settings with the app ID and app password values from Azure. You'll put these into the MicrosoftAppId and MicrosoftAppPassword keys in the settings, as shown below:
Then, add the OAuth Login action to your dialog. In the properties panel view of that step, set the Connection Name to the name of your connection setting in Azure. This value must match exactly.
You will also need to configure at least the Text and Title values, which configure the message that will be displayed alongside the login button, as well as the property field, which will bind the results of the OAuth action to a variable in your bot's memory.
Your bot is now configured to use this OAuth connection!
When you launch the bot in the Emulator and trigger the appropriate dialog, the bot will present a login card. Clicking the button in the card will launch the OAuth process in a new window.
You'll be asked to login 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 <scope.name>.token -- so for example, if the OAuth prompt is bound to dialog.oauth, the token will be dialog.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: {dialog.oauth.token}.
- Learn how to send an HTTP request and use OAuth.