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.

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.

Summary and best practices

The Azure Active Directory app registration flow involves three main steps.

  1. Register an application in Azure Active Directory.
  2. Authorize the application to have data access to the Time Series Insights environment.
  3. Use the Application ID and Client Secret to acquire a token from https://api.timeseries.azure.com/ in your client app. The token can then be used to call the Time Series Insights API.

Per step 3, separating your application's and your user credentials allows you to:

  • Assign permissions to the app identity that are distinct from your own permissions. Typically, these permissions are restricted to only what the app requires. For example, you can allow the app to read data only from a particular Time Series Insights environment.
  • Isolate the app's security from the creating user's authentication credentials by using a Client Secret or security certificate. As a result, the application's credentials are not dependent on a specific user's credentials. If the user's role changes, the application does not necessarily require new credentials or further configuration. If the user changes their password, all access to the application doesn't require new credentials or keys.
  • Run an unattended script using a Client Secret or security certificate rather than a specific user's credentials (requiring them to be present).
  • Use a security certificate rather than a password to secure access to your Azure Time Series Insights API.

Important

Follow the principle of Separation of Concerns (described for this scenario above) when configuring your Azure Time Series Insights security policy.

Note

  • The article focuses on a single-tenant application where the application is intended to run in only one organization.
  • You'll typically use single-tenant applications for line-of-business applications that run in your organization.

Detailed setup

Azure Active Directory app registration

  1. In the Azure portal, select Azure Active Directory > App registrations > New registration.

    New application registration in Azure Active Directory

    Your app will be listed here after you register it.

  2. Give the application a name and select Accounts in this organizational directory only to specify the Supported account types that may access the API. Choose a valid URI to redirect users to after they authenticate, then Register.

    Create the application in Azure Active Directory

  3. Important Azure Active Directory app information is displayed in your listed app's Overview blade. Select your app under Owned applications, then Overview.

    Copy the application ID

    Copy your Application (client) ID to use in your client application.

  4. The Authentication blade specifies important authentication configuration settings.

    1. Add Redirect URIs and configure Access Tokens by selecting + Add a platform.

    2. Determine whether the app is a public client or not by selecting Yes or No.

    3. Verify which accounts and tenants are supported.

    Configure Implicit grant

  5. After selecting the appropriate platform, configure your Redirect URIs and Access Tokens in the side panel to the right of the user interface.

    1. Redirect URIs must match the address supplied by the authentication request:

      • For apps hosted in a local development environment, select Public client (mobile & desktop). Make sure to set public client to Yes.
      • For Single-Page Apps hosted on Azure App Service, select Web.
    2. Determine whether a Logout URL is appropriate.

    3. Enable the implicit grant flow by checking Access tokens or ID tokens.

    Create Redirect URIs

    Click Configure, then Save.

  6. Select Certificates & secrets then New client secret to create an application password that your client app can use to prove its identity.

    Create a new client secret

    Your client secret password will then be displayed. Copy the key to your favorite text editor.

    Note

    You have the ability to import a certificate instead. For enhanced security, a certificate is recommended. To use a certificate, select Upload certificate.

  7. Associate your Azure Active Directory app Azure TIme Series Insights. Select API permissions > Add a permission > APIs my organization uses.

    Associate an API with your Azure Active Directory app

    Type Azure Time Series Insights into the search bar then select Azure Time Series Insights.

  8. Next, specify the kind API permission your app requires. By default, Delegated permissions will be highlighted. Choose a permission type then, select Add permissions.

    Specify the kind of API permission your app requires

Granting data access

  1. For the Time Series Insights environment, select Data Access Policies and select Add.

    Add new data access policy to the Time Series Insights environment

  2. In the Select User dialog box, paste either the Application Name or the Application ID from the Azure Active Directory app registration section.

    Find an application in the Select User dialog box

  3. Select the role. Select Reader to query data or Contributor to query data and change reference data. Select OK.

    Pick Reader or Contributor in the Select User Role dialog box

  4. Save the policy by selecting OK.

    Tip

    For advanced data access options, read granting data access.

Client app initialization

  • Developers may use the [Microsoft Authentication Library (MSAL) to authenticate with Azure Time Series Insights.

  • To authenticate using ADAL:

    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.

    2. In C#, the following code can acquire the token on behalf of the application. For a complete sample, read Query data using C#.

      private static async Task<string> AcquireAccessTokenAsync()
      {
          if (AadClientApplicationId == "#PLACEHOLDER#" || AadScopes.Length == 0 || AadRedirectUri == "#PLACEHOLDER#" || AadTenantName.StartsWith("#PLACEHOLDER#"))
          {
              throw new Exception($"Use the link {"https://docs.microsoft.com/azure/time-series-insights/time-series-insights-get-started"} to update the values of 'AadClientApplicationId', 'AadScopes', 'AadRedirectUri', and 'AadAuthenticationAuthority'.");
          }
      
          IPublicClientApplication app = PublicClientApplicationBuilder
                      .Create(AadClientApplicationId)
                      .WithRedirectUri(AadRedirectUri)
                      .WithAuthority(AadAuthenticationAuthority)
                      .Build();
      
          AuthenticationResult result = await app
                      .AcquireTokenInteractive(AadScopes)
                      .ExecuteAsync();
      
          // Show interactive logon dialog to acquire token on behalf of the user.
          // Suitable for native apps, and not on server-side of a web application.
          // AuthenticationResult result = await app
          //          .AcquireTokenInteractive(AadScopes)
          //          .ExecuteAsync();
          //    
          //    // Set redirect URI for Azure PowerShell
          //    redirectUri: new Uri("urn:ietf:wg:oauth:2.0:oob"),
          //    parameters: new PlatformParameters(PromptBehavior.Auto));
      
          return result.AccessToken;
      }
      
      
    3. The token can then be passed in the Authorization header when the application calls the Time Series Insights API.

See our [Manage GA reference data for an Azure Time Series Insights environment using C#](time-series-insights-manage-reference-data-csharp.md) article to learn more.

Common headers and parameters

This section describes common HTTP request headers and parameters used to make queries against the Time Series Insights GA and Preview APIs. API-specific requirements are covered in greater detail in the Time Series Insights REST API reference documentation.

Tip

Read the Azure REST API Reference to learn more about how to consume REST APIs, make HTTP requests, and handle HTTP responses.

Authentication

To perform authenticated queries against the Time Series Insights REST APIs, a valid OAuth 2.0 bearer token must be passed in the Authorization header using a REST client of your choice (Postman, JavaScript, C#).

Tip

Read the hosted Azure Time Series Insights client SDK sample visualization to learn how to authenticate with the Time Series Insights APIs programmatically using the JavaScript Client SDK along with charts and graphs.

HTTP headers

Required request headers are described below.

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.

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 AuthURL will therefore be: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com/.default
  • https://api.timeseries.azure.com/ is valid but https://api.timeseries.azure.com is not.

Optional request headers are described below.

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.

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.
x-ms-property-not-found-behavior GA API optional response header. Possible values are ThrowError (default) or UseNull.

HTTP parameters

Tip

Find more information about required and optional query information in the reference documentation.

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

Optional URL query string parameters include setting a timeout for HTTP request execution times.

Optional query parameter Description Version
timeout=<timeout> Server-side timeout for HTTP request execution. Applicable only to the Get Environment Events and Get Environment Aggregates 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. GA
storeType=<storeType> For Preview environments with warm store enabled, the query can be executed either on the WarmStore or ColdStore. This parameter in the query defines which store the query should be executed on. If not defined, the query will be executed on the cold store. To query the warm store, storeType needs to be set to WarmStore. If not defined, the query will be executed against the cold store. Preview

Next steps