Merge pull request #98409 from KingdomOfEnds/tsi-refresh

MSAL and ADAL note

Author: ktoliver

articles/time-series-insights/time-series-insights-authentication-and-authorization.md

@@ -10,14 +10,19 @@ ms.reviewer: v-mamcge, jasonh, kfile
 ms.devlang: csharp
 ms.workload: big-data
 ms.topic: conceptual
-ms.date: 11/14/2019
+ms.date: 12/09/2019
 ms.custom: seodec18
 ---
 
 # Authentication and authorization for Azure Time Series Insights API
 
 This document describes how to register an app in Azure Active Directory using the new Azure Active Directory blade. Apps registered in Azure Active Directory enable users to authenticate to and be authorized to use the Azure Time Series Insight API associated with a Time Series Insights environment.
 
+> [!IMPORTANT]
+> Azure Time Series Insights supports both of the following authentication libraries:
+> * The more recent [Microsoft Authentication Library (MSAL)](https://docs.microsoft.com/azure/active-directory/develop/msal-overview)
+> * The [Azure Active Directory Authentication Library (ADAL)](https://docs.microsoft.com/azure/active-directory/develop/active-directory-authentication-libraries)
+
 ## Service principal
 
 The following sections describe how to configure an application to access the Time Series Insights API on behalf of an app. The application may then query or publish reference data in the Time Series Insights environment using its own application credentials through Azure Active Directory.
@@ -71,30 +76,19 @@ Per **step 3**, separating your application's and your user credentials allows y
 
 ### Client app initialization
 
-1. Use the **Application ID** and **Client Secret** (Application Key) from the Azure Active Directory app registration section to acquire the token on behalf of the application.
+* Developers may use the [Microsoft Authentication Library (MSAL)](https://docs.microsoft.com/azure/active-directory/develop/msal-overview) or [Azure Active Directory Authentication Library (ADAL)](https://docs.microsoft.com/azure/active-directory/develop/active-directory-authentication-libraries) to authenticate with Azure Time Series Insights.
 
-    In C#, the following code can acquire the token on behalf of the application. For a complete sample, see [Query data using C#](time-series-insights-query-data-csharp.md).
+* For example, to authenticate using ADAL:
 
-    ```csharp
-    // Enter your Active Directory tenant domain name
-    var tenant = "YOUR_AD_TENANT.onmicrosoft.com";
-    var authenticationContext = new AuthenticationContext(
-        $"https://login.microsoftonline.com/{tenant}",
-        TokenCache.DefaultShared);
+   1. Use the **Application ID** and **Client Secret** (Application Key) from the Azure Active Directory app registration section to acquire the token on behalf of the application.
 
-    AuthenticationResult token = await authenticationContext.AcquireTokenAsync(
-        // Set the resource URI to the Azure Time Series Insights API
-        resource: "https://api.timeseries.azure.com/",
-        clientCredential: new ClientCredential(
-            // Application ID of application registered in Azure Active Directory
-            clientId: "YOUR_APPLICATION_ID",
-            // Application key of the application that's registered in Azure Active Directory
-            clientSecret: "YOUR_CLIENT_APPLICATION_KEY"));
+   1. In C#, the following code can acquire the token on behalf of the application. For a complete sample, see [Query data using C#](time-series-insights-query-data-csharp.md).
 
-    string accessToken = token.AccessToken;
-    ```
+        [!code-csharp[csharpquery-example](~/samples-tsi/csharp-tsi-ga-sample/Program.cs?range=170-199)]
 
-1. The token can then be passed in the `Authorization` header when the application calls the Time Series Insights API.
+   1. The token can then be passed in the `Authorization` header when the application calls the Time Series Insights API.
+
+* Alternatively, developers may choose to authenticate using MSAL. Read about [migrating to MSAL](https://docs.microsoft.com/azure/active-directory/develop/msal-net-migration) to learn more. 
 
 ## Common headers and parameters
 
@@ -106,39 +100,57 @@ To perform authenticated queries against the [Time Series Insights REST APIs](ht
 
 > [!IMPORTANT]
 > The token must be issued exactly to the `https://api.timeseries.azure.com/` resource (also known as the "audience" of the token).
-> * Your [Postman](https://www.getpostman.com/) **AuthURL** with therefore conform to: `https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?resource=https://api.timeseries.azure.com/`
+> * Your [Postman](https://www.getpostman.com/) **AuthURL** will therefore be: `https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?resource=https://api.timeseries.azure.com/`
 
 > [!TIP]
 > See the hosted Azure Time Series Insights [client SDK sample visualization](https://tsiclientsample.azurewebsites.net/) to see how to authenticate with the Time Series Insights APIs programmatically using the [JavaScript Client SDK](https://github.com/microsoft/tsiclient/blob/master/docs/API.md) along with charts and graphs.
 
 ### HTTP headers
 
-Required request headers:
+Required request headers are described below.
 
-- `Authorization` for authentication and authorization, a valid OAuth 2.0 Bearer token must be passed in the Authorization header. The token must be issued exactly to the `https://api.timeseries.azure.com/` resource (also known as the "audience" of the token).
+| Required request header | Description |
+| --- | --- |
+| Authorization | To authenticate with Time Series Insights, a valid OAuth 2.0 Bearer token must be passed in the **Authorization** header. | 
 
-Optional request headers:
+> [!IMPORTANT]
+> * The token must be issued exactly to `https://api.timeseries.azure.com/` (which is known as the "audience" of the token).
+> * Note that `https://api.timeseries.azure.com/` is valid but `https://api.timeseries.azure.com` is not.
 
-- `Content-type` - only `application/json` is supported.
-- `x-ms-client-request-id` - a client request ID. Service records this value. Allows the service to trace operation across services.
-- `x-ms-client-session-id` - a client session ID. Service records this value. Allows the service to trace a group of related operations across services.
-- `x-ms-client-application-name` - name of the application that generated this request. Service records this value.
+Optional request headers are described below.
 
-Response headers:
+| Optional request header | Description |
+| --- | --- |
+| Content-type | only `application/json` is supported. |
+| x-ms-client-request-id | A client request ID. The service records this value. Allows the service to trace operation across services. |
+| x-ms-client-session-id | A client session ID. The service records this value. Allows the service to trace a group of related operations across services. |
+| x-ms-client-application-name | Name of the application that generated this request. The service records this value. |
 
-- `Content-type` - only `application/json` is supported.
-- `x-ms-request-id` - server-generated request ID. Can be used to contact Microsoft to investigate a request.
+Optional but recommended response headers are described below.
+
+| Response header | Description |
+| --- | --- |
+| Content-type | Only `application/json` is supported. |
+| x-ms-request-id | Server-generated request ID. Can be used to contact Microsoft to investigate a request. |
 
 ### HTTP parameters
 
-Required URL query string parameters:
+Required URL query string parameters depend on API version. 
+
+| Release | Possible API version values |
+| --- |  --- |
+| General Availability | `api-version=2016-12-12`|
+| Preview | `api-version=2018-11-01-preview` |
+| Preview | `api-version=2018-08-15-preview` |
 
-- `api-version=2016-12-12`
-- `api-version=2018-11-01-preview`
+> [!TIP]
+> The required API query value to use for each API is given in the [reference documentation](https://docs.microsoft.com/rest/api/time-series-insights/).
 
-Optional URL query string parameters:
+Optional URL query string parameters include setting a timeout for HTTP request execution times.
 
-- `timeout=<timeout>` – server-side timeout for the request execution. Applicable only to the [Get Environment Events](https://docs.microsoft.com/rest/api/time-series-insights/ga-query-api#get-environment-events-api) and [Get Environment Aggregates](https://docs.microsoft.com/rest/api/time-series-insights/ga-query-api#get-environment-aggregates-api) APIs. Timeout value should be in ISO 8601 duration format, for example `"PT20S"` and should be in the range `1-30 s`. Default value is `30 s`.
+| Optional query parameter | Description |
+| --- |  --- |
+| `timeout=<timeout>` | Server-side timeout for HTTP request execution. Applicable only to the [Get Environment Events](https://docs.microsoft.com/rest/api/time-series-insights/ga-query-api#get-environment-events-api) and [Get Environment Aggregates](https://docs.microsoft.com/rest/api/time-series-insights/ga-query-api#get-environment-aggregates-api) APIs. Timeout value should be in ISO 8601 duration format, for example `"PT20S"` and should be in the range `1-30 s`. Default value is `30 s`. |
 
 ## Next steps
 
@@ -148,4 +160,4 @@ Optional URL query string parameters:
 
 - For API reference information, see [Query API reference](https://docs.microsoft.com/rest/api/time-series-insights/ga-query-api).
 
-- Learn how to [create a service principal](../active-directory/develop/howto-create-service-principal-portal.md).
+- Learn how to [create a service principal](../active-directory/develop/howto-create-service-principal-portal.md).