Manual Setup - Microsoft 365 (MS 365) Continuous Scanning

Prerequisites

Before you integrate Microsoft 365 with Mondoo, be sure you:

• Have a Mondoo account with Editor or Owner permissions for the space in which you want to add the integration.

• Have an Azure account with an active subscription and permission to manage applications in Microsoft Entra ID (formerly Active Directory). Any of these Microsoft Entra ID roles include the required permissions:

  • Global Administrator - Create and manage all aspects of app registrations and enterprise apps.

  • Application administrator - Create and manage all aspects of app registrations and enterprise apps.

  • Cloud application administrator - Create and manage all aspects of app registrations and enterprise apps except App Proxy.

• Are logged into Azure using the Azure CLI.

  • If you use the Azure Cloud Shell, you don't need to also log into the Azure CLI. To learn more, read the Quick start for Azure Cloud Shell.

  • If you use a Linux shell or macOS shell, log into the Azure CLI.

  If you're not already an Azure CLI user:

  1. Install the Azure CLI.

  2. Log into the Azure CLI from PowerShell or a Linux/macOS CLI by entering:

     
     az login --allow-no-subscriptions
     

     Azure opens your web browser and prompts you to log in. After you do so, you can return to the CLI.

Register an Azure app

Continuous scanning of Microsoft 365 requires a Microsoft Entra ID app registration in your Azure tenant. Registering Mondoo with Azure establishes a trust relationship between Mondoo and the Microsoft identity platform. The trust is unidirectional: Mondoo trusts the Microsoft identity platform, and not the other way around. The Azure app registration creates a service principal to represent Mondoo in any tenants and subscriptions in which it acts.### Manual app registration option

To configure your Azure resources, you must:

Step A: Register an app with Azure and create a service principal

Step B: Grant permissions to access Microsoft Graph (API permissions)

Step C: Assign the Global Reader role

Step D: Upload the application certificate

Step A: Register an app with Azure and create a service principal

Like any service that integrates with Azure, Mondoo must have an app registration. To learn more about creating a new app registration, read App registration, app objects, and service principals in the Azure documentation.

1. Log into the Azure portal as a global administrator, application administrator or cloud application administrator.

2. Find and select Microsoft Entra ID.

3. In the navigation sidebar, select App registrations.

4. Select + New registration.

5. Enter the application name mondoo-ms365 and select Accounts in this organizational directory only as the supported account type. Mondoo does not require an application redirect URI.

6. Select the Register button.

Microsoft creates the application ID and displays it in the application registration overview.

Keep this page open as you continue to the next step.

Step B: Grant permissions to access Microsoft Graph (API permissions)

1. In the navigation sidebar, select API permissions.

By default, Microsoft grants your new application User.Read permission for Microsoft Graph. It's not required for Mondoo, so you can remove it.

2. Select + Add a permission.

3. From the list of Commonly used Microsoft APIs, select Microsoft Graph.

4. Because Mondoo acts as a service, select Application permissions.

5. Select expand all to see all permissions. Then select the required API permissions:

Show or hide required API permissions.

Microsoft Graph	Type	Description
IdentityProvider.Read.All	Application	Read identity providers
Policy.Read.All	Application	Read your organization's policies
Policy.Read.ConditionalAccess	Application	Read your organization's conditional access policies
Policy.Read.PermissionGrant	Application	Read consent and permission grant policies
SecurityActions.Read.All	Application	Read your organization's security actions
SecurityEvents.Read.All	Application	Read your organization's security events
DeviceManagementConfiguration.Read.All	Application	Read Microsoft Intune device configuration and policies
AuditLog.Read.All	Application	Read all audit log data
Directory.Read.All	Application	Read directory data

6. Select the Add permissions button.

7. Grant Mondoo read permissions for SharePoint.

   SharePoint APIs	Type	Description
   Sites.FullControl.All	Application	Have full control of all site collections

8. Select the Add permissions button.

9. Grant Mondoo read permissions for Office 365 Exchange Online. You need to search in APIs my organization uses

   Office 365 Exchange Online	Type	Description
   Exchange.ManageAsApp	Application	Run Exchange Online commands as if Mondoo was an administrator account

10. To complete the process, select Grant admin consent for (your tenant name) and select the Yes button to confirm.

Step C: Assign the Global Reader role

1. In the Entra ID portal, go to Identity (Roles & admins).

2. Use the search box to find the Global Reader role. Select the name of the role (not the check box). The Assignments page opens.

3. Select + Add assignments.

4. Find and select the newly created app, mondoo-ms365.

5. Assign the mondoo-ms365 app the Global Reader role.

6. When you return to the Assignments page, select Refresh and verify that the mondoo-ms365 app has been assigned the Global Reader role.

Step D: Upload the application certificate

The app registration and your Mondoo integration must share a PEM (privacy-enhanced mail) certificate for secure authentication. The certificate must not be password protected.

Create a PEM certificate using the method approved by your organization's security team. You need two files:

• The file you upload to Azure must have only the certificate, not the private key.

• The file you upload to Mondoo Console (in the Add a new Azure integration in the Mondoo Console section below) must have both the private key and the certificate. It must have a .pem extension and must use this format and order of information:

-----BEGIN PRIVATE KEY-----
key goes here
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
certificate goes here
-----END CERTIFICATE-----

Generate a self-signed certificate for testing

For testing purposes only, you can use OpenSSL toolkit together with req to generate a certificate. Run this command in Linux shell, macOS shell, or Azure Cloud shell (bash):

openssl req -newkey rsa:4096  -x509  -sha512  -days 365 -nodes -out certificate.pem -keyout privatekey.key

Add the private key to the beginning of the PEM file:

cat privatekey.key certificate.pem > certificate.combo.pem

tip

Here is a simple installation of OpenSSL for Microsoft Windows.

Upload the certificate to Azure:

1. From the Azure portal home, select Microsoft Entra ID.

2. In the navigation sidebar, select App registrations.

3. Select the app you created.

4. In the sidebar under the app name, select Certificate & secrets.

5. Select Certificates and then select Upload certificate.

6. Select the PEM certificate and enter a description, such as Mondoo certificate.

info

Be sure to choose the file containing only the certificate, not the private key.

7. Select the Add button.

Add a new Microsoft 365 integration in the Mondoo Console

After you've created and granted permissions to a new app registration, you can create a Mondoo Microsoft 365 integration. You need some values from the app registration you created in the instructions above.

1. Access the Integrations > Add > Microsoft 365 page in one of two ways:

   • New space setup: After creating a new Mondoo account or creating a new space, the initial setup guide welcomes you. Select BROWSE INTEGRATIONS and then select Microsoft 365.

     

   • INTEGRATIONS page: In the side navigation bar, under INTEGRATIONS, select Add New Integration. Under Cloud Security, select Microsoft 365.

     

2. In the Choose an integration name box, enter a name for the integration. Make it a name that lets you easily recognize the Microsoft 365 tenant.

3. In the Enter the application (client) ID box, enter the value from the app registration's Application (client) ID box.

4. In the Enter the directory (tenant) ID box, enter the value from the app registration's Directory (tenant) ID box.

5. Specify the subscriptions for Mondoo to continuously scan.

   • To continuously scan all subscriptions in the tenant, leave the Scan all subscriptions connected to the directory (tenant) ID toggle enabled.

   • To choose the subscriptions to scan, disable the Scan all subscriptions connected to the directory (tenant) ID toggle, select Allow list and enter the subscription ID to scan.

   • To scan all subscriptions except those you specify, disable the Scan all subscriptions connected to the directory (tenant) ID toggle, select Deny list and enter the names of the subscriptions you don't want Mondoo to scan.

6. Provide a certificate (a PEM (privacy-enhanced mail) file) for Mondoo to securely authenticate with the app (service principal) you created.

The certificate file must have the .pem extension and must contain both the private key and the certificate in this order:

-----BEGIN PRIVATE KEY-----
key goes here
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
certificate goes here
-----END CERTIFICATE-----

Upload the certificate to Mondoo: In the Drag and drop your .pem file here box, select the cloud icon and choose the file to upload.

7. To complete the integration, select the START SCANNING button.

8. On the Recommended Policies page, enable the policies on which you want to base assessments of your ms365 environment. To learn more, read Manage Policies.

Mondoo begins scanning your Microsoft 365 resources. When it completes, you can see results on the INVENTORY page. To learn more, read Monitor Your Infrastructure Security.

Didn't get the expected results?

Read Test and Troubleshoot Microsoft 365 Configuration.

Next steps

• Learn more about Mondoo

• Integrate Mondoo with other cloud platforms in your infrastructure