This guide walks you through setting up a Microsoft 365 integration using the Service Principal application authentication method.

Prerequisites

Before starting, ensure you have:

• Microsoft 365 global administrator access or appropriate Microsoft Entra ID permissions

• Access to Azure Portal (for Microsoft Entra ID)

• Your Microsoft 365 Tenant ID and primary domain

• Authority to grant admin consent for API permissions

Step-by-Step Setup Process

Step 1: Access the Microsoft 365 Integration Dialogue

Navigate to Integrations in the Swise menu and locate the Microsoft 365 integration. Click Connect to open the "Connect Microsoft 365" dialogue.

Step 2: Enter Tenant Information

In the Tenant Information tab (the first tab), enter your organisation's details:

• Tenant ID: Enter your Microsoft 365 Tenant ID (e.g., 328sjdd-shd64hsd-kds9833d-sd2kaift4...)

• Domain: Enter your primary domain (e.g., yourcompany.onmicrosoft.com or yourcompany.co.nz)

• Provider alias: (Optional) Enter a friendly name to identify this Microsoft 365 environment (e.g., "Production M365" or "Main Office 365")

Click Credentials → to proceed to the next step.

Step 3: Configure Service Principal Credentials

In the Credentials tab, you'll need to provide the Service Principal authentication details. Before proceeding, you must create a Service Principal in Microsoft Entra ID with the proper permissions.

Creating the Service Principal

You have two options to create the required Service Principal:

Option A: Using Azure Portal

1. Access Microsoft Entra ID in the Azure Portal

2. Navigate to App registrations in the left menu

3. Click + New registration to register a new application

4. Fill in the Name (e.g., "Swise M365 Integration"), select Supported account types (choose "Accounts in this organisational directory only"), and click Register

5. Once created, go to Certificates & secrets in the left menu

6. Click + New client secret

7. Fill in Description and Expires fields, then click Add

8. Important: Copy the secret value immediately - this will be your Client Secret

Option B: Using Azure CLI

Open a terminal and execute:

az ad sp create-for-rbac --name "swise-m365-service-principal"

Save the values from the output:

• appId → Client ID

• password → Client Secret

• tenant → Tenant ID

Entering Credentials

Once you have created the Service Principal, complete the credentials section:

• Client ID: Enter the Application (client) ID from your Service Principal (e.g., 8asd823h-adsj22jnw-ad23ee-345ja6u...)

• Client Secret: Enter the client secret value you copied (e.g., awe-3jss0dd-ad23ae-fwtdasa-sasf8ggs...)

• Tenant ID: This should auto-populate from Step 2

Click Permissions → to proceed.

Step 4: Assign Required Permissions

Before completing the integration, you must assign the proper permissions to your Service Principal. This involves Microsoft Graph API permissions and external service permissions.

Microsoft Graph API Permissions

Assign the following Microsoft Graph API permissions to your Service Principal:

• AuditLog.Read.All - Required for audit and compliance monitoring

• Directory.Read.All - Required for all identity and directory services

• Policy.Read.All - Required for policy and configuration checks

• SharePointTenantSettings.Read.All - Required for SharePoint service monitoring

• UserAuthenticationMethod.Read.All - Required for MFA and authentication checks

To assign via Azure Portal:

1. Navigate to your App registration → API permissions

2. Click + Add a permission → Microsoft Graph

3. Select Application permissions (not Delegated)

4. Search for and select the five permissions listed above

5. Click Add permissions

6. Important: Click Grant admin consent for [your organisation] to activate the permissions

External API Permissions

For comprehensive monitoring of Exchange, Teams, and Defender services:

Exchange Online Management

1. In API permissions, click + Add a permission

2. Select APIs my organisation uses and search for Office 365 Exchange Online

3. Add Exchange.ManageAsApp permission

4. Grant admin consent

Microsoft Teams

1. Click + Add a permission again

2. Select APIs my organisation uses and search for Skype and Teams Tenant Admin API

3. Add application_access permission

4. Grant admin consent

Assign Global Reader Role

Your Service Principal needs the Global Reader role:

1. In Microsoft Entra ID, go to Roles and administrators

2. Search for and select Global Reader

3. Click + Add assignments

4. Select your Swise M365 app and click Add

5. Confirm the assignment

💡 Note: The Global Reader role provides read-only access to all Microsoft 365 services and is required for comprehensive security monitoring.

Step 5: Select Compliance Standards

In the Compliance standards tab, choose which security frameworks to evaluate against:

• Your Security Compliance Project e.g. ISO 27001 (auto-selected if your Security Compliance project is set to ISO 27001)

• CIS Controls V8 (optional)

Check any additional standards you’d like to monitor. Each standard’s description appears below its checkbox. When ready, click Connect.Click Connect to finalise the setup.

Step 6: Swise will make the connection 🎉

After clicking Connect, the Swise system will:

• Authenticate with Microsoft 365 using your Service Principal credentials

• Verify the assigned permissions

• Activate monitoring for your Microsoft 365 tenant

Soon results from this monitoring will become available in the Cloud Security dashboard, which you can access by selecting Cloud Security from the Swise menu.

Troubleshooting

Common Issues

Authentication Failed

• Verify your Client ID, Client Secret, and Tenant ID are correct

• Ensure the client secret hasn't expired

• Check that admin consent has been granted for all API permissions

Insufficient Permissions

• Confirm all Microsoft Graph API permissions are assigned

• Verify external API permissions for Exchange and Teams are configured

• Check that the Global Reader role has been assigned to your Service Principal

• Ensure admin consent is granted for all permissions

Connection Timeout

• Ensure your Microsoft 365 tenant is active and accessible

• Verify network connectivity to Microsoft services

• Check if any conditional access policies are blocking the Service Principal