M365 Mailbox Backup Tool (self-hosted-m365-backup)

This is an open-source, self-hosted web application designed to back up Microsoft 365 mailboxes to a local server in the standard .eml format. Built with a security-first approach, it leverages the Microsoft Identity Platform for authentication, ensuring that access is protected by your organization's existing security policies.

Features

• Web-Based Management Panel: A modern and convenient web interface for all operations.
• Secure, Enterprise-Grade Authentication: Instead of managing local passwords, the application integrates with the Microsoft Identity Platform ("Login with Microsoft"). This ensures that your organization's existing security policies, including Multi-Factor Authentication (2FA/MFA), are automatically enforced, providing a highly secure login experience for administrators.
• Selective Backup: Choose one or more users to back up from a dynamically loaded list of all tenant users.
• Date Filtering: Back up items from specific time ranges (presets or custom dates).
• Asynchronous Background Tasks: Large backup jobs run in the background using Celery and Redis, ensuring the UI is always responsive.
• Task Status Dashboard: Monitor the status of all initiated backup tasks (Pending, In Progress, Success, Failure).
• Interactive Restore Portal: An Outlook-like three-pane interface to browse backed-up data:
  • Navigation through the original mailbox folder structure (Inbox, Sent Items, etc.).
  • A list of emails within the selected folder.
  • In-browser preview of emails without downloading.
• Privacy-by-Design Filter: The email preview pane is blurred by default to respect user privacy, with a hover-to-reveal feature for administrators.
• Full-Text Search: Search within the subject and body of all backed-up emails for a specific user.
• Automated Installation: A single install.sh script to deploy the entire application and its dependencies on a fresh Ubuntu server.

Architecture

• Backend: Python, Flask
• Web Server: Gunicorn, Nginx (as a Reverse Proxy)
• Background Tasks: Celery
• Queue Manager / Broker: Redis
• Frontend: HTML, Pico.css, HTMX
• Authentication: Microsoft Identity Platform (OAuth 2.0)

Installation Guide

The installation consists of two main stages: Azure Portal configuration and Server Installation.

I. Azure Portal Configuration (Prerequisites)

Before running the installation script, you must complete the following steps in the Azure Portal.

1. App Registration:

• Log in to portal.azure.com.
• Navigate to Azure Active Directory > App registrations > + New registration.
• Give your application a name (e.g., M365-Backup-Tool) and click Register.

2. API Permissions:

• In your newly created app, navigate to API permissions from the left menu.
• Click + Add a permission > Microsoft Graph.
• You will need to add two types of permissions:
  • Application permissions:
    • User.Read.All (To get the list of all users for backup selection)
    • Mail.Read.All (To read all mailboxes for the backup process)
  • Delegated permissions:
    • User.Read (To allow users to log in to the application with their Microsoft account)
• After adding these permissions, you must click the "Grant admin consent for [Your Organization's Name]" button to approve them. The status for all permissions should show a green checkmark and "Granted".

3. Add a Redirect URI:

• From the left menu, select Authentication.
• Click + Add a platform > Web.
• In the Redirect URIs field, you will enter a URI in the format https://<your_server_ip_address>/get_token. The install.sh script will show you the exact URI to use when you run it.
• Click Save.

4. Create a Client Secret:

• From the left menu, select Certificates & secrets > + New client secret.
• Add a description and choose an expiration period (e.g., 24 months).
• Click Add.
• VERY IMPORTANT: Immediately copy the "Value" of the newly created secret and save it somewhere safe. You will not be able to see this value again after you leave the page.

Summary: At the end of this stage, you must have these 3 pieces of information: Tenant ID, Client ID, and Client Secret Value.

II. Server Installation

Log into your fresh Ubuntu 22.04 LTS server and run the following commands.

# Download the installation script from GitHub
wget [https://raw.githubusercontent.com/DualStackAdmin/self-hosted-m365-backup/main/install.sh](https://raw.githubusercontent.com/DualStackAdmin/self-hosted-m365-backup/main/install.sh)

# Make the script executable
chmod +x install.sh

# Run the script with sudo
sudo ./install.sh