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. Navigate to Admin Centers and then click Azure AD.
  3. In the left navigation area, click Azure Active Directory, and then select App Registrations.
  4. Click + New application registration and then provide the following information:
    • Name - for example alo365collector.
    • Select Web app/ API as Application type.
    • In Sign-on URL, enter a URL (for example http://alo365collector.com).
  5. Click Create.
  6. From the All applications tab on the App registration (Preview) blade, select All apps, and then click the application name you created.
  7. Make a note of the Application ID.

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 Settings panel under the new application, select Required permissions, and then click + Add.
  2. Click Select an API > Office 365 Management APIs, and then click Select.
  3. In Application permissions, click Read service health information for your organization > Read activity data for your organization > Read threat intelligence data for your organization > Read activity reports for your organization.
  4. Click Select, and then click Done.
  5. Click Grant Permissions, and then click Yes.
Only the Active Directory tenant administrator can grant permissions to an Azure Active Directory application.
  1. On the Settings panel for the application, select Keys.
  2. Type a key Description and set the duration to Never expires.
  3. Click Save.
Save the key value, which you need during ARM template deployment.
  1. From the Registered App blade, click the link under Managed application in local directory, and then click Properties.
  2. Note the Service Principal ID associated with the application. The Service Principal ID is labeled as "Object ID" on the properties page.
This 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.
    • 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.
  1. In the Alert Logic console, navigate to Configuration > Deployments > All Deployments > Log Sources, and then filter the list by Push (Office 365, CloudWatch) collection method.
  2. Verify a new Office 365 log source with the name provided during az group deployment create appears with the source status of OK.

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.