Skip to main content
The user authorizing the Microsoft Defender connection must be able to grant tenant-wide admin consent. This integration uses the /adminconsent endpoint, which requires admin consent to authorize the application on behalf of the entire organization. Microsoft Defender APIs require application permissions that need admin consent to access organizational data across all users.
Important: Application registration only defines which permissions the application requires. A Microsoft Entra tenant administrator must explicitly grant these permissions by granting admin consent. This must be done per tenant and must be performed every time the application permissions are changed.
Privileged Role Administrator (Recommended)
  • Can grant consent for apps requesting any permission, for any API
  • No limitations on API types or permission scopes
  • Full admin consent capabilities
Cloud Application Administrator
  • Can grant consent for apps requesting any permission for any API
  • Limitation: Cannot grant consent for Microsoft Graph app roles (application permissions)
  • Can grant all Microsoft Defender API permissions (uses WindowsDefenderATP API, not Microsoft Graph)
Application Administrator
  • Can grant consent for apps requesting any permission for any API
  • Limitation: Cannot grant consent for Microsoft Graph app roles (application permissions)
  • Can grant all Microsoft Defender API permissions
Global Administrator
  • Can grant consent for any application
  • Has full access to all administrative features
  • Can grant admin consent without restrictions

​
Which Role to Use

Recommendation: Use a Privileged Role Administrator, Cloud Application Administrator, or Global Administrator account for the authorization in step 2. Since Microsoft Defender uses the WindowsDefenderATP API (not Microsoft Graph), the Cloud Application Administrator role has sufficient permissions.

​
Key Points

  • Admin consent is required to grant application permissions to Microsoft Defender APIs
  • The authorizing user must have one of the admin roles listed above
  • Permissions must be explicitly granted even after application registration
  • Admin consent must be re-granted if application permissions are changed

​
Microsoft Defender App

To integrate with Microsoft Defender, users will have to authorize Leen’s Microsoft Defender app, which is an OAuth2 app. This will allow Leen to access the appropriate Microsoft Defender resources in the organization’s account. Leen takes care of the OAuth2 code-flow and access token management, so you don’t have to worry about it.

​
Onboarding

Follow the steps below to onboard your environment to our Microsoft Defender app.
1

Create Microsoft Defender Connection

With your Leen API Key and your Customer’s Org ID, make a API request to create a new Microsoft Defender Connection. More information can be found on the API Reference page.
The response will look like this:
2

Granting permission to Leen app for Microsoft Defender

Open the oauth2_authorize_url from the previous step in a new tab. This will prompt the admin user to authorize Leen’s Microsoft Defender app to access their Microsoft Defender resources.Microsoft Defender-authOnce the user has authorized the app, they will be redirected to Leen on a successful authorization.Microsoft Defender-auth-success
3

Pull Data

Now that the user has authorized the app, you can pull data from Microsoft Defender using the connection_id from the first step. More information can be found on the API Reference page.