Add user authentication

APPLIES TO: Composer v1.x and v2.x

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.

Note

It's not necessary to deploy your bot to Azure for the authentication to work.

Prerequisites

• Microsoft Azure subscription.
• A basic bot built using Composer.
• Install ngrok.
• A service provider your bot is authenticating with such as GitHub.
• Basic knowledge of user authentication within a conversation.

Composer v2.x

Create an Azure Bot resource

If you already have an Azure Bot resource, you can skip to the Configure OAuth connection settings in Azure step. Otherwise, follow the steps described in Create an Azure Bot resource.

Make sure to copy and save the Azure Bot resource app ID and password. You'll need these values to Configure OAuth connection settings in Composer step.

Composer v1.x

Create the Azure Bot Service registration

If you've already got an Azure Bot Service channel registration, you can skip to the configure the oauth connection settings in Azure step.

If you don't have an Azure Bot Service channel registration, 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 these values to Configure OAuth connection settings in Composer step.

Configure OAuth connection settings in Azure

Composer v2.x

The following steps show how to configure OAuth connection settings to allow a bot to access an external service, GitHub in the example.

1. In the Azure portal, go to the Azure Bot resource.

2. In the left pane, in the Settings section, select Configuration.

3. In the right pane, select Add OAuth Connection Settings.

   

4. In the New Connection Settings, enter the required information to configure the OAuth connection. 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'll need to enter this value in Composer exactly as it's displayed in this setting.

5. 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.

   1. 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.

   2. Select Register application. You'll see the Client ID, Client Secret values generated in the application webpage as shown below.

      

   3. Save the Client ID and Client Secret values.

6. 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.

7. Optionally, enter user, repo, admin in Scopes. This field specifies the permission you want to grant to the bot.

8. Select Save.

9. You can test the connection. In the right pane, select the connection you created, GitHubLogin in the example.

10. Select Test Connection.

    

    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're ready to configure your bot.

Composer v1.x

1. From the bot channel registration inside Azure, select the Settings tab on the left. At the bottom of the resulting pane, you'll see a section titled OAuth Connection Settings. Select Add Setting.

   

   This will open a New Connection Settings, where you can configure the OAuth connection. The options will differ depending on the service you're authenticating with. Pictured below is the settings pane for configuring a log in to GitHub:

   

   Note the Name of your connection. You'll need to enter this value in Composer exactly as it's displayed in this setting.

2. Enter the values of Client ID, Client Secret, and optionally Scopes depending on the service you're authenticating with. In this example of GitHub, follow the steps to get these values:

   1. Go to GitHub developer's setting webpage and click New OAuth App on the upper right corner. This will redirect you to the GitHub OAuth App registration website where you fill in the values as instructed in the following:

      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 more here.

   2. Select Register application. You'll see the Client ID, Client Secret values generated in the application webpage as the following:

      

   3. Copy the Client ID and Client Secret values and paste them to your Azure's Service Provider Connection Setting. 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 caller. Save this setting.

   Now, with the Name , Client ID, Client Secret, and Scopes of your new OAuth connection setting in Azure, you're ready to configure your bot.

Configure OAuth connection settings in Composer

Composer v2.x

1. In the Composer menu, select Project Settings.

2. In the right pane, select Development Resources tab.

3. 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.

   

4. In the left menu, select Design and add the OAuth login action to your dialog.

   1. Select OAuth login from the Access external resources menu.

      

   2. 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.

   3. 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.

      Tip

      It's best practice to not keep the token for longer than is required. Use the turn memory scope.

      

   This will open a New Connection Settings, where you can configure the OAuth connection. The options will differ depending on the service you're authenticating with. Pictured below is the settings pane for configuring a login to GitHub:

Composer v1.x

1. Select Project Settings in the Composer menu. In the fields of Microsoft App Id and Microsoft App Password, enter the app ID and app password values from your Azure Bot Service registration.

   

2. On the Design page, add the OAuth login action to your dialog.

   1. Select OAuth login from the Access external resources menu.

      

   2. 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.

   3. You'll also need to configure at least the Text and Title values, which configure the message that will be displayed alongside the log-in button, and possibly 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!

Use the OAuth token in your bot

Composer v2.x

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.

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 <scope-name>.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}.

Composer v1.x

When you launch the bot in the Emulator and trigger the appropriate dialog, the bot will present a log-in card. Clicking the button in the card will launch the OAuth process in a new window.

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 <scope-name>.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}.

Next steps

• Learn how to send an HTTP request and use OAuth.