Configure Connection
Microsoft Defender XDR guide
Prepare an Entra application and certificate, configure NIM, and validate access to connected devices.
Before you beginDirect link to Before you begin
Follow Microsoft's Defender XDR API access documentation. NIM uses application access with certificate authentication, following the same general Entra application and certificate setup pattern used by other Microsoft integrations.
NIM requires Application ID, Organization, and Certificate.
The /machines test uses the Defender for Endpoint machine API. Follow Microsoft's app-only Defender for Endpoint setup for the corresponding API permissions.
Register the application and configure permissionsDirect link to Register the application and configure permissions
- In Microsoft Entra ID, open App registrations > New registration, name the application for NIM, and register it.
- Record the Application (client) ID and the tenant information for the organization you will connect.
- Open API permissions > Add a permission > APIs my organization uses, select WindowsDefenderATP, and choose Application permissions for the machine API.
- Add the permissions needed for your process. Microsoft's List machines API documentation lists Machine.Read.All for reading machine profiles; use the permissions documented for any additional management actions you intend to perform.
- Grant administrator consent for the configured application permissions.
Configure certificate authenticationDirect link to Configure certificate authentication
- Prepare a certificate for application authentication, following the certificate guidance linked from Microsoft's app-only setup documentation.
- In the Entra application, open Certificates & secrets > Certificates and upload the public certificate.
- Import the matching certificate with its private key into NIM.
Enter the connection settingsDirect link to Enter the connection settings
- In NIM Studio, open Systems > Overview and add a Microsoft Defender XDR system, or select the existing system.
- Open Connection, enter the following settings, and save.
| NIM setting | Value |
|---|---|
| Application ID | The Application (client) ID from the Entra application registration. |
| Organization | The Entra tenant or organization value for the environment, using the format expected by the Connection screen. |
| Certificate | The certificate imported into NIM. Its matching public certificate must be registered on the Entra application. |
Test machine retrievalDirect link to Test machine retrieval
-
Select Test Connection. NIM attempts to retrieve machines using:
GET /machines -
If the test fails, verify the Application ID, Organization, certificate validity and private key, API permissions, administrator consent, and network access.
-
Collect machine data and validate the results in NIM.
-
Validate intended device management actions with a test device before enabling automation.
The connection test checks machine retrieval. Validate each intended management action separately; successful read access does not confirm permission to change device information or perform other actions.