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

Important

  • The new Azure Active Directory > App registrations blade replaces the legacy Azure Active Directory > App registrations (Legacy) blade May 2019.
  • App registrations created or displayed in the legacy blade will automatically appear in the new blade.
  • For comprehensive information about migrating to the new Azure App registration experience, read the Azure App registrations training guide and Azure Active Directory Quickstart.
  1. In the Azure portal, select Azure Active Directory > App registrations > New registration.

    New application registration in Azure Active Directory

    Tip

    The new Azure Active Directory App registration panel allows you to filter the displayed apps by selecting Owned applications.

    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. 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 the Default client type to yes.
      • For Single-Page apps hosted on Azure App Service, select Web.
    2. Enable the implicit grant flow by checking ID tokens.

    Create a new client secret

    Click Save.

  5. Select Certificates & secrets then New client secret to create an application password that client 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.

  6. 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.

  7. 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

    Read about granting data access to your Time Series Insights environment in Azure Active Directory.

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.

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

    // 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);
    
    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"));
    
    string accessToken = token.AccessToken;
    
  2. The token can then be passed in the Authorization header when the application calls the Time Series Insights API.

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.

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#).

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 with therefore conform to: 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 to see 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:

  • 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).

Optional request headers:

  • 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.

Response headers:

  • 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:

  • api-version=2016-12-12
  • api-version=2018-11-01-preview

Optional URL query string parameters:

  • timeout=<timeout> – server-side timeout for the 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.

Next steps