Overview

This post describes how to add OAuth2 authentication to a bot so it can perform certain GitHub operations on behalf of the user. The article assumes that you already have a bot deployed in Azure. GitHub is used as the identity provider to authenticate the user and to generate a bearer token which the bot uses to perform GitHub operations on behalf of the user. In its simplest form, the bot should allow the user to perform basic GitHub commands like listing and accessing repositories. You can download an example of this kind of bot from GitHub here.

Create a GitHub OAuth Application

1. In your browser, log in to your GitHub account.
2. Navigate to GitHub Apps.
3. In the left pane, click the OAuth Apps link.
4. Click the New OAuth App button.
5. Confirm your password.
6. Enter the following information:
   1. Application name. This is the name of the application.
   2. HomePage URL. https://dev.botframework.com.
   3. Application description. The intent of the application.
   4. Authorization callback URL. https://token.botframework.com/web/redirect.
7. Click the Register application button.
8. Upload a logo.
9. Click the Update application button.
10. Copy and save the Client Id and the Client Secret. You will need them when setting the bot Oauth connection string in Azure.

Create an authentication connection

The following are the steps you must perform to create an authentication connection.

1. In your browser, navigate to the Azure portal.
2. Select your bot registration resource.
3. In the left pane, click Settings.
4. In the right pane, scroll to the bottom of page.
5. In the OAuth Connection Settings section, click the Add Settings button.
6. In the New Connection Setting page, enter the following information:
   
   1. Name. The name of the connection.
   2. Service Provider. From the drop-down list, select GitHub.
   3. Client Id. The GitHub OAuth application Client Id.
   4. Client Secret . The GitHub OAuth application Client Secret.
   5. Scopes. A comma-separated list of GitHub commands, for example: read:user, user:email, repo.
      
      
7. Click the Save button.

Test the Connection

1. Click on the name of the connection you just created.
2. In the displayed connection page, click the Test Connection button in the upper right.
3. If you are not signed in GitHub, you will be asked to do so.
   
4. Once signed in, you should be getting your authentication bearer token.
   

Test the bot

1. In your browser, navigate to the Azure portal.
2. Select your bot registration resource.
3. In the left pane, click Test in Web Chat.
4. In the example shown here, you receive a welcome message.
5. Enter any message in the text box. You will be asked to sign in.
6. Click the Sign In button.
   
7. Once signed in successfully the bot displays a set of GitHub commands you can use, at the least in the example referred to in this article.
   
8. If you click the Repositories button, you get the list of the GitHub repository you can access. And you can get to those repositories in GitHub.

References

• Good OAuth overview easier to follow than the formal specification
• OAuth specification
• OAuth in a Nutshell