Initial commit

docs/setup/M365_SETUP.md

@@ -0,0 +1,160 @@
+# Microsoft 365 Setup
+
+Step-by-step guide for connecting GDPRScanner to Microsoft 365.
+
+---
+
+## 1. Register an app in Azure
+
+Go to **Azure Portal → Microsoft Entra ID → App registrations → New registration**.
+
+| Field | Value |
+|---|---|
+| Name | GDPRScanner (or any name) |
+| Supported account types | Accounts in this organisational directory only |
+| Redirect URI | Leave blank |
+
+Click **Register**. Note the **Application (client) ID** and **Directory (tenant) ID** — you'll need both.
+
+---
+
+## 2. Choose an authentication mode
+
+| Mode | How it works | When to use |
+|---|---|---|
+| **Application** | Client credentials — client ID + tenant ID + client secret. No user interaction. | Automated / scheduled scans, all-user scans |
+| **Delegated** | OAuth device code flow — user signs in interactively. | Single-user scans, testing |
+
+### Application mode — create a client secret
+
+In your app registration: **Certificates & secrets → New client secret**.
+
+Set an expiry (24 months recommended) and copy the **Value** immediately — it is only shown once.
+
+### Delegated mode — no secret needed
+
+The scanner will show a device code URL. Open it in a browser, sign in, and the scanner authenticates as that user.
+
+---
+
+## 3. Add API permissions
+
+Go to **API permissions → Add a permission → Microsoft Graph**.
+
+### Scan only
+
+| Permission | Type |
+|---|---|
+| `Mail.Read` | Application or Delegated |
+| `Files.Read.All` | Application or Delegated |
+| `Sites.Read.All` | Application or Delegated |
+| `ChannelMessage.Read.All` | Application |
+| `Team.ReadBasic.All` | Application |
+| `User.Read.All` | Application |
+
+### Scan + Delete
+
+Add these in addition to the read permissions above:
+
+| Permission | Type |
+|---|---|
+| `Mail.ReadWrite` | Application or Delegated |
+| `Files.ReadWrite.All` | Application or Delegated |
+| `Sites.ReadWrite.All` | Application or Delegated |
+
+### Email reports via Graph
+
+If you want the scanner to send email reports via Microsoft 365 (not SMTP):
+
+| Permission | Type |
+|---|---|
+| `Mail.Send` | Application or Delegated |
+
+### Grant admin consent
+
+All **Application** permissions require admin consent. Click **Grant admin consent for [your tenant]** at the top of the API permissions page. Without this, scans will fail with 403 errors.
+
+---
+
+## 4. Connect in GDPRScanner
+
+Open GDPRScanner → **Source Management → Microsoft 365** tab.
+
+| Field | Where to find it |
+|---|---|
+| Client ID | App registration → Overview → Application (client) ID |
+| Tenant ID | App registration → Overview → Directory (tenant) ID |
+| Client Secret | The value you copied in step 2 (Application mode only) |
+
+Click **Connect**. In Application mode, the connection is immediate. In Delegated mode, a browser window opens for sign-in.
+
+---
+
+## 5. Verify
+
+After connecting, the Sources panel shows:
+
+- **Email** — Exchange mailboxes
+- **OneDrive** — personal drives
+- **SharePoint** — site file libraries
+- **Teams** — Teams channel files
+
+The Accounts panel lists all users in the tenant (Application mode) or just the signed-in user (Delegated mode).
+
+---
+
+## Notes on deletion
+
+Emails deleted via the scanner are moved to **Deleted Items** — recoverable for 14–30 days depending on admin configuration. Files are sent to the **OneDrive/SharePoint recycle bin** — retained for 93 days across both recycle bin stages before permanent deletion. Nothing is permanently destroyed without a second manual step.
+
+---
+
+## Headless / scheduled mode
+
+Headless mode uses Application auth only. Credentials are read in priority order:
+
+1. `--settings FILE` — a JSON file you provide
+2. Environment variables: `M365_CLIENT_ID`, `M365_TENANT_ID`, `M365_CLIENT_SECRET`
+
+Example settings file:
+
+```json
+{
+  "client_id":     "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "tenant_id":     "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "client_secret": "your-secret",
+  "sources":       ["email", "onedrive"],
+  "options": {
+    "older_than_days": 365,
+    "email_body":      true,
+    "attachments":     true,
+    "delta":           true
+  }
+}
+```
+
+Run:
+
+```bash
+python gdpr_scanner.py --headless --output ~/Reports/ --settings settings.json
+```
+
+See the full CLI flag reference in `README.md`.
+
+---
+
+## Role classification (staff / student)
+
+GDPRScanner classifies users as **staff** or **student** based on their Microsoft 365 licence SKU. The mapping is in `classification/m365_skus.json`. If users appear as "other", open **Settings → SKU debug** to see which SKU IDs are assigned in your tenant and add any missing ones to `m365_skus.json`.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| 403 on scan start | Admin consent not granted, or wrong permissions added |
+| `AADSTS7000215` | Invalid client secret — check it was copied correctly |
+| No users listed | `User.Read.All` permission missing or not consented |
+| Teams files not appearing | `ChannelMessage.Read.All` or `Team.ReadBasic.All` missing |
+| Delta scan not working | Delta tokens require at least one full scan first |