Skip to content

Commit 2ba21da

Browse files
CLiX-1CLiX-1
authored
Update README.md
1 parent fe410ef commit 2ba21da

File tree

1 file changed

+58
-37
lines changed

1 file changed

+58
-37
lines changed

‎README.md‎

Lines changed: 58 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,46 @@
11
# Checkmk Plugin: Microsoft Entra Special Agent
22

3-
## Plugin Information
4-
The Microsoft Entra Special Agent can be integrated into Checkmk 2.3 or newer.
3+
The **Microsoft Entra** Special Agent is an extension for the monitoring software **Checkmk**.
4+
It can be integrated into Checkmk 2.3 or newer.
5+
6+
You can download the extension package as an `.mkp` file from the [releases](../../releases) in this repository and upload it directly to your Checkmk site.
7+
See the Checkmk [documentation](https://docs.checkmk.com/latest/en/mkps.html) for details.
58

6-
You can download the .mkp file from releases in this repository to upload it directly to your Checkmk site.
9+
## Plugin Information
710

8-
The Plugin provides monitoring of these components:
11+
The Plugin provides monitoring for the following components:
912
- Microsoft Entra App Registration Credentials
1013
- Microsoft Entra CA VPN Certificate
1114
- Microsoft Entra Connect/Cloud Sync
1215
- Microsoft Entra SAML Certificates
1316

17+
See [Check Details](#check-details) for more information.
18+
1419
## Prerequisites
1520

16-
This Special Agent uses the Microsoft Graph API to collect the monitoring data.
17-
To access the API, you need a Microsoft Entra Tenant and a Microsoft Entra App Registration with a secret.
21+
This Special Agent uses the Microsoft Graph API to collect the monitoring data.
22+
To access the API, you need a Microsoft Entra tenant and a Microsoft Entra app registration with a client secret ([Steps to Get It Working](#steps-to-get-it-working)).
1823

19-
You need at least these API **application** permissions for your App Registration to use all the checks:
24+
You need at least the following API **application** permissions for your app registration to use all the checks:
2025
- *Application.Read.All*
2126
- *Organization.Read.All*
2227

23-
For a more granular option, the required API permissions per check are listed in the next sections.
28+
For a more granular options, the required API permissions per check are listed in the next sections.
2429

25-
To implement the check, you need to configure the *Microsoft Entra* Special Agent in Checkmk.
26-
You will need the Microsoft Entra Tenant ID, the Microsoft Entra App Registration ID and Secret.
30+
To activate the checks, you must configure the **Microsoft Entra** Special Agent in Checkmk.
31+
You will need the Microsoft Entra tenant ID, the App ID and the client secret from the Microsoft Entra app registration.
2732
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.
2833

34+
> [!NOTE]
35+
> This plugin uses HTTPS connections to Microsoft.
36+
>Make sure you have enabled **Trust system-wide configured CAs** or uploaded the CA certificates for the Microsoft domains in Checkmk.
37+
>You can find these options in **Setup** > **Global settings** > **Trusted certificate authorities for SSL** under **Site management**.
38+
>If your system does not trust the certificate you will encounter the error: `certificate verify failed: unable to get local issuer certificate`.
39+
>
40+
>Also do not block the communications to:
41+
>- https://login.microsoftonline.com
42+
>- https://graph.microsoft.com
43+
2944
## Check Details
3045

3146
### Microsoft Entra App Registration Credentials
@@ -40,15 +55,17 @@ This check monitors the expiration time of secrets and certificates from Entra a
4055

4156
#### Checkmk Parameters
4257

43-
1. **Credential Expiration**: Specify the lower levels for the Microsoft Entra app credential expiration time. The default values are 14 days (WARN) and 5 days (CRIT). To ignore the credential expiration, select 'No levels'.
58+
1. **Credential Expiration**: Specify the lower levels for the Microsoft Entra app credential expiration time. The default values are 14 days (WARN) and 5 days (CRIT). To ignore the credential expiration, select "No levels".
4459
2. **Exclude Credentials**: Specify a list of credential descriptions that you do not want to monitor.
4560

4661
#### Microsoft Graph API
4762

4863
**API Permissions**: At least *Application.Read.All* (Application permission)
4964

50-
**Endpoint**: *https://graph.microsoft.com/v1.0/applications*
51-
<br><br>
65+
**Endpoint**: `https://graph.microsoft.com/v1.0/applications`
66+
67+
---
68+
5269
### Microsoft Entra CA VPN Certificates
5370

5471
#### Description
@@ -61,14 +78,16 @@ This check monitors the expiration time of the Entra Conditional Access VPN cert
6178

6279
#### Checkmk Parameters
6380

64-
1. **Certificate Expiration**: Specify the lower levels for the Microsoft Entra Conditional Access VPN certificate expiration time. The default values are 14 days (WARN) and 5 days (CRIT). To ignore the certificate expiration, select 'No levels'.
81+
1. **Certificate Expiration**: Specify the lower levels for the Microsoft Entra Conditional Access VPN certificate expiration time. The default values are 14 days (WARN) and 5 days (CRIT). To ignore the certificate expiration, select "No levels".
6582

6683
#### Microsoft Graph API
6784

6885
**API Permissions**: At least *Application.Read.All* (Application permission)
6986

70-
**Endpoint**: *https://graph.microsoft.com/v1.0/servicePrincipals*
71-
<br><br>
87+
**Endpoint**: `https://graph.microsoft.com/v1.0/servicePrincipals`
88+
89+
---
90+
7291
### Microsoft Entra Connect/Cloud Sync
7392

7493
#### Description
@@ -81,14 +100,16 @@ This check monitors the time since the last Entra Connect/Cloud Sync synchronisa
81100

82101
#### Checkmk Parameters
83102

84-
1. **Time since last sync**: Specify the upper levels for the last sync time from Microsoft Entra Connect/Cloud Sync. The default values are 1 hour (WARN) and 3 hours (CRIT). To ignore the last sync time, select 'No levels'.
103+
1. **Time Since Last Sync**: Specify the upper levels for the last sync time from Microsoft Entra Connect/Cloud Sync. The default values are 1 hour (WARN) and 3 hours (CRIT). To ignore the last sync time, select "No levels".
85104

86105
#### Microsoft Graph API
87106

88107
**API Permissions**: At least *Organization.Read.All* (Application permission)
89108

90-
**Endpoint**: *https://graph.microsoft.com/v1.0/organization/{organizationId}*
91-
<br><br>
109+
**Endpoint**: `https://graph.microsoft.com/v1.0/organization/{organizationId}`
110+
111+
---
112+
92113
### Microsoft Entra SAML Certificates
93114

94115
#### Description
@@ -101,23 +122,23 @@ This check monitors the expiration time of certificates from Entra enterprise ap
101122

102123
#### Checkmk Parameters
103124

104-
1. **Certificate expiration**: Specify the lower levels for the Microsoft Entra SAML app certificate expiration time. The default values are 14 days (WARN) and 5 days (CRIT). To ignore the certificate expiration, select 'No levels'.
125+
1. **Certificate Expiration**: Specify the lower levels for the Microsoft Entra SAML app certificate expiration time. The default values are 14 days (WARN) and 5 days (CRIT). To ignore the certificate expiration, select "No levels".
105126

106127
#### Microsoft Graph API
107128

108-
**API Permissions**: At least *Application.Read.All* (Application permission)
129+
**API Permissions**: At least *Application.Read.All* (Application permission)
109130

110-
**Endpoint**: *https://graph.microsoft.com/beta/servicePrincipals*
131+
**Endpoint**: `https://graph.microsoft.com/beta/servicePrincipals`
111132

112-
## Steps to get it working
133+
## Steps to Get It Working
113134

114-
To use this Checkmk Special Agent, you must configure a Microsoft Entra Application to access the Microsoft Graph API endpoints.
135+
To use this Checkmk Special Agent, you must configure a Microsoft Entra application to access the Microsoft Graph API endpoints.
115136
You must also have a host in Checkmk and configure the Special Agent rule for the host.
116137

117138
### Microsoft Entra Configuration
118139
#### Register an Application
119140

120-
1. Sign in to the Microsoft Entra Admin Center (https://entra.microsoft.com) as a Global Administrator (at least a Privileged Role Administrator)
141+
1. Sign in to the Microsoft Entra Admin Center (https://entra.microsoft.com) as a Global Administrator (or at least a Privileged Role Administrator)
121142
2. Browse to **Identity** > **Applications** > **App registrations**
122143
3. Select **New registration**
123144
4. Provide a meaningful name (e.g. "Checkmk Special Agent")
@@ -126,44 +147,44 @@ You must also have a host in Checkmk and configure the Special Agent rule for th
126147
7. Click **Register**
127148

128149
> [!NOTE]
129-
> In the overview of your new application registration you will find the **Application (client) ID** and the **Directory (tenant) ID**.
150+
> In the overview of your new application registration, you will find the **Application (client) ID** and the **Directory (tenant) ID**.
130151
> You will need this information later for the configuration of the Checkmk Special Agent.
131152
132153
#### Configure the Application
133154
1. Go to **API permissions**
134155
2. Click **Add a permission** > **Microsoft Graph** > **Application permissions**
135156
3. Add all API permissions for all services that you want to monitor (see sections above)
136157
4. Select **Grant admin consent** > **Yes**
137-
5. Go to **Certificates & secrets** and click on **New client secret**
138-
6. Insert a description (e.g. the Checkmk Site name) and select an expiration period for the secret
158+
5. Go to **Certificates & secrets** and click **New client secret**
159+
6. Enter a description (e.g. the Checkmk Site name) and select an expiration period for the secret
139160

140161
### Checkmk Special Agent Configuration
141162

142-
1. Log in to your Checkmk Site
143-
163+
1. Log in to your Checkmk site
164+
144165
#### Add a New Password
145166

146167
1. Browse to **Setup** > **Passwords**
147168
2. Select **Add password**
148-
3. Specify a **Unique ID** and a **Ttile**
169+
3. Specify a **Unique ID** and a **Title**
149170
4. Copy the generated secret from the Microsoft Entra Admin Center to the **Password** field
150171
5. Click **Save**
151172

152173
#### Add Checkmk Host
153174

154175
1. Add a new host in **Setup** > **Hosts**
155176
2. Configure your custom settings and set
156-
- **IP address family**: No IP
157-
- **Checkmk agent / API integrations**: API integrations if configured, else Checkmk agent
177+
- **IP address family**: No IP
178+
- **Checkmk agent / API integrations**: API integrations if configured, else Checkmk agent
158179
3. Save
159180

160181
#### Add Special Agent Rule
161182

162183
1. Navigate to the Special Agent rule **Setup** > **Microsoft Entra** (use the search bar)
163184
2. Add a new rule and configure the required settings
164-
- **Application (client) ID** and **Directory (tenant) ID** from the Microsoft Entra Application
165-
- For **Client secret** select **From password store** and the password from **Add a New Password**
166-
- Select all services that you want to monitor
167-
- Add the newly created host in **Explicit hosts**
185+
- **Application (client) ID** and **Directory (tenant) ID** from the Microsoft Entra Application
186+
- For **Client Secret** select **From password store** and the password from **Add a New Password**
187+
- Select all services that you want to monitor
188+
- Add the newly created host in **Explicit hosts**
168189
3. Save and go to your new host and discover your new services
169190
4. Activate the changes

0 commit comments

Comments
 (0)