diff --git a/containers/backupchecks/src/templates/documentation/mail-import/setup.html b/containers/backupchecks/src/templates/documentation/mail-import/setup.html index 50e5bf8..3c85e5b 100644 --- a/containers/backupchecks/src/templates/documentation/mail-import/setup.html +++ b/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. -

1.3 Grant API Permissions

+

1.3 Grant API Permissions (Start with Read-Only)

-

BackupChecks requires application permissions (not delegated) to access the mailbox:

+

BackupChecks requires application permissions (not delegated) to access the mailbox. Start with read-only access for initial testing:

  1. In your app registration, go to API permissions
    2. +
  2. Remove any default Microsoft Graph permissions that were added automatically
  3. Click Add a permission
  4. Select Microsoft Graph
  5. Select Application permissions (not Delegated)
    6. -
  6. Search for and add the following permissions: - -
    7. +
  7. Search for and add: Mail.Read - Read mail in all mailboxes
  8. Click Add permissions
  9. Important: Click Grant admin consent for [your organization]
  10. Confirm the consent
+
+ ⚠️ Tenant-Wide Access:
+ At this stage, the app has permission to read all mailboxes in your tenant. This is a security risk. Follow Step 1.4 (recommended) to restrict access to only the backup mailbox. +
+ +

1.4 Restrict Access to One Mailbox (Optional but Recommended)

+ +

To follow the principle of least privilege, restrict the application to access only the backup mailbox instead of all mailboxes in your tenant.

+ +
+ 💡 Security Best Practice:
+ This step is highly recommended 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. +
+ +

Prerequisites

+ + + +

Restrict via Application Access Policy

+ +
    +
  1. Open PowerShell and connect to Exchange Online: +
    Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com
    +
    2. +
  2. Create an Application Access Policy to restrict the app to one mailbox: +
    New-ApplicationAccessPolicy `
+  -AppId "<CLIENT_ID>" `
+  -PolicyScopeGroupId "backupreports@yourdomain.com" `
+  -AccessRight RestrictAccess `
+  -Description "Allow Graph app to access only the backup mailbox"
    + +
    3. +
  3. Test the policy to verify it's working: +
    Test-ApplicationAccessPolicy `
+  -Identity backupreports@yourdomain.com `
+  -AppId "<CLIENT_ID>"
    +
    4. +
  4. Expected result: AccessCheckResult : Granted
    5. +
  5. Test with a different mailbox to confirm access is denied: +
    Test-ApplicationAccessPolicy `
+  -Identity someuser@yourdomain.com `
+  -AppId "<CLIENT_ID>"
    +
    6. +
  6. Expected result: AccessCheckResult : Denied
    7. +
+ +
+ 💡 How It Works:
+ The Application Access Policy restricts the app to access only the mailbox specified in PolicyScopeGroupId. Even though the app has tenant-wide Mail.Read permissions, Exchange Online enforces the policy and blocks access to other mailboxes. +
+ +

1.5 Add Write Permissions (After Testing)

+ +

Once you've tested read-only access and confirmed it works correctly, add write permissions to allow BackupChecks to move processed emails.

+ +
    +
  1. Go back to your app in Azure AD → API permissions
    2. +
  2. Click Add a permission
    3. +
  3. Select Microsoft Graph → Application permissions
    4. +
  4. Add: Mail.ReadWrite - Read and write mail in all mailboxes
    5. +
  5. Click Add permissions
    6. +
  6. Important: Click Grant admin consent for [your organization] again
    7. +
+
💡 Why ReadWrite?
- The Mail.ReadWrite permission is required to move processed emails from the incoming folder to the processed folder. If you only grant Mail.Read, BackupChecks can import emails but cannot move them after processing. + The Mail.ReadWrite permission is required to move processed emails from the incoming folder to the processed folder. If you only grant Mail.Read, BackupChecks can import emails but cannot move them after processing. They will remain in the incoming folder.
+

Note: 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.

+

Step 2: Configure Mail Settings in BackupChecks

After creating the Azure AD app registration, configure BackupChecks to use it:

@@ -292,10 +361,13 @@

Next Steps

diff --git a/docs/changelog-claude.md b/docs/changelog-claude.md index 609464a..9e96372 100644 --- a/docs/changelog-claude.md +++ b/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)