Enhance Mail Import Setup with Application Access Policy security

Enhanced Mail Import Setup documentation with additional security measures:
- Step 1.3: Start with Mail.Read only (read-only) for initial testing
- Step 1.4 (NEW): Restrict access to one mailbox via Application Access Policy
  - Exchange PowerShell commands to create and test policy
  - Ensures app can only access backup mailbox, not all tenant mailboxes
  - Marked as "Optional but Recommended" following principle of least privilege
- Step 1.5: Add Mail.ReadWrite after testing (moved from 1.3)
- Updated Security Best Practices section to emphasize mailbox restriction
- Added security notes about starting read-only and rotating secrets (12 months)

Based on setup documented in /docker/develop/HOWTO-CREATE-GRAPH-APP.md

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

containers/backupchecks/src/templates/documentation/mail-import/setup.html

@@ -75,31 +75,100 @@
   Client secrets expire after the selected period. Set a calendar reminder to renew the secret before expiration, or mail import will stop working. When renewing, create a new secret, update BackupChecks settings, then delete the old secret.
 </div>
 
-<h3>1.3 Grant API Permissions</h3>
+<h3>1.3 Grant API Permissions (Start with Read-Only)</h3>
 
-<p>BackupChecks requires <strong>application permissions</strong> (not delegated) to access the mailbox:</p>
+<p>BackupChecks requires <strong>application permissions</strong> (not delegated) to access the mailbox. Start with read-only access for initial testing:</p>
 
 <ol>
   <li>In your app registration, go to <strong>API permissions</strong></li>
+  <li><strong>Remove</strong> any default Microsoft Graph permissions that were added automatically</li>
   <li>Click <strong>Add a permission</strong></li>
   <li>Select <strong>Microsoft Graph</strong></li>
   <li>Select <strong>Application permissions</strong> (not Delegated)</li>
-  <li>Search for and add the following permissions:
-    <ul>
-      <li><code>Mail.Read</code> - Read mail in all mailboxes</li>
-      <li><code>Mail.ReadWrite</code> - Read and write mail in all mailboxes</li>
-    </ul>
-  </li>
+  <li>Search for and add: <code>Mail.Read</code> - Read mail in all mailboxes</li>
   <li>Click <strong>Add permissions</strong></li>
   <li><strong>Important:</strong> Click <strong>Grant admin consent for [your organization]</strong></li>
   <li>Confirm the consent</li>
 </ol>
 
+<div class="doc-callout doc-callout-warning">
+  <strong>⚠️ Tenant-Wide Access:</strong><br>
+  At this stage, the app has permission to read <strong>all mailboxes</strong> in your tenant. This is a security risk. Follow Step 1.4 (recommended) to restrict access to only the backup mailbox.
+</div>
+
+<h3>1.4 Restrict Access to One Mailbox (Optional but Recommended)</h3>
+
+<p>To follow the <strong>principle of least privilege</strong>, restrict the application to access <strong>only the backup mailbox</strong> instead of all mailboxes in your tenant.</p>
+
+<div class="doc-callout doc-callout-tip">
+  <strong>💡 Security Best Practice:</strong><br>
+  This step is <strong>highly recommended</strong> for production environments. It ensures that even if the client secret is compromised, the attacker can only access the backup mailbox, not personal or sensitive mailboxes.
+</div>
+
+<h4>Prerequisites</h4>
+
+<ul>
+  <li>Exchange Online PowerShell module installed</li>
+  <li>Exchange Administrator permissions</li>
+  <li>Client ID from Step 1.1</li>
+</ul>
+
+<h4>Restrict via Application Access Policy</h4>
+
+<ol>
+  <li>Open PowerShell and connect to Exchange Online:
+<pre><code>Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com</code></pre>
+  </li>
+  <li>Create an Application Access Policy to restrict the app to one mailbox:
+<pre><code>New-ApplicationAccessPolicy `
+  -AppId "&lt;CLIENT_ID&gt;" `
+  -PolicyScopeGroupId "backupreports@yourdomain.com" `
+  -AccessRight RestrictAccess `
+  -Description "Allow Graph app to access only the backup mailbox"</code></pre>
+    <ul>
+      <li>Replace <code>&lt;CLIENT_ID&gt;</code> with your Application (client) ID from Step 1.1</li>
+      <li>Replace <code>backupreports@yourdomain.com</code> with your backup mailbox address</li>
+    </ul>
+  </li>
+  <li>Test the policy to verify it's working:
+<pre><code>Test-ApplicationAccessPolicy `
+  -Identity backupreports@yourdomain.com `
+  -AppId "&lt;CLIENT_ID&gt;"</code></pre>
+  </li>
+  <li>Expected result: <code>AccessCheckResult : Granted</code></li>
+  <li>Test with a different mailbox to confirm access is denied:
+<pre><code>Test-ApplicationAccessPolicy `
+  -Identity someuser@yourdomain.com `
+  -AppId "&lt;CLIENT_ID&gt;"</code></pre>
+  </li>
+  <li>Expected result: <code>AccessCheckResult : Denied</code></li>
+</ol>
+
+<div class="doc-callout doc-callout-info">
+  <strong>💡 How It Works:</strong><br>
+  The Application Access Policy restricts the app to access only the mailbox specified in <code>PolicyScopeGroupId</code>. Even though the app has tenant-wide <code>Mail.Read</code> permissions, Exchange Online enforces the policy and blocks access to other mailboxes.
+</div>
+
+<h3>1.5 Add Write Permissions (After Testing)</h3>
+
+<p>Once you've tested read-only access and confirmed it works correctly, add write permissions to allow BackupChecks to move processed emails.</p>
+
+<ol>
+  <li>Go back to your app in Azure AD → <strong>API permissions</strong></li>
+  <li>Click <strong>Add a permission</strong></li>
+  <li>Select <strong>Microsoft Graph</strong> → <strong>Application permissions</strong></li>
+  <li>Add: <code>Mail.ReadWrite</code> - Read and write mail in all mailboxes</li>
+  <li>Click <strong>Add permissions</strong></li>
+  <li><strong>Important:</strong> Click <strong>Grant admin consent for [your organization]</strong> again</li>
+</ol>
+
 <div class="doc-callout doc-callout-info">
   <strong>💡 Why ReadWrite?</strong><br>
-  The <code>Mail.ReadWrite</code> permission is required to move processed emails from the incoming folder to the processed folder. If you only grant <code>Mail.Read</code>, BackupChecks can import emails but cannot move them after processing.
+  The <code>Mail.ReadWrite</code> permission is required to move processed emails from the incoming folder to the processed folder. If you only grant <code>Mail.Read</code>, BackupChecks can import emails but cannot move them after processing. They will remain in the incoming folder.
 </div>
 
+<p><strong>Note:</strong> If you configured the Application Access Policy in Step 1.4, the write restriction still applies - the app can only write to the backup mailbox, not other mailboxes.</p>
+
 <h2>Step 2: Configure Mail Settings in BackupChecks</h2>
 
 <p>After creating the Azure AD app registration, configure BackupChecks to use it:</p>
@@ -292,10 +361,13 @@
 
 <ul>
   <li><strong>Use a dedicated mailbox:</strong> Don't use a personal mailbox for backup reports</li>
-  <li><strong>Restrict app permissions:</strong> Only grant the minimum required permissions (Mail.Read and Mail.ReadWrite)</li>
-  <li><strong>Rotate secrets regularly:</strong> Set calendar reminders to renew client secrets before expiration</li>
+  <li><strong>Restrict to one mailbox:</strong> Configure an Application Access Policy (Step 1.4) to limit the app to only the backup mailbox - this is the <strong>most important</strong> security measure</li>
+  <li><strong>Start with read-only:</strong> Begin with <code>Mail.Read</code> only, test thoroughly, then add <code>Mail.ReadWrite</code> after validation</li>
+  <li><strong>Restrict app permissions:</strong> Only grant the minimum required permissions (Mail.Read and Mail.ReadWrite, not broader permissions)</li>
+  <li><strong>Rotate secrets regularly:</strong> Set calendar reminders to renew client secrets before expiration (recommended: 12 months)</li>
   <li><strong>Limit admin access:</strong> Only BackupChecks admins should have access to Settings</li>
-  <li><strong>Monitor import logs:</strong> Check audit logs regularly for failed authentication attempts</li>
+  <li><strong>Monitor import logs:</strong> Check audit logs regularly for failed authentication attempts or unusual activity</li>
+  <li><strong>Store secrets securely:</strong> Client secrets are stored encrypted in the database - never commit them to source code</li>
 </ul>
 
 <h2>Next Steps</h2>

docs/changelog-claude.md

@@ -6,7 +6,7 @@ This file documents all changes made to this project via Claude Code.
 
 ### Added
 - Completed Mail & Import documentation section (4 pages):
-  - **Mail Import Setup**: Microsoft Graph API configuration (Azure AD app registration, permissions, credentials), folder configuration (incoming/processed), test configuration, troubleshooting (authentication errors, folder not found, no emails imported), advanced configuration (email retention, multiple mailboxes), security best practices
+  - **Mail Import Setup**: Microsoft Graph API configuration with enhanced security (Azure AD app registration, start with Mail.Read only, Application Access Policy to restrict access to one mailbox via Exchange PowerShell, add Mail.ReadWrite after testing), folder configuration (incoming/processed), test configuration, troubleshooting (authentication errors, folder not found, no emails imported), advanced configuration (email retention, multiple mailboxes), comprehensive security best practices including principle of least privilege
   - **Inbox Management**: Inbox overview and workflow, table columns explanation, viewing email details (metadata, body iframe, parsed objects), approving emails (customer selection, job name), what happens after approval, re-parsing emails (single and bulk), deleting emails (single and bulk delete, soft delete behavior), downloading .eml files, common workflows (new customer setup, troubleshooting unparsed emails, cleaning spam), best practices
   - **Mail Parsing**: Parsing overview and workflow (retrieval, preprocessing, parser selection, matching, parsing, storage), parsers (viewing available parsers, parser information), match criteria (sender, subject, body match), supported backup software (Veeam, Synology, NAKIVO, Boxafe, Panel3, QNAP, Syncovery, 3CX, RDrive, NTFS Auditing), parser execution order, enabling/disabling parsers, re-parsing emails, parsing workflow example, troubleshooting parsing issues, parser limitations, best practices
   - **Auto-Import Configuration**: Auto-import overview and features, enabling auto-import, import interval configuration (5/15/30/60 minutes), batch size explanation, how auto-import works (timer, check settings, authenticate, fetch, parse, auto-approve, move, log, persist, wait), auto-approval logic and conditions, when auto-approval fails, manual import (triggering, batch size 1-50), import settings summary table, monitoring import activity (audit log, inbox page, jobs/daily jobs), troubleshooting (auto-import not running, emails not auto-approved, import errors), best practices, advanced configuration (disabling temporarily, EML retention, high-volume environments)