Set Up Collection of Microsoft Office 365 Logs

Alert Logic supports Microsoft Office 365 log collection. To collect Office 365 logs, you must first create and set up an Alert Logic application in Microsoft Azure.

Before you begin

To perform the setup required to grant Alert Logic permission to collect Office 365 logs, you must have access to the following:

  • A Microsoft Office 365 account with administrative privileges
  • A Microsoft Azure account with administrative privileges
  • An Alert Logic account with administrative privileges

You cannot complete this procedure without administrative privileges in all three accounts.

Register a new Office 365 web application

In the Office 365 portal, you must register a new Office 365 web application to collect Office 365 logs.

To register an Office 365 web application:

  1. Log into the Office 365 portal as an Active Directory tenant administrator.
  2. Click Show all to expand the left navigation area, and then click Azure Active Directory.
  3. Select App Registrations, and then click + New application registration.
  4. Provide the following information in the fields:
    • Name - for example, alo365collector.
    • Select Single tenant for supported account types.
    • Leave the Redirect URI blank.
  5. Click Register. Note the Application (client) ID, for example, a261478c-84fb-42f9-84c2-de050a4babe3.

Set up Active Directory security permissions

You must set up Active Directory security permissions for the application you created so it can read threat intelligence data and activity reports for your organization.

To set up Active Directory permissions:

  1. On the main panel under the new application, click API Permissions, and then click + Add a permission.
  2. Locate and click Office 365 Management APIs.
  3. In Application permissions, expand and select ActivityFeed.Read, ActivityFeed.ReadDlp, ActivityReports.Read(both), ServiceHealth.Read, and ThreatIntelligence.Read (both).
  4. Ensure all necessary permissions are selected, and then click Add permissions.
  5. Click Grant admin consent, and then click Accept to confirm.
  6. Only the Active Directory tenant administrator can grant permissions to an Azure Active Directory application.
  7. On the left navigation area, select Certificates & secrets, and then click + New client secret.
  8. Type a key Description and set the duration to Never.
  9. Click Add.
  10. Save the key value, which you need during ARM template deployment.
  11. Click Overview to return to the application summary, and then click the link under Managed application in local directory.
  12. Click Properties, and then note the Object ID associated with the application.
  13. This Object ID not the same Object ID found under the Registered app view or under Settings.

Create an Alert Logic access key

You must create an access key that allows the application you created to connect to the Alert Logic back end.

From the Bash command line in Azure Cloud Shell, run the following commands, where <username> is your Alert Logic user name and <password> is your Alert Logic password.

export AL_USERNAME='<username>'

auth=$(curl -SX POST -u $AL_USERNAME https://api.global-services.global.alertlogic.com/aims/v1/authenticate); export AL_ACCOUNT_ID=$(echo $auth | jq -r '.authentication.account.id'); export AL_USER_ID=$(echo $auth | jq -r '.authentication.user.id'); export AL_TOKEN=$(echo $auth | jq -r '.authentication.token'); if [ -z $AL_TOKEN ]; then echo "Authentication failure"; else roles=$(curl -SX GET -H "x-aims-auth-token: $AL_TOKEN" https://api.global-services.global.alertlogic.com/aims/v1/$AL_ACCOUNT_ID/users/$AL_USER_ID/roles | jq -r '.roles[].name'); if [ "$roles" != "Administrator" ]; then echo "The $AL_USERNAME doesn’t have Administrator role. Assigned role is '$roles'"; else curl -SX POST -H "x-aims-auth-token: $AL_TOKEN" https://api.global-services.global.alertlogic.com/aims/v1/$AL_ACCOUNT_ID/users/$AL_USER_ID/access_keys | jq .; fi; fi; unset AL_USERNAME;

A successful response returns an access key ID and a secret key.

{
  "access_key_id": "712c0b413eef41f6",
  "secret_key": "1234567890b3eea8880d292fb31aa96902242a076d3d0e320cc036eb51bf25ad"
}

If the output is blank, verify your Alert Logic user account has administrator permissions. For more information, see Customer Accounts, User Accounts, and User Roles.

Note the access_key_id and secret_key values, which you need in the deployment steps below.

An account can create only five access keys. If you receive a "limit exceeded" response, you must delete some keys to create more. You can use the following command to list your current access keys:
curl -s -X GET -H "x-aims-auth-token: $AL_TOKEN" https://api.global-services.global.alertlogic.com/aims/v1/$AL_ACCOUNT_ID/users/$AL_USER_ID/access_keys | jq
Use the following command to delete a specific access key:
curl -X DELETE -H "x-aims-auth-token: $AL_TOKEN" https://api.global-services.global.alertlogic.com/aims/v1/$AL_ACCOUNT_ID/users/$AL_USER_ID/access_keys/<ACCESS_KEY_ID_HERE>

Download and deploy the Azure Resource Manager (ARM) template

Before you can configure Office 365 log collection, you must log into Microsoft Azure and download and deploy an ARM template. You can use either the Microsoft Azure portal or a command line to deploy the template.

The steps in this section require an active Azure subscription. To verify your Azure subscription, visit Azure subscriptions blade.

If your organization uses multiple Active Directory tenants, log into the same tenant used to Register a new Office 365 web application. To find your Office 365 tenant ID, see Find your Office 365 tenant ID.

Deploy with the custom ARM template through the Azure portal

To access and deploy the ARM template through the Azure portal, click this link, and then:

  1. Provide the following required template parameters:
    • Name: The name of the log source to appear in the Alert Logic console.
    • Resource Group: Create a new resource group for the collector.
    • Storage Name: Any storage account name that does not currently exist.
    • Alert Logic Access Key ID: The access_key_id you created above.
    • Alert Logic Secret Key: The secret_key you created above.
    • Alert Logic API endpoint: Leave the default value (api.global-services.global.alertlogic.com).
    • Alert Logic Data Residency: Leave the default value.
    • Office 365 Content Streams: The log types you want to collect. Valid values are:
      • ["Audit.AzureActiveDirectory","Audit.Exchange","Audit.SharePoint","Audit.General"]
    • Service Principal ID: The Object ID of the application that created the subscription.
    You can obtain this value from Azure > AD > App registrations > Your app name > Link under Managed application in local directory > Properties > Object ID.
    • App Client ID: The GUID of your application that created the subscription. You can obtain it from Azure > AD > App registrations > Your app name
    • App Client Secret: The secret key of your application from App Registrations
  2. Click Purchase.

Deploy through the Azure CLI

If you want to deploy through the Azure command line, you can use either Azure Cloud Shell or a local installation of Azure CLI.

To deploy through the Azure command line:

  1. In the command line, type the following to create a new resource group. (The example below creates a new resource group in the "Central US" location.)
    az group create --name <new-resource-group-name> --location "Central US"
  2. In the Azure portal, access the Resource groups blade, and then select the resource group you created.
  3. Select Access Control (IAM), and add the Website Contributor role to the Active Directory application identity you created above.
  4. In the command line, type the following command to deploy a template, and enter the required parameters when prompted.
    az group deployment create \
       --resource-group <new-resource-group-name> \
       --template-uri "https://raw.githubusercontent.com/alertlogic/azure-collector/master/template.json"

Verify the installation

As a best practice, you should verify the template installed successfully.

To verify successful installation of the template:

  1. In the Azure portal, access Function Apps, and then choose the Alert Logic Office 365 collector function.
  2. Click Functions > Master > Monitor, and verify the recent log entry has the status of OK and contains no error messages.
  3. In the Alert Logic console, navigate to Deployments > All Deployments > Log Sources, and then filter the list by Push (Office 365, CloudWatch) collection method.
  4. Verify a new Office 365 log source with the name provided during az group deployment create appears with the source status of OK.

If the collector stops sending information to Alert Logic, the Current Status for the source displays the error, "Collector is offline." If you see this error, try one of the following troubleshooting methods:

  • If you either deleted the collector application, or disabled it from the Azure portal, the Alert Logic console may not have removed it. To correct the issue, delete the collector source from the Alert Logic console.
  • Occasionally the collector has an issue with the Azure Active Directory, which causes an error. Alert Logic monitors these errors and resolves them, but you may also restart the function app from the Azure portal.

For information about how Azure functions use the Application and Office 365 tenant ID as a PublisherIdentifier during Office 365 management API requests, see How the Office 365 Collector Works.