Overview

In this page you will find an explanation on integrating your Office 365 data to Hunters.

Supported Data Types

  • Office 365 Audit logs - audit event logs for various actions over your Office 365 applications (e.g SharePoint, Exchange)

Hunters Ingestion

In order to enable Hunters' ingestion of Office 365 for your account, you will need to perform several administrative steps as a prerequisite.

Collection Prerequisites

Note: In order to execute all the steps, an Azure admin account is required.

In order to collect the data, you will need to follow the rest of this guide, which is based on the official Microsoft guide.

Overview of the following steps (each step is detailed later on):

  1. Register you application for the management API via azure active directory.

    1. Make sure you follow the guide to the end, and also execute the Request an access token using the authorization code stage.

    2. Pass hunters the following keys:

      1. client_id, tenant_id, client_secret - these values are available in the portal and are detailed in the “Register you application” guide

      2. access_token, refresh_token - these values are returned in the “Request an access token using authorization code”

  2. Enable audit logging via office 365

  3. Start subscription for every content type.

Register your app

  1. First you need to register your app in azure portal using this page. Important to fill in the Redirect URI field - for example http://localhost:5110. This parameter will be used later on in this guide.
    Here is an example on how the registration process should look like:

     

  2. Now you need to add the ActivityFeed.Read, ActivityFeed.ReadDlp, ServiceHealth.Read permission for your app:

    1. Go to azure Active Directory

    2. On the left sidebar choose App registrations

    3. Choose the app you registered in the previous step.

    4. Go to API permissions on the left sidebar.

    5. Press Add a premission

    6. Choose the Microsoft Graph option

    7. Choose Application premissions option, and add the three options mentioned above:

       

    8. In case you have Not granted for ... Directory alert on the permissions, you need to press on the Grant admin consent for ... Directory bottom.


      a popup window will pop up -

      choose yes.
      The status for each permission should be changed to  Granted for ... Directory:

       

  3. Add a new client secret to your app:

    1. Go to azure Active Directory

    2. On the left sidebar choose App registrations

    3. Choose the app you registered in the previous step.

    4. Go to Certificates & secrets on the left sidebar.

    5. Press New Client Secret.

    6. After adding the client secret, you will see a new record under Certificates & secrets, its value will be used later in this guid.
      Important: The value of the client secret is only displayed when created, so make sure to write it down and keep it for later use!

Retrieve an Authorization Code

This stage is based on this guide.

  1. Open the browser on which you logged in to the Azure Portal

  2. Paste in the url:
    https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https://manage.office.com&client_id={client_id} 

    1. client_id - The application id of your registered app. Can be found in:
      Azure Active Directory → App registrations → Under Application (client) ID of your app.

  3. You will be redirected and in the new url you will receive the Authorization Code.

Get a Refresh Token

Open terminal and run the following command:
curl -X POST -d 'client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code&code={authorization_code}' -H "Content-Type: application/x-www-form-urlencoded" https://login.windows.net/common/oauth2/token

An access token and a refresh token will be returned, you will need the access token for the next step and Hunters will need the refresh token.

Deliver Keys to Hunters

The parameters needed for Hunters to collect the data are:

  1. client_id - The application id of your registered app. Can be found in:
    Azure Active Directory → App registrations → Under Application (client) ID of your app.

  2. client_secret - the value of the client secret you created in step 3 in the Pre collection phase.

  3. refresh_token - The refresh token you retrieved in earlier step.

Enable Auditing

This stage has to be done in order to follow the next step and eventually in order for Hunters to collect the data.

Here you will find a very detailed guid in order to do so.

Start Subscriptions

The office 365 audit logs are available for various content types, in order for Hunters to collect the data you will need to start a subscription for each content type:
Open terminal and run the following command:

curl -X POST -H "Content-Length: 0" -H "Authorization: Bearer {access_token}" "https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/subscriptions/start?contentType={content_type}"

content_type can be one of the following:

  • Audit.AzureActiveDirectory

  • Audit.Exchange

  • Audit.SharePoint

  • Audit.General (includes all other workloads not included in the previous content types)

  • DLP.All (DLP events only for all workloads)

Hunters recommend to start a subscription for all the available content types.

Expected Format

In case you supply the logs to a shared storage service directly, this is the events' expected format:

{"CreationTime": "2022-05-11T13:34:07", "Id": "123456", "Operation": "UserLoggedIn", "OrganizationId": "1111", "RecordType": 15, "ResultStatus": "Success", "UserKey": "12345", "UserType": 0, "Version": 1, "Workload": "AzureActiveDirectory", "ClientIP": "1.1.1.1", "ObjectId": "000000", "UserId": "john@doe", "AzureActiveDirectoryEventType": 1, "ExtendedProperties": [{"Name": "ResultStatusDetail", "Value": "Redirect"}, {"Name": "UserAgent", "Value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.41 Safari/537.36"}, {"Name": "RequestType", "Value": "OAuth2:Authorize"}], "ModifiedProperties": [], "Actor": [{"ID": "12345", "Type": 0}, {"ID": "john@doe", "Type": 5}], "ActorContextId": "12345", "ActorIpAddress": "1.1.1.1", "InterSystemsId": "12345", "IntraSystemId": "6789", "SupportTicketId": "", "Target": [{"ID": "0000", "Type": 0}], "TargetContextId": "12345", "ApplicationId": "12345", "DeviceProperties": [{"Name": "OS", "Value": "MacOs"}, {"Name": "BrowserType", "Value": "Chrome"}, {"Name": "IsCompliantAndManaged", "Value": "False"}, {"Name": "SessionId", "Value": "123"}], "ErrorNumber": "0"}
CODE

If there is anything unclear or you have any further questions please contact our support 🙂