BEC Setup Guide
Step-by-step guide to register an Azure AD application, grant the required permissions, and connect dfir-cli to your Microsoft 365 tenant for BEC investigation.
Prerequisites
- A Microsoft 365 tenant (Business Basic or higher)
- Global Administrator or Application Administrator role
- A DFIR Platform subscription (Starter, Professional, or Enterprise)
- dfir-cli installed via
brew install dfir-lab/tap/dfir-cli
Register an App in Microsoft Entra ID
Open the Azure Portal and navigate to App registrations → New registration.
- Name:
DFIR CLI Investigation - Supported account types: Single tenant (this organization only)
- Redirect URI: Leave blank (not required)
After registration, copy the Application (client) ID and Directory (tenant) ID from the overview page. You will need both in Step 5.
Enable Public Client Flows
In the app registration, go to Authentication → Advanced settings and set Allow public client flows to Yes.
This enables the device code flow used by dfir-cli bec connect. If you prefer client credentials (service principal), you can skip this step and use --auth-flow client_credentials instead.
Add API Permissions
Navigate to API permissions → Add a permission → Microsoft Graph → Application permissions and add the following:
| Permission | Purpose | Required by |
|---|---|---|
| MailboxSettings.Read | Read inbox rules | inbox-rules, forwarding-audit |
| User.Read.All | Enumerate users | lookalike |
| AuditLog.Read.All | Read sign-in / audit logs | signin-audit, timeline |
| Directory.Read.All | Read directory data | signin-audit, oauth-audit |
| Application.Read.All | Audit OAuth grants | oauth-audit |
| Organization.Read.All | Read org info | forwarding-audit |
Grant Admin Consent
Still on the API permissions page, click Grant admin consent for [Your Organization] and confirm. Each permission should show a green checkmark in the Status column.
Admin consent is required because the permissions are application-level. Without it, API calls will return 403 Forbidden.
Connect dfir-cli
Run the connect command with the IDs you copied in Step 1. This launches a device-code flow that opens your browser for authentication.
Device Code Flow (interactive)
dfir-cli bec connect --tenant-id YOUR_TENANT_ID --client-id YOUR_CLIENT_ID
Client Credentials (non-interactive)
dfir-cli bec connect --tenant-id YOUR_TENANT_ID --client-id YOUR_CLIENT_ID --auth-flow client_credentials --client-secret YOUR_SECRET
Tokens are stored locally in an encrypted keychain. Run dfir-cli bec status at any time to check your connection.
Verify Connection
Confirm that dfir-cli can reach Microsoft Graph and that all permissions are active:
dfir-cli bec status
You should see a green Connected status along with the tenant name and a list of granted permissions. If any permission shows as missing, revisit Steps 3 and 4.