Integrate a Microsoft Office 365 Cloud Device

Integrate a Microsoft Office 365 cloud device to enable indicator of compromise (IOC) sharing between Rapid7 and your Microsoft environment.

This table describes the integration characteristics specific to Microsoft Office 365:

To integrate the device and enable it to receive IOCs:

1. Configure an application in Entra ID.
2. Create an anti-spam policy in Microsoft 365 Defender.
3. Add the device to Digital Risk Protection (Threat Command).
4. Configure an IOC group to push IOCs to the device.

Configure an application in Entra ID

The application enables pushing IOCs from Threat Intelligence to a Microsoft Office 365 Defender anti-spam policy.

Prerequisites:

• Access to Entra ID.
  • Any user can complete this process. However, a user with the Privileged Administrator role must approve the requested API permissions in Entra ID before they take effect.
• Access to a Windows physical or virtual machine.

To configure an application:

1. Log in to Entra ID .
2. Register a new application:
   1. From Entra ID, click App registrations then click New registration.
   2. Enter a user-defined name for the app.
   3. Retain the default values for all remaining fields and click Register. The new application details are displayed.
   4. Copy the Application (client) ID for later use.
   • Example ID: 5ed6625d-b980-43ae-9b89-655cb958e45b
3. Set permissions for the new application:
   1. From the application details screen, click API permissions. In the Configured permissions section, permissions have been granted for Microsoft Graph only.
   2. Click Add a permission. The Request API permissions section is displayed in the right-panel.
   3. Select APIs my organization uses.
   4. In the search field, search for office 365 and select Office 365 Exchange Online.
   5. Choose Application permissions.
   6. In the Select permissions section, expand the Exchange option and select Exchange.ManageAsApp and Exchange.ManageAsApp V2
   7. Click Add permissions. Office 365 Exchange Online has been added to the Configured permissions section and now permissions can be added.
   8. Approve the user to add the permissions by clicking Grant admin consent for <organization> and then confirm the consent.
   • If this option is not displayed, you will need to ask an Admin user to grant consent. For more information, contact the Azure AD administrator.
4. From a Windows machine, create and export CER and PFX certificates:
   • Sample script to create certificates:
     • $PfxPassword = yourpassword
     • $Organization = your.organization.com
     • $AppId = your-app-ip-string

$mycert = New-SelfSignedCertificate -DnsName $Organization -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(3) -KeySpec KeyExchange
$mycert | Export-Certificate -FilePath certificate_file.cer
$mycert | Export-PfxCertificate -Password $(ConvertTo-SecureString -String $PfxPassword -AsPlainText -Force) -FilePath 'ExoCertificateFile.pfx'

5. Upload the CER certificate:
   1. From the application details screen, click Certificates & secrets.
   2. Click Upload certificate.
   3. Upload the CER certificate.
   • The certificate is displayed in the Certificates section. The PFX certificate and password are used later in the process.
6. Run the following commands in PowerShell:
   1. Install or update the Exchange Online management module (EXO V3):

Install-Module ExchangeOnlineManagement -Scope CurrentUser

2. Connect to Exchange Online:

Connect-ExchangeOnline -UserPrincipalName admin@yourtenant.onmicrosoft.com

# Example: Connect-ExchangeOnline -UserPrincipalName MilanKoudelka@rapidintegrationtest.onmicrosoft.com

3. (Optional) Install and authenticate to Microsoft Graph:

Install-Module Microsoft.Graph -Scope CurrentUser -Force Connect-MgGraph -Scopes "Application.Read.All"

4. Find the service principal (Enterprise Application) by App ID:

$sp = Get-MgServicePrincipal -Filter "appId eq 'YourAppID'"

Example: $sp = Get-MgServicePrincipal -Filter "appId eq 'YourAppID'"

$sp.Id      # this is the enterprise app object id (ServiceId in New-ServicePrincipal)

5. Create the Exchange service principal reference, replacing placeholders where applicable:

New-ServicePrincipal -AppId YourAppId -ServiceId YourServiceID -DisplayName "Rapid7 O365 App"

# Example: New-ServicePrincipal -AppId 5ed6625d-b980-43ae-9b89-655cb958e45b -ServiceId 1a4358f5-e27a-4354-8074-0fe335490ded -DisplayName "Rapid7 O365 App"

6. Choose a role group:

Get-RoleGroup | Select Name

• Common candidates (names vary by tenant):
  • Security Administrator
  • Compliance Administrator
  • Organization Management (broad access — use only if needed for initial validation)

7. Add the service principal to the selected role group:

Add-RoleGroupMember -Identity "Organization Management" -Member YourServiceID

# Example: Add-RoleGroupMember -Identity "Organization Management" -Member 1a4358f5-e27a-4354-8074-0fe335490ded

The application is configured.

Create an anti-spam policy in Microsoft 365 Defender

Prerequisites:

• You have administrative credentials to access Digital Risk Protection (Threat Command) with a subscription to the Automation and TIP modules.
• You have the Microsoft 365 Defender username and password.

Before you can integrate an Office 365 device with Digital Risk Protection (Threat Command), you need to create an anti-spam policy. This policy is where IOCs are displayed after the integration is running.

To create an anti-spam policy in Microsoft 365 Defender:

1. From Microsoft 365 Defender, go to Email & collaboration > Policies & rules > Threat Policies > Anti-spam.
2. Create a new Inbound policy. The name that you enter will be the name that you use in Digital Risk Protection (Threat Command). In our example, we used the name “Intsights.”
3. Configure settings according to your company policy. These settings include users, groups, domains, spam policies, actions, and more.

The new anti-spam policy is displayed.

Add an Office 365 cloud device to Digital Risk Protection (Threat Command)

Create an Office 365 cloud device in Digital Risk Protection (Threat Command).

To add an Office 365 device:

1. Log in to Digital Risk Protection (Threat Command) at https://dashboard.ti.insight.rapid7.com 
2. From the main menu, select Automation > Integrations.
3. From the Integrations page, click Cloud.
4. Click Add new device.
5. In the Add New Cloud Device  dialog, type a user-defined name for the device. The name can contain a maximum of 50 letters, spaces, numbers, and underscores.
6. For the Device type, select Office 365. The default device limit is displayed.
7. (Optional) You can change the IOCs limit.
8. Enter details about the Azure Directory app:
   1. Enter the PFX certificate file password you created .
   2. Enter the Application (client) ID.
   3. Enter the AD organization name.
   • Example: <tenantname>.onmicrosoft.com.
   4. In Spam Filter Identity, type the name of the anti-spam policy created in the previous procedure.
9. Upload the PFX certificate file.
10. It is recommended to click Test Credentials to ensure that the credentials are valid. If the credentials are not valid, a message is displayed.
11. Click Add.
12. (Optional) To verify that the new device is displayed in Digital Risk Protection (Threat Command), select Automation > Integrations. If this window is already open, refresh it by selecting Automation > Integrations from the menu.

The new device is added to the cloud integrations device list. Next to the device name, there is a red dot, indicating that communication has not yet been established. The dot will change to green when the device is synchronized. If the device cannot synchronize for more than 48 hours, an email warning is sent to the account administrator.

Configure an IOC group to push IOCs to the device

Once the Office 365 device has been added and is synching with Digital Risk Protection (Threat Command) , it is ready to receive IOCs that are pushed from Digital Risk Protection (Threat Command). IOCs are pushed by creating an IOC group for this device in Digital Risk Protection (Threat Command).

Viewing IOCs via Office 365

You can see pushed IOCs in Microsoft 365 Defender.

To view IOCs:

1. From Microsoft 365 Defender, choose Policies & rules > Threat Policies > Anti-spam policies.
2. Select the anti-spam policy created for Digital Risk Protection (Threat Command) IOCs.
   • The pushed IOCs are shown in the Blocked senders and Blocked domains sections.