The Microsoft 365 Special Agent can be integrated into Checkmk 2.3 or newer.
You can download the .mkp file from releases in this repository to upload it directly to your Checkmk site.
The Plugin provides monitoring of these components:
- Microsoft 365 Group-Based Licensing
- Microsoft 365 Licenses
- Microsoft 365 Service Health
This Special Agent uses the Microsoft Graph API to collect the monitoring data. To access the API, you need a Microsoft Entra Tenant and a Microsoft Entra App Registration with a secret. For a configuration guide, see the "Steps to get it working" section.
You need at least these API application permissions for your App Registration to use all the checks:
- GroupMember.Read.All
- Organization.Read.All
- ServiceHealth.Read.All
For a more granular option, the required API permissions per check are listed in the next sections.
To implement the check, you need to configure the Microsoft 365 Special Agent in Checkmk. You will need the Microsoft Entra Tenant ID, the Microsoft Entra App Registration ID and Secret. When you configure the Special Agent, you have the option to select only the services that you want to monitor. You do not have to implement all the checks, but at least one of them.
This check monitors the Microsoft group-based licensing errors from a Microsoft 365 tenant. It will show the count of groups with license assignment errors.
No parameters
API permissions: At least GroupMember.Read.All (Application permission)
Endpoint: https://graph.microsoft.com/v1.0/groups
This check monitors all the Microsoft 365 licenses available in your Microsoft 365 Tenant. Only licenses with a capabilityStatus of "warning" or "enabled" are displayed.
| State | Description |
|---|---|
| Enabled | The count of units that are currently active for the service SKU subscription. |
| lockedOut | The count of units that are inaccessible due to the customer canceling their service SKU subscription. |
| suspended | The count of units that are on hold because the service SKU subscription was canceled. These units cannot be assigned but can be reactivated before deletion. |
| warning | The count of units in a warning state. After the service SKU subscription expires, the customer has a grace period to renew before it is canceled and moved to a suspended state. |
- Licenses lower levels: Set lower-level thresholds for the number of remaining available app licenses as absolute or percentage values. To ignore the remaining available licenses, Select "Percentage" or "Absolute" and "No levels".
API permissions: At least Organization.Read.All (Application permission)
Endpoint: https://graph.microsoft.com/v1.0/subscribedSkus
This check monitors the service health status from a Microsoft 365 Tenant. Only licensed services are displayed.
The check uses the SKU name as the service name. To find the corresponding product name, go to https://learn.microsoft.com/en-us/entra/identity/users/licensing-service-plan-reference
- Severity level incident: Set the severity level of the issue type incident. The default severity level is critical.
- Severity level advisory: Set the severity level of the issue type advisory. The default severity level is warning.
API permissions: At least ServiceHealth.Read.All (Application permission)
Endpoint: https://graph.microsoft.com/v1.0/admin/serviceAnnouncement/healthOverviews
- Get all licensed services from the Microsoft 365 Tenant.
Endpoint: https://graph.microsoft.com/v1.0/admin/serviceAnnouncement/issues
- Get all active Microsoft 365 health issues
To use this Checkmk Special Agent, you must configure a Microsoft Entra Application to access the Microsoft Graph API endpoints. You must also have a host in Checkmk and configure the Special Agent rule for the host.
- Sign in to the Microsoft Entra Admin Center (https://entra.microsoft.com) as a Global Administrator (at least a Privileged Role Administrator)
- Browse to Identity > Applications > App registrations
- Select New registration
- Provide a meaningful name (e.g. "Checkmk Special Agent")
- Select Accounts in this organizational directory only
- Do not specify a Redirect URI
- Click Register
Note
In the overview of your new application registration you will find the Application (client) ID and the Directory (tenant) ID. You will need this information later for the configuration of the Checkmk Special Agent.
- Go to API permissions
- Click Add a permission > Microsoft Graph > Application permissions
- Add all API permissions for all services that you want to monitor (see sections above)
- Select Grant admin consent > Yes
- Go to Certificates & secrets and click on New client secret
- Insert a description (e.g. the Checkmk Site name) and select an expiration period for the secret
- Log in to your Checkmk Site
- Browse to Setup > Passwords
- Select Add password
- Specify a Unique ID and a Ttile
- Copy the generated secret from the Microsoft Entra Admin Center to the Password field
- Click Save
- Add a new host in Setup > Hosts
- Configure your custom settings and set
- IP address family: No IP
- Checkmk agent / API integrations: API integrations if configured, else Checkmk agent
- Save
- Navigate to the Special Agent rule Setup > Microsoft 365 (use the search bar)
- Add a new rule and configure the required settings
- Application (client) ID and Directory (tenant) ID from the Microsoft Entra Application
- For Client secret select From password store and the password from Add a New Password
- Select all services that you want to monitor
- Add the newly created host in Explicit hosts
- Save and go to your new host and discover your new services
- Activate the changes