# 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.

![Restore Portal Screenshot](https://github.com/DualStackAdmin/self-hosted-m365-backup/raw/main/backup%20interface.jpg)
![Login Page Screenshot](https://github.com/DualStackAdmin/self-hosted-m365-backup/blob/main/backuplogin.jpg)

## ✨ Features

-   💻 **Web-Based Management Panel:** A modern and convenient web interface for all operations.
-   🛡️ **Secure, Enterprise-Grade Authentication:** Integrates with the Microsoft Identity Platform ("Login with Microsoft"), automatically enforcing your organization's existing security policies, including **Multi-Factor Authentication (2FA/MFA)**.
-   ✅ **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, including folder navigation, an email list, and an in-browser preview pane.
-   👁️‍🗨️ **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 and follow these steps.

#### Step 1: Download the Script
Use `wget` to download the latest installer from the GitHub repository.
```bash
wget https://raw.githubusercontent.com/DualStackAdmin/self-hosted-m365-backup/main/install.sh
```

#### Step 2: Make the Script Executable
Grant execution permissions to the downloaded file.
```bash
chmod +x install.sh
```

Step 3: Run the Installer
Execute the script with sudo privileges.

```bash
sudo ./install.sh
```

The script will first ask you to confirm that you have set the Redirect URI in the Azure Portal. It will then become interactive and ask for the following details to configure the application:

Azure Tenant ID

Application (Client) ID

Client Secret Value (your input will be hidden)

Allowed Admin Emails (comma-separated list)

After you provide this information, the script will complete the entire installation and configuration automatically.

🚀 Usage
After the installation is complete, open a browser and navigate to https://<your_server_ip>.

Accept the browser's security warning (this is normal for a self-signed certificate).

You will be redirected to the Microsoft login page. Sign in with your authorized M365 account.

New Backup: Used to start a new backup task.

Existing Backups: Used to browse, search, and preview existing backups.

Tasks: Used to monitor the status of background and completed tasks.