From 165c510d8cddf33304f1746a2e3fbe88823e618f Mon Sep 17 00:00:00 2001 From: DualStackAdmin <64967000+DualStackAdmin@users.noreply.github.com> Date: Thu, 9 Oct 2025 01:33:02 +0400 Subject: [PATCH] Update README.md --- README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 89 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 185ec7d..67fb76b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,89 @@ -# self-hosted-m365-backup -A self-hosted, open-source tool to back up Microsoft 365 mailboxes to standard .eml files. Features a complete web UI for managing backups, with background tasks, search, preview functionality, and secure Microsoft OAuth 2.0 login. +# 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:///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 + +1. **Requirements:** A fresh **Ubuntu 22.04 LTS** server. +2. Copy the `install.sh` script to the server. +3. Make the file executable: + ```bash + chmod +x install.sh + ``` +4. Run the script with `sudo`: + ```bash + sudo ./install.sh + ``` +5. The script will prompt you for the Azure credentials you gathered (Tenant ID, Client ID, Client Secret) and the list of admin emails who are allowed to use the application. +6. Wait for the installation process to complete. The script will output the IP address to access the application. + +## Usage +- After the installation is finished, open a browser and navigate to `https://`. +- 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.