83 lines
4.8 KiB
Markdown
83 lines
4.8 KiB
Markdown
# 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 process consists of two main parts: preparing the prerequisites in the Azure Portal and then running the installation script on your server.
|
|
|
|
### 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. The following commands will download the installation script, make it executable, and then run it with the necessary privileges.
|
|
|
|
```bash
|
|
wget https://raw.githubusercontent.com/DualStackAdmin/self-hosted-m365-backup/main/install.sh
|
|
```
|
|
|
|
```bash
|
|
chmod +x install.sh
|
|
```
|
|
|
|
```bash
|
|
sudo ./install.sh
|
|
```
|
|
|