Azure Log Analytics provider

What are Integrations?

SquaredUp DS Integrations allow you to create your own providers. Each Integration has its own form to help you input the information required for different providers.

What is a provider?

Providers contain the connection details to external platforms. A provider only needs to be set up once and can then be used when creating tiles on a dashboard.

There are two types of integrations and therefore providers:

• generic Web API providers that can connect to any REST API
• dedicated providers that connect to a specific external platform or database (SQL, ServiceNow, Azure Active App Insights, Elasticsearch, etc.)

About Azure Log Analytics provider

An Azure Log Analytics provider stores the authentication details for your Azure Log Analytics instance.

This provider allows you to use the Azure Log Analytics tile.

How do I use the tile after I created the provider for it?

See How to use the Azure Log Analytics tile

Prerequisites

• If you use a proxy server you may need to configure the proxy to allow the Azure Log Analytics tile to communicate with Log Analytics (see How to configure SquaredUp DS to use a proxy).
• A Microsoft Azure Log Analytics workspace.
• For configuring the provider you will also need the following: (which are not required for using the tile)
  • Azure subscription administrator role
  • Azure Active Directory User administrator role

Connecting SquaredUp DS to Azure Log Analytics is a simple procedure, but requires some one-time configuration in your Azure Active Directory (AAD) environment prior to making a SquaredUp DS provider. These settings will enable permissions and connectivity for API access, and only need to be performed once regardless of the number of SquaredUp DS instances you have.

Configure Azure Active Directory

In order for SquaredUp DS to authenticate and access Log Analytics data you must create an Azure AD application that represents SquaredUp DS and configure an SPN for that application with the appropriate permissions to access Log Analytics data for your workspace(s).

In order to complete the Azure Active Directory configuration process, you will need to have Administrative permissions over Azure AD.

A. Add Log Analytics as a new Service Principal in your Azure Active Directory

This step is required to ensure that your Azure Active Directory is set up to interact with the Log Analytics API.

Adding the Service Principal is a one-time operation.

First, you will need to find your Azure Active Directory Tenant ID, and then create a new Log Analytics API Service Principal. The instructions below assume you have PowerShell v4 or later installed (if not, you can use the in-browser PowerShell session right from the Azure portal).

1. In the Azure portal, open your Azure Active Directory resource.
2. Take note of the Tenant ID as you will need it in following steps, and it will be entered as the azure active directory id on the azure log analytics provider page later.
3. Start a new PowerShell prompt, and type in the below:
   Install-Module AzureAD
Connect-AzureAD -TenantId <AAD Tenant ID> -Credential (get-credential)
   where <AAD Tenant ID> is the Tenant ID located in the previous step
4. You will get a prompt to log in using your Azure credentials.
5. Execute the following command:
   New-AzureADServicePrincipal -AppId ca7f3f0b-7d91-482c-8e09-c5d840d0eac5 -DisplayName "Log Analytics API"

B. Create an Azure Active Directory Application

In this step, you will create an AAD application, which SquaredUp DS will use to authenticate against your AAD. If you have previously used the v3 OMS tile in this AD Tenant, you can use the existing application that was created for that tile (skip this section).

1. Open your Azure Active Directory resource in the Azure portal and click on App registrations.
2. Click New application registration.
3. Give your application a name (such as SquaredUp DS). Make sure the application type is set to Web app/API. Finally, enter a sign-on URL for SquaredUp DS. This must be unique, but is only used if someone clicks on a link to the application within Azure. If you do not wish to enter your URL here, you can put in a dummy value such as http://server.local/.
4. Click create.

C. Allow the Application to access Log Analytics data

1. Open the Azure Active Directory resource and under the App registrations page, find your SquaredUp DS app, and click on it to open its details page.
2. Take note of the Application ID as you will need it later. (This will be entered as the active directory application id on the provider page later).
3. Click API permissions > Add a permission
4. On the Request API permissions page, select the Service Principal you created in the first section of these instructions (i.e. Log Analytics API or Application Insights API).
5. Click Delegated Permissions and ensure that Read <app> data as user is checked, and click Add permissions.
6. Finally, you need to create a new client secret. Under Manage click on Certificates & secrets and then New client secret. Give your secret a description and an expiry and press Add. Your client secret value will be generated and displayed - make sure to copy the value, as it cannot be retrieved once you navigate away from the page. (This will be entered as the application key on the provider page later).
   We now have an application that will allow us to authenticate against your Azure Active Directory!

D. Grant access from your Azure AD application to Log Analytics workspaces

In this step you will allow the Azure AD application to access Log Analytics workspaces. This step will need to be repeated on each Log Analytics workspace you want to query using SquaredUp DS.

1. Find your Log Analytics resource on the Azure portal.
2. Take note of the Workspace ID as you will need it later. (This will be entered as the workspace id on the azure log analytics provider page later).
3. Next, click on Access Control (IAM) and then Add.
4. Set the Role to Log Analytics Reader.
5. On the Select dropdown list click on the AAD application created earlier, and make sure it appears under Selected members.
6. Click Save.

Adding an Azure Log Analytics provider in SquaredUp DS

Now that SquaredUp DS has an identity within Azure Active Directory that it can use to query Log Analytics workspaces, you need to provide the details to SquaredUp DS. A provider defines the Log Analytics workspace that you wish to query, and the identity used for doing so (in this case, the Azure AD Application authenticates to query Log Analytics as the user who authorizes the provider).

If you have multiple workspaces that you want to query, you can either create multiple providers (one per workspace) and/or create an empty Log Analytics workspace for use with the provider, and then use the additional workspaces option in each tile to query up to 10 workspaces simultaneously.

1. Create provider for a Log Analytics workspace

1. In SquaredUp DS navigate to the right-hand menu ☰ > system > Integrations

2. Under Integrations click on Azure Log Analytics and type in a suitable name, e.g. LondonLogAnalytics.

   

3. In the workspace id box enter the Log Analytics workspace ID you noted down in section D above.
4. In the Azure Active Directory ID box enter the Tenant ID that you noted down in section A.
5. In the Azure Active Directory Application ID box enter the Azure Active Directory Application ID you noted down at the beginning of section C above.
6. In the Application Key box enter the application secret value that you noted down at the end of section C above.

   

7. Select your Log Analytics endpoint.

   https://api.loganalytics.io	Default endpoint
   https://api.loganalytics.us	US Government endpoint

   How to add your own endpoints

   Connection settings can be configured in the connections.json file.

   1. On the SquaredUp server, run Notepad as administrator (Start, Run, type notepad, and then right-click and select Run as administrator).
      With Notepad in administrator mode, open the connections.json file from the following path in the SquaredUp DS folder:
      ...\User\Configuration\connections.json

   Where to find the SquaredUp folder

   Name of the SquaredUp folder

   The default name of the SquaredUp folder is SquaredUp for v6 and above.

   For v5 it is SquaredUpv5.

   Location of the SquaredUp folder

   If you deployed SquaredUp DS via the Azure or AWS Marketplace:

   The default location for the SquaredUp folder is F:\SquaredUpv[Version Number].
   For v5 it is F:\SquaredUpv5.

   If you installed SquaredUp DS using the installer:

   A custom location may have been chosen during the installation.

   The default location for the SquaredUp folder is C:\inetpub\wwwroot\SquaredUp

   For v5 it is C:\inetpub\wwwroot\SquaredUpv5.

   1. Add a log-analytics-endpoints JSON object to the existing entries in connections.json, consisting of both an apiDomain and authDomain key pair value. For example:
      Copy

      "log-analytics-endpoints": [
          {
            "apiDomain": "https://somedomain.com",
            "authDomain": "https://login.microsoftonline.de"
          },
          {
            "apiDomain": "https://someotherdomain.com",
            "authDomain": "https://login.microsoftonline.hk"
          }
        ]

   2. Save the file.
   3. In IIS recycle the SquaredUp DS application pool for the setting to take effect.
      If you are unable to access SquaredUp DS ("Server Error in '/SquaredUpvx' Application", "SquaredUp DS cannot start due to an error" or "Startup failed for 'Configuration'") after editing connections.json then there is an error in the file. Correct connections.json and recycle the SquaredUp DS application pool again.

8. Click save.

2. Add Reply URL to Azure AD Application and authorize provider

Once the provider is created, the final step is to authorize it within Azure AD. These credentials are sent to Azure AD and are not stored anywhere within SquaredUp DS.

1. Note down the reply url listed under the newly created provider in SquaredUp DS.
2. In the Azure portal, click on the Azure Active Directory resource and under the App registrations page, find your SquaredUp DS app, and click on it to open it's Overview page.
3. Click on Authentication.
4. Add the URL from step 1 to the list of Redirect URIs.
5. Wait a few minutes for the Azure AD to process the update, then back in SquaredUp DS click perform authorization under the newly created provider.
   If you do not want to repeatedly add a reply URL to the application for each new provider, you can specify a wildcard when configuring the reply URL using a * (e.g. https://server.local/*).

Troubleshooting

Attempts to authorize the provider fail

Ensure that you have added the Reply URL to the Azure AD application, and that you have given Azure enough time to replicate the configuration (often takes several minutes).

How do I use the tile after I created the provider for it?

See How to use the Azure Log Analytics tile