This section provides a summary of the procedures required to configure collection from O365.

Prerequisites

Before you start to configure collection from O365, you must ensure you have the following:

  • O365 account with admin access.
  • Azure AD account with admin access that is tied to the O365 account.
  • System Monitor Agent Pro or Collector license.


Enable Auditing in Your Environment

Enable Auditing for SharePoint, OneDrive, and Azure AD

  1. Go to the Office 365 portal (https://portal.office.com).
  2. Log in with your O365 administrator account.
  3. Click the Admin app.
  4. On the left-side menu, click Admin centers, and then click Security.
    The Security & Compliance Center appears.
  5. On the left-side menu, click Search, and then click Audit log search.
    The Audit log search page appears.
  6. Under the Audit log search heading, click the Start recording user and admin activities link.
  7. In the Start recording user and admin activities dialog box, click Turn On.
If you do not see the Start recording user and admin activities link, then auditing for SharePoint, OneDrive, and Azure AD has already been enabled.

(Optional) Enable Auditing for Exchange

Starting in January 2019, Microsoft turned on mailbox audit logging by default for all organizations. This means that certain actions performed by mailbox owners, delegates, and admins are automatically logged, and the corresponding mailbox audit records will be available when you search for them in the mailbox audit log. Before mailbox auditing was turned on by default, you had to manually enable it for every user mailbox in your organization.

  1. Open Windows PowerShell on your local system, and then run the following command:

    $UserCredential = Get-Credential
  2. In the Windows PowerShell Credential Request dialog box, type your O365 user name and password, and then click OK.
  3. To open the credentials prompt for O365, run the following commands:

    $Session = New-PSSession -ConfigurationName Microsoft.Exchange -
    ConnectionUri https://outlook.office365.com/powershell-liveid/ -
    Credential $UserCredential -Authentication Basic -AllowRedirection 
    Import-PSSession $Session
  4. To enable the admin audit log, run the following command:

    Set-AdminAuditLogConfig -UnifiedAuditLogIngestionEnabled $true
  5. To get all mailboxes, run the following command:

    $Mailboxes = (Get-Mailbox)
  6. To group mailboxes by what is enabled, run the following commands:

    $Group = $Mailboxes | Group-Object AuditEnabled,AuditDelegate | Select-
    Object "Name","Count",@{Name="Account"; Expression={ $_.Group.Identity }}
    $Group | Format-Table -AutoSize
  7. To audit everything from every mailbox, run the following command:

    (Get-Mailbox).Identity | % { Set-Mailbox -Identity $_ -AuditDelegate 
    SendAs,SendOnBehalf,Create,Update,SoftDelete,HardDelete -AuditEnabled 
    $true }
    Larger enterprises may want to filter the target mailbox into smaller batches.


    If new accounts are added in the future, you will need to run this command again to ensure that new mailboxes are audited.

    When you are finished, disconnect the remote PowerShell session by running the following command:

    Remove-PSSession $Session

    Failure to disconnect could use up all your available remote PowerShell sessions, forcing you to wait for the sessions to expire.


Register an Application with Azure AD

Open the Azure AD Portal

These steps might reference a version of the Azure AD portal that is different from the one you have. If your user interface does not have the menus and descriptions included here, see https://msdn.microsoft.com/EN-US/library/dn707383.aspx for more information on registering your application.
  1. On the left-side menu in the Office 365 portal Admin app, click Admin centers, and then click Azure AD.
    The Azure AD Dashboard appears.
  2. On the left-side menu, click Azure Active Directory.
  3. If you have more than one directory, select the correct directory name.

Create an Application

  1. On the directory page, click App Registrations from the menu on the left.
  2. In the top menu, click New Registrations.
  3. Complete the fields on the right side of the page:
    • Name the application.
    • Select a support account type.
    • Provide a sign-on URL (for example, https://localhost/).
  4. Click Register.
    Your new application appears under the Display Name header.

Add O365 Management API Permissions

  1. On the directory page, click the name of your application.
  2. Click API permissions.
  3. Click Add a permission.
  4. Under Request API permissions, click Office 365 Management APIs.
  5. Click Application permissions.
  6. Under Application Permissions, expand the headers and select the following check boxes:
    • ActivityFeed.Read
    • ActivityFeed.ReadDlp
    • ServiceHealth.Read
  7. Click Add permissions.
  8. Verify that your changes have been saved on the API permissions page.
  9. Select Grant admin consent for "Organization Name" to apply the Application Permissions previously selected.
  10. Select Yes to continue.
    Successfully granted admin consent for the requested permissions appears.


Configure the Self-Signed Certificate

Create the self-signed certificate using one of the methods below. You can also obtain a certificate signed by a publicly trusted certificate authority (CA).

(Optional) Create the Certificate via Powershell

  1. Open Powershell.
  2. To generate the certificate, run the following command:
    New-SelfSignedCertificate -Subject "C=<Country Code>,ST=<State>,L=<Locality>,O=<Organisation>,CN=<Common Name>" -KeyLength 2048 -CertStoreLocation "cert:\LocalMachine\My" -KeyUsage None -KeyAlgorithm RSA -KeyExportPolicy ExportableEncrypted -KeyUsageProperty All -NotAfter (Get-Date).AddYears(3) -KeySpec Signature

    Example

    New-SelfSignedCertificate -Subject "ST=CO,CN=LRSIEM" -KeyLength 2048 -CertStoreLocation "cert:\LocalMachine\My" -KeyUsage None -KeyAlgorithm RSA -KeyExportPolicy ExportableEncrypted -KeyUsageProperty All -NotAfter (Get-Date).AddYears(3) -KeySpec Signature
    The resulting certificate is valid for three years.

(Optional) Create the Certificate via MakeCert.exe

  1. Go to the \Bin folder of the Microsoft Windows Software Development Kit (SDK), then open MakeCert.
    You can download the Microsoft Window SDK at http://go.microsoft.com/fwlink/p/?linkid=84091.

    If you do not use Microsoft Window SDK, you can also obtain a certificate signed by a publicly trusted certificate authority (CA).

  2. In the command line of MakeCert, run the following command:

    <MakeCert file location>makecert -r -pe -n <Cert Name> -b <MM/DD/YYYY> -e <MM/DD/YYYY> -ss my -len 2048
    For these commands, you must use the minus key (-) at the top of the keyboard—between the zero key (0) and the equals key (=)—rather than the minus key on the numeric keypad.
    • -r -pe: Self-signed exportable cert
    • -n: <Cert Name>: "CN=[Tenant Name] [Application Name] Cert"

      Example

      CN=MyOrganization TrainingApp Cert
    • -b: Begin time stamp
      If possible, make this the current date.
    • -e: End time stamp
      Unless otherwise necessary, make this two years from the current date.
    • -ss my: Certificate store (personal)
    • -len 2048: Cert key length is 2048 bits (the minimum required by O365)

This certificate will be saved to your personal user certificate store.


Export the Certificate with a Private Key and Public Key

  1. In Windows, click Start, click Run, type mmc, and then press Enter.
    The Microsoft Management Console appears.
  2. Click File, and then click Add/Remove Snap-in.
    The Add or Remove Snap-ins window appears.
  3. Under the Available snap-ins menu, select the Certificates snap-in, and then click Add.
  4. Select My user account, click Finish, and then click OK.
  5. In the top-left corner of the Microsoft Management Console, click the Console Root folder, CertificatesLocal computerPersonal, and then click Certificates
    The certificate created in the Configure the Self-Signed Certificate section should appear in this location.
  6. Right-click the certificate, click All Tasks, and then click Export.
    The Certificate Export Wizard appears.
  7. In the Export Private Key dialog box, select Yes, export the private key, and then click Next.
  8. Verify that the Personal Information Exchange - PKCS #12 (.PFX) button is selected, and that the Include all certificates in the certification path if possible check box is selected, and then click Next.
  9. In the Security dialog box, select the Password check box, enter and confirm a private key password, and then click Next.

    Ensure you retain this private key password because it goes into the office365.ini file after being encrypted with lrcrypt. For more information, see LogRhythm Password Encryption.
  10. In the File to Export dialog box, click Browse, and then save the .pfx file to your system.

    It may be helpful to create a certs directory in C:\Program Files\LogRhythm\LogRhythm System Monitor\config.
  11. Click Next, click Finish, and then click OK.
  12. Right-click the certificate, click All Tasks, and then click Export.
    The Certificate Export Wizard appears.
  13. In the Export Private Key dialog box, select No, do not export the private key, and then click Next.
  14. Select the Base-64 encoded X.509 (.CER) option, and then click Next.
  15. In the File to Export dialog box, click Browse, and then save the .cer file to your system.

    It may be helpful to create a certs directory in C:\Program Files\LogRhythm\LogRhythm System Monitor\config.
  16. Click Next, click Finish, and then click OK.

Upload the Certificate to Azure AD App

  1. Return to the Office 365 portal Admin app.
  2. From the left-side menu, click App Registrations, and then click the name of your application.
  3. From the left-side menu on the application page, click Certificates & secrets.
  4. Click Upload certificate.
  5. Select the .cer file, and then click Add.

Update the office365.ini File

After LogRhythm is identified to Azure, the office365.ini file must be edited so the LogRhythm System Monitor Agent can access the Office 365 Management Activity API. The office365.ini file must be located on the host of the Agent collecting logs.

We have implemented the REST API access token process and will deprecate the ADAL access token process in 2021. Government and new customers must use the REST API process to generate an API access token. For more details, see ADAL Access Token Fields and REST API Access Token Fields in the table below.

To edit the office365.ini file:

  1. Open Windows Explorer on the host of the Agent collecting logs, and then go to the following directory: 
    C:\Program Files\LogRhythm\LogRhythm System Monitor\config.
  2. Open the office365.ini file with a text editor and replace the following values:


SettingDefault ValueDescription
O365Host

manage.office.com

(Enterprise plan)

Host name of the Management Activity API. The default value is for Enterprise customers. The table below indicates values for government plans.

Government PlanValue
GCC governmentmanage-gcc.office.com
GCC high governmentmanage.office365.us
DoD governmentmanage.protection.apps.mil
AuditAzureActiveDirectorytrueEnable auditing of Azure Active Directory Management events.
AuditExchangetrueEnable auditing of Exchange Management events.
AuditSharepointtrueEnable auditing of Sharepoint events.
DLPEventstrueEnable for collection of DLP events. To disable DLP events, you must set this flag to FALSE.
AuditGeneraltrueEnable auditing of General events. To disable general audit events, you must set this flag to FALSE.

Azure Active Directory Application Fields

ADAL Access Token Fields

Existing Enterprise customers do not need to change these settings to continue to use the default ADAL access token process.

This process will be deprecated in early 2021. We recommend switching to the new REST API process outlined under the REST API Access Token Fields section below. When you switch to the REST API process, you must set the UseAdalToken flag to False.


UseAdalTokenTrueExisting Enterprise customers using the default ADAL access token process do not need to change this setting. If you want to switch to the REST API process now, change this setting to False and refer to the REST API Access Token Fields below.
ClientIDCHANGE_ME

Obtain the ClientID from the Azure AD portal. This can be found in your App Registration > Overview screen (alternatively known as the Application ID).

This must be encrypted using the lrcrypt command line utility. For more information, see LogRhythm Password Encryption.

TenantIDCHANGE_MEObtain the TenantID from the Azure AD portal. This can be found in your App Registration > Overview screen (alternatively known as the Directory ID).
CertificatePathCHANGE_MEPaste the location of your .pfx file, including the file name and extension.
CertificatePasswordCHANGE_ME

Paste the password from the Export the Certificate with a Private Key section.

This must be encrypted using the lrcrypt command line utility. For more information, see LogRhythm Password Encryption.

REST API Access Token Fields

Government and new customers must use the REST API process to generate an API access token. For the REST API process to work, you must set the UseAdalToken flag to False.

UseAdalTokenTrueGovernment and new customers using the REST API access token process, set this flag to False.
ClientSecretCHANGE_ME

The client secret value is generated in your Azure AD portal. For instructions on generating your client secret, see REST API - Obtaining your Client Secret.

This must be encrypted using the lrcrypt command line utility. For more information, see LogRhythm Password Encryption.

TenantDomainCHANGE_ME

Specify your domain in the following format:

<YOUR_DOMAIN>.onmicrosoft.com

LoginURLCHANGE_ME

Enter the value based on your plan. Example values:

Remaining Azure Active Directory Application Fields
Timeout300

The timeout (in seconds) to use when requesting data O365. Range: 10-300 seconds.

LogApiRequestsfalse

logAPIRequest used to enable/disable ApI Requests Logging. Add logger in Logger4Net with name Office365ApiRequestLogger to log in separate file.

MaxBatchSize10

Throttling. Process number of audit contents per batch. Range: 10-100 (Default: 10).

StopCountFetchNewContentIds1000

Throttling. Stop count for number of content Ids. Range: 1000-5000 (Default: 1000).

StopCountCacheFiles50Throttling. Stop count for controlling number of cache files read via flat file reader. Range: 25-100 (Default: 50).
NumOfBackMinutesData15

Number of last minutes Office 365 data need to be fetched when configured to run. Range: 15-1440 minutes (Default: 15 minutes and maximum is 1 day/1440 minutes).

CollectionDelay1Number of minutes for collection delay as it sometimes takes one day (1440 minutes) for Office 365 content to be available on Azure. Range: 1-1440 minutes (Default: 1 minute).
(Optional) Proxy Settings
ProxyServer=OPTIONALThe IP address or DNS name of a proxy server to use for connecting to the specified endpoint.
ProxyPort=OPTIONALThe port to use on the proxy server.
UserName=OPTIONALThe user name to send if authentication is required on the proxy server. If the user name is an email account, be sure to include the full address.
Password=OPTIONAL

The password for the specified user name.

The password must be encrypted using the lrcrypt command line utility. For more information, see LogRhythm Password Encryption.

Domain=OPTIONALThe domain to use for connecting to the proxy server.

3. Save and close the file.


REST API - Obtaining your Client Secret

  1. On the directory page, click the name of your application.
  2. Click Certificates & secrets.
  3. In the Client secrets section, click New client secret.
    The Add a client secret window appears.
  4. In the Description field, enter a description for your secret (for example, O365 Secret).
  5. In the Expires section, select Never.
  6. Click Add.
    Your new client secret value displays in the Value column.
  7. On the right-side of the row containing your client secret, click the Copy icon to copy the new client secret value. 

    The client secret value is only available to copy at the time of generation. Since you cannot retrieve it at a later time, please save this value.
  8. Paste your newly generated client secret value into the ClientSecret field of your office365.ini file.

    This must be encrypted using the lrcrypt command line utility. For more information, see LogRhythm Password Encryption.


(Optional) Add proxy setting 

If a proxy is being used, please modify the following file:

C:\Program Files\LogRhythm\LogRhythm System Monitor\scsm.exe.config

Example before configuration

<!--For o365 to work with Proxy Server we need to enable this section-->
<!--<defaultProxy enabled="true" useDefaultCredentials="true">
	<proxy proxyaddress="Address:Port"/>
</defaultProxy>-->


Example after configuration

<!--For o365 to work with Proxy Server we need to enable this section-->
<defaultProxy enabled="true" useDefaultCredentials="true">
	<proxy proxyaddress="http://192.168.0.9:8080"/>
</defaultProxy>


Add a Log Source in the Client Console

Only Global Admins or Restricted Admins with elevated View and Manage privileges can perform this action.

(Optional) Create a Host Record for Office 365

We recommend you create a Host Record for Office365. You can use the Office365 Host Record as the Log Source Host when creating any Office 365 Log Sources throughout the SIEM.

  1. On the main toolbar, click Deployment Manager.

  2. Click the Entities tab, and then select the Entity to which you want to assign the Host.
  3. In the Entity Hosts pane at the lower-right, click New.
    The Host dialog box appears.
  4. On the Basic Information tab, enter the following details:

    FieldDescription
    Name (required)

    The name to assign to the new host (for example, Office365).

    LogRhythm does not support hostnames that include spaces.

    Host Zone (required)Internal.
    Operating SystemThe operating system of the new host. Click the ellipsis [...] button next to the Operating System box. In the Operating System Selector window, click your operating system in the list, and then click OK.
    Operating System VersionThe version of the selected operating system that is running on the new host.
    Host LocationThe geographic location of the new host. Click the ellipsis [...] button next to the Host Location box. In the Location Selector window, select the country, region, and city where the host is located.
    Brief DescriptionAn optional description of the new host.
    Host Risk Level (required)Represents the amount of risk developed if the system were to become compromised or the subject of some other issue. A value of 0 indicates that no risk is involved in the loss of this system. A value of 9 indicates the most risk would be incurred if the system were compromised. The risk level is relevant when the host is the impacted system, target, or is acted upon by external forces.
    Windows Event Log Credentials

    When the operating system is Windows, if you want the Agent to use different credentials for each host in the deployment when collecting Event Logs, select the Use specified credentials check box and provide the username and password to be used. If you do not select this option, the Agent uses its own service credentials.

    Multi-domain event log collection is only supported on Windows Vista, 7, 8, 2008, or 2012. Windows XP, 2000, and 2003 are not supported.

  5. On the Identifiers tab, enter manage.office.com in the DNS Name field.
  6. On the Host Roles tab, enter any relevant key contacts.
  7. On the Threat Level tab, designate the amount of threat that is developed if the system were to be the origin of actions. Select the Add to Global Source Threat List check box if there is any treat level other than 0 (none/no risk). A value of 1 (low-low (lowest threat)) means that actions originating from this host are of little cause for alarm or are possibly commonplace, and a value of 9 (high-high (highest threat)) means that this system should not be the source of outgoing actions and that there is the greatest threat to security if such events are observed.
  8. On the Additional Information tab, add any other useful information.
  9. Click OK.

Add a Single Log Source

  1. On the main toolbar, click Deployment Manager.
  2. Click the System Monitors tab.
  3. Double-click the System Monitor Agent that will collect the information from the Office 365 Management Activity API.
  4. Right-click within the list of Log Message Sources, and then click New.
    The Log Message Source Properties dialog box appears.
  5. Click the icon to the right of the Log Source Host box. Assign this to be the Office365 Host created previously, then click OK.
  6. Click the icon to the right of the Log Message Source Type box.
    The Log Source Type Selector dialog box appears.
  7. Select the Log Source type:

    1. In the Record Type section on the left side, click System.

    2. In the Text Filter text box, enter Office 365.

    3. Click Apply.

    4. In the Log Source Type section, select API - Office 365 Management Activity.

    5. Click OK.

  8. In the Log Message Processing Settings section, select the desired Log Message Processing Mode and Log MPE Policy. This can be the LogRhythm Default policy or a custom policy you create.
  9. Click the Flat File Settings tab.
  10. In the File Path box, enter the location of the office365.ini configuration file.
    This defaults to C:\Program Files\LogRhythm\LogRhythm System Monitor\config\office365.ini.
  11. Click OK to accept the settings.

    The Log Message Source Properties box appears.

    If the System Monitor Agent is already running, collection begins soon after clicking OK or Apply.
    Monitor the scsm.log file for error messages until you are satisfied that the event collection has begun successfully.
  12. Click OK

Recommendations

Create a Host Record for Office 365 

We recommend you create a Host Record for Office365. You can use the Office365 Host Record as the Log Source Host when creating any Office 365 Log Sources throughout the SIEM. For more information, see Add a Log Source in the Client Console.

Create a Separate Log Source for each Office 365 Event Stream

The Office 365 Management Activity Log Source consists of multiple Event streams from within the Office 365 environment. We recommend you split these streams into separate Log Sources. This enables ease of analytics and increases Log Source throughput efficiency.

To create separate Log Sources, do the following:

  1. Create a different office365.ini configuration file for each Events stream within Office 365. In each configuration file select one of the Events streams to be true, and all other Events streams to be false. The possible Events streams you can enable are:
    • AuditAzureActiveDirectory
    • AuditExchange
    • AuditSharepoint
    • DLPEvents
    • AuditGeneral
  2. Name each office365.ini configuration file to correspond to the Events stream you selected to be true in that file. 

    Example

    Events stream: AuditAzureActiveDirectory

    Configuration file name: Office365AuditAzureAD.ini

    Configuration file settings:

    • AuditAzureActiveDirectory=true
    • AuditExchange=false
    • AuditSharepoint=false
    • DLPEvents=false
    • AuditGeneral=false
  3. Repeat this process for all of the remaining Event streams you wish to enable.
  4. Within the LogRhythm Console, repeat the Add a Log Source in the Client Console steps within this guide to add each Events stream as a separate Log Source. Use a Log Message Source Name that is similar to the name of the Events stream.

    Example

    Events stream: AuditAzureActiveDirectory

    Log Message Source Name: Office365 Mgmt Activity Azure AD

  5. In the Flat File Settings tab, enter the location of the configuration file that corresponds to the Events stream.

    Example

    Events stream: AuditAzureActiveDirectory

    File path: C:\Program Files\LogRhythm\LogRhythm System Monitor\config\Office365AuditAzureAD.ini

The Log Source type for all of the Events streams will still be API - Office 365 Management Activity