Authentication, Control library (#104)

* Norm control library (#101)

* Add control library topic

* toc

* link

* trdt

* Added second part

* proofreading

* edits

* links

* Edits (#98)

* added links to React and Redux
* changed heading capitalization style to match rest of docs
* fixed commas, spaces, capitalization bugs, monospace formatting

* Made changes for PR #100

* Norm authentication rework (#103)

* Added structure for new authentication content

* Added content to top level

* Rough draft of tab authentication topic with new screenshots

* Fixed format issue

* Formatting test

* Formatting

* Added content for SSO

* Structural edits

* list test

* test

* test

* test

* Test

* test

* test

* test

* test

* indent code

* test

* tst

* test

* Updated bot auth

* Added new samples for bot auth

* Corrected code for auth

* Expanded code for bot auth

* Minor edits

* Removed work in progress

* More term changes and rewrite

* More review comments

* Review comments

* TOC

* Added support for other providers

* Removed app registration

* minor edits

* Pre publication changes

* Extensive edits, added links, native image

* Added missing space

* Made title match metadata

* Misc changes (#97)

* Misc changes

1. Missing comma
2. Fixed 404 dead link to SDK
3. Misc editing
4. Attempted to clarify murky mobile auth story
5. Fixed sample code labels

* Added Visio sequence diagram source

Bot and tab auth sequence diagrams

* Added folder for authentication images

* Delete placeholder.md

* Added copy of PNG instead of linking to asolis repo

* Extensive edits, updated bitmap, added links

* Updated flow diagram

* toc changes

* fixed link

* Extensive edits (#99)

Technical accuracy, additional links, reordered last two sections, minor edits.

* Restructured auth topics

* added links to auth provider

* TOC

* Changes from readthrough

* edits

* edits

* edits

* formatting

* edits

* standardize

* Billbl auth final edits (#102)

* Minor edits and clarifications

* Enlarged to fit available space

* Enlarged to fit available space

* replaced by lowercase filename version

* Mistakenly posted to wrong directory

* Minor edits

* Tech review and clarification

Fixed some of my own bugs and clarified the distinction between state validation and <verification code> validation.

* Fixed grammar bug

* Grammar change to bot auth diagram

* Technical review changes

* Extensive revisions to reflect bot auth sample

Previous version referenced Josh's sample; Adrian's is quite different.

* Added clarification - no bot support

* Changed to "identity provider" nomenclature

* Changed to "identity provider" nomenclature

* Minor edits and nomenclature change

* authentication -> identity

* Fixed broken links

msteams-platform/TOC.yml

@@ -3,11 +3,14 @@
   universal_ref_toc: /javascript/api/msteams-client-docs-ref-typescript/toc.json
 - name: Get started
   href: ./get-started/get-started
-  items:
+  items: 
   - name:  Prepare your Office 365 tenant
     href: ./get-started/get-started-tenant
   - name: Use Teams App Studio
     href: ./get-started/get-started-app-studio
+    items:
+    - name: App Studio Controls
+      href: ./get-started/app-studio-component-library
   - name: Get started with Node.js
     href: ./get-started/get-started-nodejs
   - name: Get started with C#/.NET
@@ -57,7 +60,20 @@
     - name: Test a bot
       href: ./concepts/bots/bots-test
   - name: Authentication
-    href: ./concepts/authentication
+    href: ./concepts/authentication/authentication
+    items:
+    - name: Authentication flow for tabs
+      href: ./concepts/authentication/auth-flow-tab
+    - name: Authentication flow for bots
+      href: ./concepts/authentication/auth-flow-bot
+    - name: AAD tab authentication
+      href: ./concepts/authentication/auth-tab-AAD
+    - name: AAD bot authentication
+      href: ./concepts/authentication/auth-bot-AAD
+    - name: Silent authentication and SSO
+      href: ./concepts/authentication/auth-silent-AAD
+    - name: Configuring identity providers
+      href: ./concepts/authentication/auth-configure
   - name: Activity Feed
     href: ./concepts/activity-feed
   - name: Connectors

msteams-platform/concepts/apps/apps-upload.md

@@ -26,16 +26,16 @@ With your package created, you can now upload it into a team. Once uploaded it w
 > [!NOTE]
 > For uploading to work, your tenant admin must first [enable uploading of apps](/microsoftteams/admin-settings).
 
-1. Create a new team for testing, if necessary. Click **Create and join team** at the bottom of the left-hand panel.
+1. Create a new team for testing, if necessary. Click *Create and join team* at the bottom of the left-hand panel.
 
-2. In the target team, choose **More options** (**⋯**) and choose **Manage team**.
+2. In the target team, choose *More options* (**⋯**) and choose *Manage team*.
 
    ![View team](~/assets/images/ManageTeam.png)
 
    > [!NOTE]
    > You must be the team owner, or the owner must allow users to add the appropriate app types for this functionality to appear.
 
-3. Select the Apps tab, and then choose **Upload a custom app** on the lower right.
+3. Select the Apps tab, and then choose *Upload a custom app* on the lower right.
 
    ![Upload entry point](~/assets/images/uploadACustomApp.png)
 
@@ -51,13 +51,13 @@ If your app does not load, the most common reason is an error in the manifest, p
 
 If the app contains tabs, users can pin them to any channel on the team using the standard tab gallery flow:
 
-1. Go to a channel in the team. Choose **+** (**Add a tab**) to the right of the existing tabs.
+1. Go to a channel in the team. Choose *+* (*Add a tab*) to the right of the existing tabs.
 
 2. Select your tab from the gallery that appears.
 
 3. Accept the consent prompt.
 
-4. Configure your tab via its [configuration page](~/concepts/tabs/tabs-configuration) and choose **Save**.
+4. Configure your tab via its [configuration page](~/concepts/tabs/tabs-configuration) and choose *Save*.
 
   ![The Add a tab dialog box, featuring a gallery of available tabs](~/assets/images/tab_gallery.png)
 
@@ -73,25 +73,25 @@ To test direct chats with your bot, you can either access it via the App home, @
 
 With the app loaded in the team, users can set up a Connector on any channel in the team using the standard Connectors gallery flow:
 
-1. Go to a channel in the team. Choose **More options** (**⋯**) and choose **Connectors**.
+1. Go to a channel in the team. Choose *More options* (*⋯*) and choose *Connectors*.
 
 2. Select your Connector from the **Uploaded** section at the bottom.
 
-3. Configure your Connector via its [configuration page](~/concepts/connectors) and choose **Save**.
+3. Configure your Connector via its [configuration page](~/concepts/connectors) and choose *Save*.
 
   ![The Add a tab dialog box, featuring a gallery of available tabs.](~/assets/images/connector_gallery.png)
 
 ## Accessing your uploaded messaging extension
 
-An uploaded app with a messaging extension automatically appears in the **More options** (**⋯**) menu in the compose box.
+An uploaded app with a messaging extension automatically appears in the *More options* (*⋯*) menu in the compose box.
 
 ![Messaging extensions](~/assets/images/compose-extensions/cesampleapp.png)
 
 ## Removing or updating your app
 
 If you want to remove your app, select the trash-can icon next to the app name in the View Teams bots list.
 
-If you change manifest information, you must first remove the app and then add the updated package (per [Load your package into a team](#load-your-package-into-a-team)). Note that, in general, code changes on your service do not require you to re-upload your manifest, unless those changes require manifest updates (such as changes to the URL or the Microsoft app ID for its bot). 
+If you change manifest information, you must first remove the app and then add the updated package (per [Load your package into a team](#load-your-package-into-a-team)). Note that, in general, code changes on your service do not require you to re-upload your manifest, unless those changes require manifest updates (such as changes to the URL or the Microsoft app ID for its bot).
 
 > [!NOTE]
 > There is currently no way to completely remove a bot from 1:1 context.

msteams-platform/concepts/authentication/auth-bot-AAD.md

@@ -0,0 +1,119 @@
+---
+title: Authentication for bots using Azure Active Directory
+description: Describes AAD authentication in Teams and how to use it in your bots
+keywords: teams authentication bots AAD
+ms.date: 03/01/2018
+---
+# Authenticate a user in a Microsoft Teams bot
+
+There are many services that you may wish to consume inside your Teams app, and most of those services require authentication and authorization to get access to the service. Services include Facebook, Twitter, and of course Teams. Users of Teams have user profile information stored in Azure Active Directory (AAD) using Microsoft Graph. This article will focus on authentication using AAD to get access to this information.
+
+OAuth is an open standard for authentication used by AAD and many other service providers. Understanding OAuth is a prerequisite for working with authentication in Teams and AAD. The examples below use the OAuth2 Implicit Grant flow with the goal of eventually reading the user's profile information from AAD and Graph.
+
+The authentication flow described in this article is very similar to that of tabs except that tabs can use web based authentication flow, and bots require authentication to be driven from code. The concepts in this article will also be useful when implementing authentication from the mobile platform.
+
+For a general overview of authentication flow for bots see the topic [Authentication flow in bots](~/concepts/authentication/auth-flow-bot).
+
+## Configuring identity providers
+
+See the topic [Configure identity providers](~/concepts/authentication/auth-configure) for detailed steps on configuring OAuth 2.0 callback redirect URL(s) when using Azure Active Directory as an identity provider.
+
+## Initiate authentication flow
+
+Authentication flow should be triggered by a user action. You should not open the authentication pop-up automatically because this is likely to trigger the browser's pop-up blocker as well as confuse the user.
+
+## Add UI to start authentication
+
+Add UI to the bot to enable the user to sign in when needed. Here it is done from a Thumbnail card, in TypeScript:
+
+```TypeScript
+// Show prompt of options
+protected async promptForAction(session: builder.Session): Promise<void> {
+    let msg = new builder.Message(session)
+        .addAttachment(new builder.ThumbnailCard(session)
+            .title(this.providerDisplayName)
+            .buttons([
+                 builder.CardAction.messageBack(session, "{}", "Sign in")
+                     .text("SignIn")
+                     .displayText("Sign in"),
+                  builder.CardAction.messageBack(session, "{}", "Show profile")
+                     .text("ShowProfile")
+                     .displayText("Show profile"),
+                  builder.CardAction.messageBack(session, "{}", "Sign out")
+                     .text("SignOut")
+                     .displayText("Sign out"),
+            ]));
+    session.send(msg);
+}
+```
+
+Three buttons have been added to the Hero Card: Sign in, Show Profile, and Sign out.
+
+## Sign the user in
+
+Because of the validation that must be performed for security reasons and the support for the mobile versions of Teams, the code isn't shown here, but [here's an example of the code that kicks off the process when the user presses the Sign in button.](https://github.com/OfficeDev/microsoft-teams-sample-auth-node/blob/e84020562d7c8b83f4a357a4a4d91298c5d2989d/src/dialogs/BaseIdentityDialog.ts#L154-L195).
+
+The validation and mobile support are explained in the topic [Authentication flow in bots](~/concepts/authentication/auth-flow-bot).
+
+Be sure to add the domain of your authentication redirect URL to the [`validDomains`](~/resources/schema/manifest-schema#validdomains) section of the manifest. If you don't, the login popup will not appear.
+
+## Showing user profile information
+
+Although getting an access token is difficult because of all the transitions back and forth across different websites and the security issues that must be addressed, once you have a token, obtaining information from Azure Active Directory is straightforward. The bot makes a call to the `me` Graph endpoint with the access token. Graph responds with the user information for the person who logged in. Information from the response is used to construct a bot card and sent.
+
+```TypeScript
+// Show user profile
+protected async showUserProfile(session: builder.Session): Promise<void> {
+    let azureADApi = this.authProvider as AzureADv1Provider;
+    let userToken = this.getUserToken(session);
+
+    if (userToken) {
+        let profile = await azureADApi.getProfileAsync(userToken.accessToken);
+        let profileCard = new builder.ThumbnailCard()
+            .title(profile.displayName)
+            .subtitle(profile.mail)
+            .text(`${profile.jobTitle}<br/> ${profile.officeLocation}`);
+        session.send(new builder.Message().addAttachment(profileCard));
+    } else {
+        session.send("Please sign in to AzureAD so I can access your profile.");
+    }
+
+    await this.promptForAction(session);
+}
+
+// Helper function to make the Graph API call
+public async getProfileAsync(accessToken: string): Promise<any> {
+    let options = {
+        url: "https://graph.microsoft.com/v1.0/me",
+        json: true,
+        headers: {
+            "Authorization": `Bearer ${accessToken}`,
+        },
+    };
+    return await request.get(options);
+}
+```
+
+If the user is not signed in they are prompted to do so.
+
+## Sign the user out
+
+```TypeScript
+// Handle user logout request
+private async handleLogout(session: builder.Session): Promise<void> {
+    if (!utils.getUserToken(session, this.providerName)) {
+        session.send(`You're already signed out of ${this.providerDisplayName}.`);
+    } else {
+        utils.setUserToken(session, this.providerName, null);
+        session.send(`You're now signed out of ${this.providerDisplayName}.`);
+    }
+
+    await this.promptForAction(session);
+}
+```
+
+## Other samples
+
+For sample code showing the bot authentication process see:
+
+* [Microsoft Teams bot authentication sample](https://github.com/OfficeDev/microsoft-teams-sample-auth-node)

msteams-platform/concepts/authentication/auth-configure.md

@@ -0,0 +1,39 @@
+---
+title: Configuring OAuth 2.0 identity providers
+description: Describes how to configure identity providers with a focus on AAD
+keywords: teams authentication AAD oauth identity provider
+ms.date: 03/01/2018
+---
+# Configuring identity providers
+
+## Configuring an application to use Azure Active Directory as an identity provider
+
+Identity providers supporting OAuth 2.0 will not authenticate requests from unknown applications; applications must be registered ahead of time. To do this with AAD, follow these steps:
+
+1. Open the [Application Registration Portal](https://apps.dev.microsoft.com/), click on *Add an app* and follow the steps to register your app. If your app has already been registered (for example if you have previously registered a bot in your app) locate your app.
+
+2. Select your app to view its properties. Find the *Platforms* section for the app and select *Add Platform*.
+
+    ![View team](~/assets/images/authentication/AppRegistration.png)
+
+3. From the *Add Platform* dialog select *Web*.
+
+    ![View team](~/assets/images/authentication/AddPlatform.png)
+
+4. The *Add Platform* section of the app properties page will now look something like this:
+
+    ![View team](~/assets/images/authentication/Platforms.png)
+
+    Add the OAuth 2.0 redirect and logout URLs in the Web section of Platforms. For the TypeScript/Node.js and C# sample apps on GitHub, the redirect URLs will be similar to this:
+
+    Redirect URLs: https://\<hostname\>/bot-auth/simple-start
+
+    No logout URL is required.
+
+    Replace `<hostname>` with your actual host. This might be a dedicated hosting site such as Azure, Glitch, or an ngrok tunnel to localhost on your development machine such as `abcd1234.ngrok.io`. You may not have this information yet if you have not completed or hosted your app (or the sample app mentioned above), but you can always return to this page when that information is known.
+
+## Other authentication providers
+
+* **LinkedIn** Follow the instructions in [Configuring your LinkedIn application](https://developer.linkedin.com/docs/oauth2)
+
+* **Google** Obtain OAuth2 client credentials from the [Google API Console](https://console.developers.google.com/)