# Microsoft Defender for Cloud Apps Integration

Connect Microsoft Defender for Cloud Apps to Capsule Security to discover which generative AI apps your users reach, and what they do in them.

## Overview

Capsule reads two sources from Defender for Cloud Apps through Microsoft Graph:

- **Cloud Discovery** - the AI apps (generative AI, AI model providers, MCP servers and AI client apps) seen in your discovery streams over the last 30 days, with the users who used each one, the app's risk score and its sanctioned or unsanctioned tag.
- **App activity** - `CloudAppEvents` from Advanced Hunting for those apps, such as uploads and other actions recorded by app connectors and session control.


Each app becomes one inventory entry per user, so you can see who uses an unsanctioned AI app. Capsule connects via an approved Microsoft Entra ID application with read-only permissions.

## Prerequisites

Before you begin, ensure you have:

- **Microsoft Defender for Cloud Apps** licensed and deployed in Microsoft Defender XDR
- At least one **Cloud Discovery** source: the Defender for Endpoint integration, a log collector, or uploaded firewall or proxy logs
- A **Microsoft Entra ID** account with **Global Administrator** or **Privileged Role Administrator** role (Microsoft Graph application permissions can't be consented by an Application Administrator)
- A **Capsule Security** account with admin access


App activity only covers apps that Defender for Cloud Apps has events for - apps connected through an app connector, or accessed through Conditional Access App Control session control.

## Step 1: Configure the Integration in Capsule

1. Log in to the **Capsule Security** portal
2. Click **Integrations** in the left sidebar
3. Find the **Microsoft Defender for Cloud Apps** card and click **Set up Integration**
4. Click **Connect with Microsoft**
5. You'll be redirected to Microsoft's sign-in page


## Step 2: Grant Admin Consent

1. Sign in with a Microsoft Entra ID account that has the required administrator role (see Prerequisites)
2. Review the permissions requested by the Capsule application
3. Click **Accept** to grant admin consent for your organization


### Permissions

The Capsule application requests the following **application-level** permissions on **Microsoft Graph**. Both are read-only.

| Permission | Type | Description |
|  --- | --- | --- |
| `CloudApp-Discovery.Read.All` | Application | Read discovered cloud apps and the users of each app |
| `ThreatHunting.Read.All` | Application | Run Advanced Hunting queries to read `CloudAppEvents` |


## After Setup

- Discovery runs on a recurring schedule; the first sync may take several minutes
- View discovered AI apps in **Inventory**, shown as the AI product "via Microsoft Defender for Cloud Apps"
- Apps that stop appearing in the 30-day Cloud Discovery window are removed from the inventory


## Troubleshooting

1. **Consent failed or permissions error**
  - Verify your account has **Global Administrator** or **Privileged Role Administrator** role
  - Confirm both permissions show as granted on the Capsule enterprise application in Microsoft Entra ID
2. **No apps discovered**
  - Confirm Cloud Discovery has data in the Defender portal under **Cloud apps > Cloud discovery**
  - Check that the discovered apps include generative AI apps
3. **Apps appear without users**
  - Streams with user data anonymization turned on don't expose usernames, so their apps appear once, without an owner
  - Streams built from logs that carry only IP addresses have the same limitation
4. **No app activity**
  - Activity requires an app connector or session control for the AI app; Cloud Discovery alone doesn't produce events


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your organization ID, Entra tenant ID, and any error messages


## References

- [Work with discovered apps via Graph API](https://learn.microsoft.com/en-us/defender-cloud-apps/discovered-apps-api-graph)
- [runHuntingQuery API](https://learn.microsoft.com/en-us/graph/api/security-security-runhuntingquery)
- [CloudAppEvents table](https://learn.microsoft.com/en-us/defender-xdr/advanced-hunting-cloudappevents-table)
- [Grant tenant-wide admin consent](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent)