Azure Integration Setup Guide

Complete guide for integrating Azure with CyberOptix.

Prerequisites

• Azure CLI installed (Installation Guide)
• Global Administrator or Privileged Role Administrator access to Microsoft Entra ID
• Owner or User Access Administrator role on Azure subscriptions

Part 1: Create Azure Service Principal

Step 1: Retrieve Management Group ID

Get your root-level Management Group ID. Learn more about Azure Management Groups.

Alternative: Use a Subscription ID if you prefer subscription-level scope instead of management group scope.

Step 2: Create Service Principal with Required Roles

# Set your Management Group ID
MG_ID="your-management-group-id"

# Login to Azure
az login

# Create Service Principal with Reader role
SP_OUTPUT=$(az ad sp create-for-rbac \
  -n 'CyberOptix Integration' \
  --role reader \
  --scopes "/providers/Microsoft.Management/managementGroups/${MG_ID}" \
  --output json)

# Display credentials
echo $SP_OUTPUT | jq

# Extract Client ID
APP_ID=$(echo $SP_OUTPUT | jq -r '.appId')

# Add Storage Blob Data Reader role
az role assignment create \
  --assignee $APP_ID \
  --role "Storage Blob Data Reader" \
  --scope "/providers/Microsoft.Management/managementGroups/${MG_ID}"

For subscription-level access, replace the scope:

--scopes "/subscriptions/{subscription-id}"

Step 3: Save Service Principal Credentials

From the output, save these values securely:

Warning: The Client Secret is only displayed once. Store it securely.

Step 4: Verify Role Assignments

az role assignment list \
  --assignee $APP_ID \
  --scope "/providers/Microsoft.Management/managementGroups/${MG_ID}" \
  --output table

Confirm both Reader and Storage Blob Data Reader roles are listed.

Part 2: Configure Microsoft Graph API Permissions

Required for Microsoft Entra ID, Microsoft 365 log collection, and Intune.

Step 1: Open App Registration

1. Navigate to Azure Portal → Microsoft Entra ID → App registrations
2. Search for and select CyberOptix Integration

Step 2: Add Microsoft Graph Permissions

1. Select API permissions → + Add a permission
2. Choose Microsoft Graph → Application permissions
3. Add these permissions:

Audit & Security Logs:

• AuditLog.Read.All
• IdentityRiskEvent.Read.All
• SecurityAlert.Read.All

Entra ID Entity Sync:

• User.Read.All
• Group.Read.All
• Application.Read.All
• RoleManagement.Read.Directory
• Policy.Read.ConditionalAccess

Intune Audit Logs:

• DeviceManagementApps.Read.All

4. Click Add permissions

Step 3: Grant Admin Consent

1. Click Grant admin consent for [Your Organization]
2. Click Yes to confirm

Critical: Without admin consent, log collection and entity sync will not function.

Step 4: Verify Permissions

Confirm all permissions show Granted status with a green checkmark in the Status column.

Part 3: Configure Microsoft Defender for Endpoint API Permissions

Required for Defender for Endpoint (EDR) device and vulnerability sync.

Step 1: Add Defender API Permissions

1. In App registrations → CyberOptix Integration → API permissions
2. Click + Add a permission → APIs my organization uses
3. Search for WindowsDefenderATP and select it
4. Choose Application permissions
5. Add these permissions:
   • Machine.Read.All
   • Vulnerability.Read.All
   • Software.Read.All
   • SecurityRecommendation.Read.All
6. Click Add permissions
7. Click Grant admin consent for [Your Organization]

Note: Microsoft Defender for Endpoint requires a Defender for Endpoint Plan 2 or Microsoft 365 E5 license.

Part 4: Configure Office 365 Management API Permissions

Required for M365 Management Activity log collection (Exchange, SharePoint, and Teams audit logs).

Step 1: Add Office 365 Management API Permissions

1. In App registrations → CyberOptix Integration → API permissions
2. Click + Add a permission → APIs my organization uses
3. Search for Office 365 Management APIs and select it
4. Choose Application permissions
5. Add this permission:
   • ActivityFeed.Read
6. Click Add permissions
7. Click Grant admin consent for [Your Organization]

Note: M365 Management Activity covers Exchange, SharePoint, and Teams audit events. DLP content types require E5 licensing and are not collected by default.

Part 5: Configure Power Platform API Permissions

Required for Power Platform environment, app, connector, connection, DLP policy, and Power Automate flow discovery.

Step 1: Assign Power Platform Administrator Role

The service principal must have the Power Platform Administrator role in Microsoft Entra ID. This role grants admin-level access to the Power Platform admin APIs — no granular API permissions are needed in the app registration.

1. Navigate to Azure Portal → Microsoft Entra ID → Roles and administrators
2. Search for Power Platform Administrator and select it
3. Click + Add assignments
4. Search for CyberOptix Integration (the service principal)
5. Select it and click Next → Assign

Note: Alternatively, the Dynamics 365 Administrator role also grants the necessary access.

Step 2: Add Power Apps Admin API Permission

Some tenants require an explicit API permission entry for the Power Platform admin scope:

1. In App registrations → CyberOptix Integration → API permissions
2. Click + Add a permission → APIs my organization uses
3. Search for Power Platform API (or PowerApps Service) and select it
4. Choose Application permissions → Check User (or available admin scopes)
5. Click Add permissions
6. Click Grant admin consent for [Your Organization]

Step 3: Verify Access

After role assignment, the service principal will have access to:

• Power Platform Admin API (api.powerplatform.com) — environments, apps, app permissions, custom connectors, connections, DLP policies
• Flow Service API (service.flow.microsoft.com) — Power Automate flow inventory and details

Note: Power Automate flow discovery uses a separate token scope (service.flow.microsoft.com/.default). If the Flow Service token cannot be acquired, CyberOptix will still discover all other Power Platform entities and log a warning.

Part 6: Configure Azure DevOps Access

Required only if using the DevSecOps module.

Step 1: Add Azure DevOps API Permission

1. In App registrations → CyberOptix Integration → API permissions
2. Click + Add a permission → Azure DevOps
3. Select Delegated permissions → Check user_impersonation
4. Click Add permissions
5. Click Grant admin consent for [Your Organization]

Step 2: Add Service Principal to Azure DevOps

1. Navigate to https://dev.azure.com/{your-organization}
2. Click Organization Settings (bottom left) → Users → Add users
3. Enter the Service Principal Client ID from Part 1, Step 3
4. Set Access level to Basic
5. Click Add

Step 3: Grant Project Access

Option A - Specific Projects:

1. Go to Organization Settings → Projects
2. Select a project → Permissions tab
3. Add the Service Principal to the Readers group
4. Repeat for each project

Option B - All Projects:

1. Go to Organization Settings → Permissions
2. Add the Service Principal to the Project Collection Readers group

Part 7: Add Integration to CyberOptix

Step 1: Navigate to Integrations

1. Log in to CyberOptix
2. Navigate to Integrations → Available Integrations

Step 2: Create Azure Integration

1. Select Azure as the integration type
2. Choose Cloud as the integration mode

3. Enter the credentials from Part 1, Step 3:
   • Client ID: The appId value
   • Client Secret: The password value
   • Tenant ID: The tenant value
4. Click Submit

Step 3: Verify Integration

The integration will appear in your Active Integrations list. CyberOptix will begin discovering Azure resources within a few minutes.

Permission Summary

Azure RBAC Roles

Microsoft Graph API Permissions

Microsoft Defender for Endpoint API Permissions

Office 365 Management API Permissions

Power Platform Permissions

Azure DevOps Permissions

Data Collection Overview

CyberOptix performs read-only operations on the following resources:

Azure Infrastructure:

• Virtual machines, networks, subnets, NICs, public IPs
• Storage accounts, blob containers, blobs
• Load balancers, application gateways, Azure Firewalls
• Databases (SQL, CosmosDB, PostgreSQL, MySQL)
• Container instances, AKS clusters
• App Services, Front Door CDN

Azure Activity Logs:

• Subscription-level control plane operations (resource create, update, delete)
• Administrative actions, service health events, and policy evaluations
• Autoscale events and security recommendations

Microsoft Entra ID:

• User sign-in and provisioning logs
• Directory audit logs
• Identity Protection risk detections
• User, group, and membership inventory
• App registrations and service principals
• Conditional Access policies
• Directory roles and role assignments

Microsoft 365:

• Defender security alerts
• Exchange audit events (mailbox access, admin changes, mail flow)
• SharePoint audit events (file access, sharing, site changes)
• Teams audit events (channel management, meeting events)

Microsoft Defender for Endpoint:

• Managed device inventory (OS, health, risk level, exposure)
• Endpoint vulnerabilities (CVE mappings per device)
• Software inventory across managed devices
• Security recommendations and remediation status

Power Platform:

• Environment inventory (type, region, lifecycle status)
• Power Apps inventory (creator, sharing, connection references per environment)
• App role assignments for broadly shared apps
• Custom connector inventory (endpoints, authentication types)
• Connection inventory (credential instances, status, creator, API bindings)
• Data Loss Prevention (DLP) policies
• Power Automate flow inventory (triggers, actions, connection references, state)

Microsoft Intune:

• Device management audit events (compliance changes, app deployments)
• Configuration profile updates and policy changes
• Administrative actions and role-based access changes

Azure DevOps:

• Projects, Git repositories, branches

Additional Resources

• Azure Service Principal Documentation
• Microsoft Graph Permissions Reference
• Microsoft Defender for Endpoint API Documentation
• Office 365 Management Activity API Reference
• Power Platform Admin API Reference
• Power Automate Management API Reference
• Microsoft Intune API Documentation
• Azure DevOps Security Best Practices