Sample: 24.bot-authentication-msgraph

samples/24.bot-authentication-msgraph/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

samples/24.bot-authentication-msgraph/README.md

@@ -0,0 +1,118 @@
+# Authentication Bot Utilizing MS Graph
+
+Bot Framework v4 bot authentication using Microsoft Graph sample
+
+This bot has been created using [Bot Framework](https://dev.botframework.com), is shows how to use the bot authentication capabilities of Azure Bot Service. In this sample we are assuming the OAuth 2 provider is Azure Active Directory v2 (AADv2) and are utilizing the Microsoft Graph API to retrieve data about the user. [Check here](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-authentication?view=azure-bot-service-4.0&tabs=csharp) for information about getting an AADv2
+application setup for use in Azure Bot Service. The [scopes](https://developer.microsoft.com/en-us/graph/docs/concepts/permissions_reference) used in this sample are the following:
+
+- `openid`
+- `profile`
+- `User.Read`
+
+NOTE: Microsoft Teams currently differs slightly in the way auth is integrated with the bot. Refer to sample 46.teams-auth.
+
+## Prerequisites
+
+- Java 1.8+
+- Install [Maven](https://maven.apache.org/)
+- An account on [Azure](https://azure.microsoft.com) if you want to deploy to Azure.
+
+## To try this sample locally
+- From the root of this project folder:
+  - Build the sample using `mvn package`
+  - Run it by using `java -jar .\target\bot-authentication-msgraph-sample.jar`
+
+- Test the bot using Bot Framework Emulator
+
+  [Bot Framework Emulator](https://github.com/microsoft/botframework-emulator) is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel.
+
+  - Install the Bot Framework Emulator version 4.3.0 or greater from [here](https://github.com/Microsoft/BotFramework-Emulator/releases)
+
+  - Connect to the bot using Bot Framework Emulator
+
+    - Launch Bot Framework Emulator
+    - File -> Open Bot
+    - Enter a Bot URL of `http://localhost:3978/api/messages`
+
+## Deploy the bot to Azure
+
+As described on [Deploy your bot](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-deploy-az-cli), you will perform the first 4 steps to setup the Azure app, then deploy the code using the azure-webapp Maven plugin.
+
+### 1. Login to Azure
+From a command (or PowerShell) prompt in the root of the bot folder, execute:  
+`az login`
+
+### 2. Set the subscription
+`az account set --subscription "<azure-subscription>"`
+
+If you aren't sure which subscription to use for deploying the bot, you can view the list of subscriptions for your account by using `az account list` command. 
+
+### 3. Create an App registration
+`az ad app create --display-name "<botname>" --password "<appsecret>" --available-to-other-tenants`
+
+Replace `<botname>` and `<appsecret>` with your own values.
+
+`<botname>` is the unique name of your bot.  
+`<appsecret>` is a minimum 16 character password for your bot. 
+
+Record the `appid` from the returned JSON
+
+### 4. Create the Azure resources
+Replace the values for `<appid>`, `<appsecret>`, `<botname>`, and `<groupname>` in the following commands:
+
+#### To a new Resource Group
+`az deployment sub create --name "authenticationBotDeploy" --location "westus" --template-file ".\deploymentTemplates\template-with-new-rg.json" --parameters appId="<appid>" appSecret="<appsecret>" botId="<botname>" botSku=S1 newAppServicePlanName="authenticationGraphBotPlan" newWebAppName="authenticationGraphBot" groupLocation="westus" newAppServicePlanLocation="westus"` 
+
+#### To an existing Resource Group
+`az deployment group create --resource-group "<groupname>" --template-file ".\deploymentTemplates\template-with-preexisting-rg.json" --parameters appId="<appid>" appSecret="<appsecret>" botId="<botname>" newWebAppName="authenticationGraphBot" newAppServicePlanName="authenticationGraphBotPlan" appServicePlanLocation="westus" --name "authenticationGraphBot"`
+
+### 5. Update app id and password
+In src/main/resources/application.properties update 
+  - `MicrosoftAppPassword` with the botsecret value
+  - `MicrosoftAppId` with the appid from the first step
+
+### 6. Deploy the code
+- Execute `mvn clean package` 
+- Execute `mvn azure-webapp:deploy -Dgroupname="<groupname>" -Dbotname="<botname>"`
+
+If the deployment is successful, you will be able to test it via "Test in Web Chat" from the Azure Portal using the "Bot Channel Registration" for the bot.
+
+After the bot is deployed, you only need to execute #6 if you make changes to the bot.
+
+## Interacting with the bot
+
+This sample uses the bot authentication capabilities of Azure Bot Service, providing features to make it easier to develop a bot that
+authenticates users to various identity providers such as Azure AD (Azure Active Directory), GitHub, Uber, and so on. These updates also
+take steps towards an improved user experience by eliminating the magic code verification for some clients and channels.
+It is important to note that the user's token does not need to be stored in the bot. When the bot needs to use or verify the user has a valid token at any point the OAuth prompt may be sent. If the token is not valid they will be prompted to login.
+
+## Microsoft Graph API
+
+This sample demonstrates using Azure Active Directory v2 as the OAuth2 provider and utilizes the Microsoft Graph API.
+Microsoft Graph is a Microsoft developer platform that connects multiple services and devices. Initially released in 2015,
+the Microsoft Graph builds on Office 365 APIs and allows developers to integrate their services with Microsoft products including Windows, Office 365, and Azure.
+
+## GraphError 404: ResourceNotFound, Resource could not be discovered
+
+This error may confusingly present itself if either of the following are true:
+
+- You're using an email ending in `@microsoft.com`, and/or
+- Your OAuth AAD tenant is `microsoft.onmicrosoft.com`.
+
+## Further reading
+
+- [Bot Framework Documentation](https://docs.botframework.com)
+- [Bot Basics](https://docs.microsoft.com/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0)
+- [Dialogs](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-dialog?view=azure-bot-service-4.0)
+- [Gathering Input Using Prompts](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-prompts?view=azure-bot-service-4.0&tabs=csharp)
+- [Activity processing](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-activity-processing?view=azure-bot-service-4.0)
+- [Microsoft Graph API](https://developer.microsoft.com/en-us/graph)
+- [MS Graph Docs](https://developer.microsoft.com/en-us/graph/docs/concepts/overview) and [SDK](https://github.com/microsoftgraph/msgraph-sdk-dotnet)
+- [Azure Bot Service Introduction](https://docs.microsoft.com/azure/bot-service/bot-service-overview-introduction?view=azure-bot-service-4.0)
+- [Azure Bot Service Documentation](https://docs.microsoft.com/azure/bot-service/?view=azure-bot-service-4.0)
+- [Azure CLI](https://docs.microsoft.com/cli/azure/?view=azure-cli-latest)
+- [Azure Portal](https://portal.azure.com)
+- [Channels and Bot Connector Service](https://docs.microsoft.com/en-us/azure/bot-service/bot-concepts?view=azure-bot-service-4.0)
+- [Maven Plugin for Azure App Service](https://docs.microsoft.com/en-us/java/api/overview/azure/maven/azure-webapp-maven-plugin/readme?view=azure-java-stable)
+- [Spring Boot](https://spring.io/projects/spring-boot)
+- [Azure for Java cloud developers](https://docs.microsoft.com/en-us/azure/java/?view=azure-java-stable)