Adding end user authentication to your data connections

The Health bot service is a highly configurable and extensible bot building platform. One of the core capabilities is the ability to integrate authenticated third party services into your scenarios flows.

To build such integrations we provide an end user authentication layer on top of the regular data connection object which allows you to make HTTPS calls to third-party API providers or your own API endpoints.

Before an authenticated connection accesses personal resources, end users are prompted to login via an OAuth 2.0 flow in the chat thread. This ensures that personal resources are accessed only by authenticated users. In this tutorial we will show you how to access an end users drop-box account via an authenticated data connection.

First you need to register an application in the DropBox developer portal. Create a new DropBox app for your Bot Instance to use. Select the relevant Tier of DropBox and appropriate level of access. For this tutorial, we chose the Free DropBox tier and Full access to the storage account.

After DropBox authenticates your users they are redirected them to the Health Bot service with an access token. The Health Bot redirect URL must be whitelisted to ensure that malicious applications can’t mimic your DropBox application.

Create your app, and white list the redirect URL in the DropBox application settings. If you are running a US instance of Health Bot whitelist: https://bot-api-us.healthbot.microsoft.com/bot/redirect/oauth2

If you are running an EU instance of Health Bot whitelist: https://bot-api-eu.healthbot.microsoft.com/bot/redirect/oauth2

To integrate with the DropBox authentication service you also need the DropBox client ID and client secret for your application (DropBox uses different terminology, they call these credentials the App key and App secret).

We will now add a new authentication provider login to Health Bot Management Portal. Navigate to Integrations > Authentication and add a new provider. You will be prompted for the details of your Key and Secret from the DropBox application settings.

• Name: Add an internal name for the connection
• Description: Add an internal description for recognizing this connection
• Client ID: Add the client ID issued by the OAuth provider when you registered your application (in DropBox this is called the App Key).
• Client Secret: Add the client secret issued by the OAuth provider when you registered your application (in DropBox this is called the App secret).
• Authorization URL: This is the URL the bot will redirect your end Users to for Authentication. Each OAuth provider has their own Authorization URL. For DropBox use https://www.dropbox.com/oauth2/authorize
• Access Token URL: This URL is used to refresh the bots access to the end users account. Each OAuth provider has their own Access Token URL. For DropBox use https://api.dropboxapi.com/oauth2/token
• Scope: The scope is used to restrict the level of access to the application. In DropBox the scope is selected the DropBox UI during the app creation and does not need to be passed here (you can leave this field blank).

You can now use this authentication provider. To see how end users are authenticated we can create a simple test scenario. Create a data connection to one of the DropBox APIs and add the authentication layer.

In this example we have made call to DropBox storage API which shows how much storage the user has left in their DropBox account.

You should also add a statement object to the canvas which will show the response from the API call. Your scenario should look like this:

You can now run the scenario. You will see that the end user is prompted to login to their DropBox account before retrieving their account storage information.