Azure Configurations

Microsoft Azure Integration – Step-by-Step Requirements

To integrate this project with Microsoft Azure, specific permissions must be granted to the application. This guide outlines how to grant these permissions using the Azure Portal, as well as an optional PowerShell script alternative.

Step 1: Register the Application in Azure AD (if not already registered)

• Sign in to the Azure Portal.

• Navigate to Microsoft Azure > App registrations.

App registrations

• Click New registration.

New Registration

• Provide a name for the app (e.g., My Azure Integration).

• Set Supported account types to Accounts in this organizational directory only (unless you require multi-tenant).

• Set a Redirect URI if needed (optional).

• Click Register.

Register

• After App Registration you must copy the Application (client) ID and Directory (tenant) ID

After App Registration

• Set up Azure Active Directory integration in the application for enterprise authentication and Microsoft 365 service access. Configure tenant credentials, client authentication, and API permissions. Please continue with Login With Client Secret. But we recommend to continue with Login With Certificate.

Step 2: Assign Required API Permissions

• Open the App Registration you just created.

API Permissions

• Go to API permissions > Click + Add a permission.

• Choose Microsoft Graph.

Microsoft Graph

• Select Application permissions.

Application permissions

• Add the following permissions:

  • Directory.Read.All

  • AuditLog.Read.All

  • Policy.Read.All

  • RoleManagement.Read.All

  • OnPremDirectorySynchronization.Read.All

• The following permission are required if you scan Teams and Sharepoints:

  • Teams Reader Role What is Teams Reader Role?

  • SharePointTenantSettings.Read.All

  • Sites.Read.All

  • Sharepoint.Sites.FullControl.All

• Click Add permissions.

Add Permissions

• To add Sharepoint.Sites.FullControl.All permission, select SharePoint instead of Microsoft Graph at Microsoft APIs tab and choose application permissions.

Sharepoint API Selection

• Type Sites.FullControl.All to find permission.

Add Permissions

• After adding, click Grant admin consent for [Your Tenant Name].

Grant admin consent

• Confirm the prompt to grant consent.

Grant admin consent confirmation

These permissions allow the integration to securely access directory, audit, policy, role, and hybrid sync data.

---

What is Teams Reader Role?

Teams Reader role lets users view Teams settings and information without being able to change anything.

Step 1: Search for Roles

Go to the Microsoft Entra admin center and type "roles" in the search box at the top.

Search roles

Click on Microsoft Entra roles and administrators from the Services section.

Step 2: Find Teams Reader Role

In the roles page, search for "teams" to find Teams-related roles.

Teams Reader Role

Look for Teams Reader role. The description says: "Read everything in the Teams admin center, but not update anything."

Step 3: Add Users or Groups

Click on the Teams Reader role, then go to Assignments and click Add assignments.

Team Reader Assignments

Search for the user, group, or application you want to give this role to. In this example, we searched for "forestall" and found the "forestall-collector" enterprise application.

Select the item from the search results and add it.

---

(Optional Step 1): Use PowerShell Script to Automate Permission Assignment

If you prefer to automate the process or deploy across multiple tenants, you can use the following PowerShell script (requires admin privileges and AzureAD or Microsoft Graph modules).

PowerShell Script: Assign Microsoft Graph Permissions to an App

Preconditions:

• You must be a Global Administrator

• The application must be registered and you must have its App ID (Client ID)

Steps:

• Open Cloud Shell from navbar

Cloud Shell

• Select PowerShell from modal

PowerShell

• Save powershell script below as permissions.ps1

# Basic settings
$appName = "forestall-collector"

# Microsoft Graph API
$graphApiId = "00000003-0000-0000-c000-000000000000"
$graphPermissions = @{
    "Directory.Read.All"                      = "7ab1d382-f21e-4acd-a863-ba3e13f7da61"
    "AuditLog.Read.All"                       = "b0afded3-3588-46d8-8b3d-9842eff778da"
    "Policy.Read.All"                         = "246dd0d5-5bd0-4def-940b-0421030a5b68"
    "RoleManagement.Read.All"                 = "c7fbd983-d9aa-4fa7-84b8-17382c103bc4"
    "OnPremDirectorySynchronization.Read.All" = "bb70e231-92dc-4729-aff5-697b3f04be95"
    "SharePointTenantSettings.Read.All"       = "83d4163d-a2d8-4d3b-9695-4ae3ca98f888"
    "Sites.Read.All"                          = "332a536c-c7ef-4017-ab91-336970924f0d"
}

# SharePoint Online API
$sharepointApiId = "00000003-0000-0ff1-ce00-000000000000"
$sharepointPermissions = @{
    "Sites.FullControl.All" = "678536fe-1083-478a-9c59-b99265e6b0d3"
}

if (!(Get-Command az -ErrorAction SilentlyContinue)) {
    Write-Error "Azure CLI is not installed. Install it from https://aka.ms/installazurecli and rerun the script."
    exit 1
}

$tenantId = az account show --query tenantId -o tsv --only-show-errors
if (-not $?) {
    Write-Error "Not logged in to Azure CLI. Run 'az login' and rerun the script."
    exit 1
}

$existingAppId = az ad app list --display-name $appName --query "[0].appId" -o tsv --only-show-errors
if ($existingAppId) {
    Write-Host "App registration '$appName' already exists. Reusing existing app."
    $appId = $existingAppId
} else {
    Write-Host "Creating app registration '$appName'..."
    $appId = az ad app create --display-name $appName --query appId -o tsv --only-show-errors
    if (-not $?) { Write-Error "App registration failed."; exit 1 }
}

# Add Microsoft Graph permissions
foreach ($permName in $graphPermissions.Keys) {
    $permId = $graphPermissions[$permName]
    Write-Host "Adding Graph permission $permName"
    az ad app permission add --id $appId --api $graphApiId --api-permissions "$permId=Role" --only-show-errors | Out-Null
    if (-not $?) { Write-Error "Failed to add $permName"; exit 1 }
}

# Add SharePoint permissions
foreach ($permName in $sharepointPermissions.Keys) {
    $permId = $sharepointPermissions[$permName]
    Write-Host "Adding SharePoint permission $permName"
    az ad app permission add --id $appId --api $sharepointApiId --api-permissions "$permId=Role" --only-show-errors | Out-Null
    if (-not $?) { Write-Error "Failed to add SharePoint $permName"; exit 1 }
}

$existingSpId = az ad sp list --filter "appId eq '$appId'" --query "[0].id" -o tsv --only-show-errors
if ($existingSpId) {
    Write-Host "Service principal already exists. Skipping creation."
} else {
    Write-Host "Creating service principal..."
    az ad sp create --id $appId --only-show-errors | Out-Null
    if (-not $?) { Write-Error "Service principal creation failed."; exit 1 }
}

Write-Host "Generating client secret..."
$clientSecret = az ad app credential reset --id $appId --append --display-name "$appName-secret" --query password -o tsv --only-show-errors
if (-not $?) { Write-Error "Client secret creation failed."; exit 1 }

Write-Host "Granting admin consent (requires Global Admin)..."
$adminConsentNote = "Admin consent still pending. Grant it manually."

az ad app permission admin-consent --id $appId --only-show-errors | Out-Null
if ($?) {
    $adminConsentNote = "Admin consent granted."
} else {
    Write-Warning "Admin consent failed. Use a Global Admin account or grant consent manually in the Azure Portal."
    $retry = Read-Host "Login with a Global Admin now and retry? (Y/N)"
    if ($retry -match '^[Yy]') {
        az login --use-device-code
        if ($?) {
            az ad app permission admin-consent --id $appId --only-show-errors | Out-Null
            if ($?) {
                $adminConsentNote = "Admin consent granted."
            } else {
                Write-Warning "Admin consent retry failed. Grant consent manually in the Azure Portal."
            }
        } else {
            Write-Warning "Login cancelled or failed. Admin consent remains pending."
        }
    }
}

$summary = @"
App Name   : $appName
Tenant ID  : $tenantId
App ID     : $appId
Secret     : $clientSecret
Consent    : $adminConsentNote

Save the client secret now; it cannot be retrieved again.
"@

Write-Host $summary

• Upload file to powershell

Upload PowerShell Script

• After uploading the file, run it via console ./permissions.ps1

Notes:

• You can find your App ID in App registrations > [Your App] > Overview.

• After assigning permissions via script you need to copy Secret Value.

Client Secret needs to copy

• If using script without global admin account, admin consent still needs to be granted manually in the portal (go to optional step 2).

(Optional Step 2): Grant Admin Consent via Portal (if using script)

1. Go back to App registrations > [Your App] > API permissions.

2. Click Grant admin consent to activate the permissions.

3. Teams Reader Role must be assigned manually. Please check What is Teams Reader Role?

Step 3: Azure Configuration in FSProtect

This section allows you to configure Azure Active Directory (Azure AD) authentication and permissions for the application. Use this configuration to grant or revoke access to Azure resources and services.

Azure Configuration

Configuration Fields

Region

Specifies the Azure environment where your application is deployed. Options typically include:

• Cloud - Azure Public Cloud (standard commercial cloud)

• Government - Azure Government Cloud (for US government agencies)

• China - Azure China Cloud (operated by 21Vianet)

Directory (Tenant) ID

Format: UUID (e.g., 05588dae-2a80-4f4d-...)

Your Azure AD tenant identifier. This is a unique GUID that identifies your organization's Azure Active Directory instance. You can find this in the Azure Portal under Azure Active Directory > Overview > Tenant ID.

Application (Client) ID

Format: UUID (e.g., 07122f25-82ff-496d-...)

The unique identifier for your registered application in Azure AD. This is generated when you register an application in Azure Portal under App Registrations. This ID is used to identify your application when requesting authentication tokens.

Password Writeback Enabled

Determines whether password changes in Azure AD has written back to your on-premises Active Directory. Options:

• Enabled - Password changes sync back to on-premises AD

• Disabled - Password changes remain only in Azure AD

• Not Defined - Feature is not configured

Authentication Method

Specifies how your application authenticates with Azure AD. Common methods include:

• Client Secret - Uses a client secret for authentication

• Certificate (recommended) - Uses a certificate for authentication

Client Secret

The secret key used to authenticate your application with Azure AD. This value should be:

• Kept secure and never exposed in code or logs

• Rotated regularly according to your security policy

• Obtained from Azure Portal under App Registrations > Certificates & secrets

Tenant Display Name

A friendly name for your Azure AD tenant. This is typically your organization's name and helps identify the tenant in multi-tenant scenarios.

App Display Name

The display name of your registered application in Azure AD. This name appears in consent prompts and admin portals to help identify your application.

Actions

Test

Validates the Azure configuration by attempting to authenticate and verify permissions. Use this to ensure your configuration is correct before saving.

Save

Saves the current configuration settings to application. All fields must be properly configured before saving.

Delete

Removes the Azure configuration from application. Use with caution as this will disable Azure AD integration.

Best Practices

1. Least Privilege Principle - Only grant the minimum permissions required for application to function

2. Secret Rotation - Regularly rotate client secrets (recommended every 90 days or per your security policy)

3. Permission Review - Periodically review granted permissions and remove any that are no longer needed

4. Testing - Always use the "Test" button to validate configuration before saving changes

Troubleshooting

Authentication Fails

• Verify the Client ID and Client Secret are correct

• Ensure the secret hasn't expired

• Check that the application is registered in the correct tenant

Permission Denied Errors

• Confirm all required permissions are granted

• Verify an admin has consented to the permissions

• Check that users have appropriate licenses in Azure AD

Configuration Won't Save

• Ensure all required fields are filled

• Verify the Tenant ID and Client ID formats are valid UUIDs

• Check that the Test passes successfully before saving

Required Microsoft Azure Permissions for Integration

To ensure secure and comprehensive functionality between your systems and Microsoft Azure (Azure Active Directory), the following permissions are required:

1. Directory.Read.All

What it does: Grants read-only access to all directory objects in Microsoft Azure, including users, groups, devices, and administrative units.

Why it's needed: This permission allows the integration to retrieve essential identity data, enabling user mapping, group membership evaluation, and device information access for reporting or policy decisions.

---

2. AuditLog.Read.All

What it does: Provides read access to the directory’s audit logs, which record configuration changes and administrative actions across the tenant.

Why it's needed: Required to track configuration changes and user activity for auditing, compliance, and forensic analysis within the integration.

---

3. Policy.Read.All

What it does: Allows the application to read conditional access policies, authentication policies, and other security-related configurations.

Why it's needed: Essential for understanding and visualizing how security policies are configured across the tenant, helping administrators identify risks or configuration issues.

---

4. RoleManagement.Read.All

What it does: Grants read-only access to directory roles, role assignments, and role eligibility settings.

Why it's needed: Enables the integration to provide visibility into privileged roles, who holds them, and how administrative permissions are structured—critical for role governance and least-privilege assessments.

---

5. OnPremDirectorySynchronization.Read.All

What it does: Allows reading of the on-premises directory synchronization configuration and related metadata.

Why it's needed: Required to understand hybrid identity configurations, sync status, and directory health—ensuring that on-prem AD and Azure are working in harmony and fully visible to administrators.

Optional Microsoft Azure Permissions for Enhanced Functionality

These permissions enhance functionality but are not required for basic operation. Grant these based on your application's specific needs and use cases.

1. Teams Readers Role

What it does:

Grants read-only access to Microsoft Teams administration data and settings, including team configurations, user assignments, policies, and administrative information without the ability to make any changes.

Why it's needed:

Required when users or applications need to view Teams administrative settings for monitoring, reporting, compliance audits, or troubleshooting purposes without risking accidental modifications to the Teams environment.

2. SharePointTenantSettings.Read.All

What it does:

Provides read access to SharePoint tenant-level settings, including external sharing policies, site creation settings, and tenant-wide configurations.

Why it's needed:

Essential for understanding the global SharePoint configuration across your organization, helping administrators audit tenant settings, identify security risks, or ensure compliance with organizational policies.

3. Sites.Read.All

What it does:

Enables the application to read SharePoint site collections, lists, libraries, and their content across the entire organization without user delegation.

Why it's needed:

Required when your integration needs to analyze SharePoint content, generate reports on site usage, perform content audits, or provide visibility into document repositories for compliance purposes.

4. Sharepoint.Sites.FullControl.All

What it does:

Provides full control over all SharePoint sites, allowing the application to create, read, update, and delete sites, site collections, lists, libraries, and their content.

Why it's needed:

Necessary for integrations that actively manage SharePoint environments—such as automated site provisioning, content migration tools, backup solutions, or applications that modify site structures and permissions on behalf of administrators.

⚠️ Security Note: This is a highly privileged permission that grants extensive control over SharePoint data. Only grant this permission if your application absolutely requires write/modify capabilities, and ensure proper governance and monitoring are in place.