Microsoft Graph SharePoint Backup (PowerShell 7)

This project backs up SharePoint files from Microsoft Graph to a local folder using a PowerShell 7 wizard script.

Main Script

• graph-backup.ps1

What It Does

• App-only authentication with Microsoft Entra app credentials.
• Role and access validation before backup:
  • Sites.Read.All
  • Files.Read.All
• Interactive site selection in terminal (all or numbered selection).
• One-way mirror sync for selected site(s):
  • New/changed files are downloaded.
  • Local files missing in Microsoft are deleted (only inside selected site roots).
• File compare mode:
  • name + size + mtime
• Interactive skip during download:
  • Press s to skip current file.
• Retry handling:
  • Graph listing requests retry on temporary failures.
  • File downloads retry on temporary failures.
• Safer download writes:
  • Downloads are written to *.part temp files first.
  • On success, temp file is moved to final filename.
  • On failure/skip, temp file is removed.
  • Resume is not enabled; interrupted files are downloaded from start next run.
• Terminal wizard flow:
  1. Initial loading and token/access validation
  2. Site selection
  3. File counting and download
  4. Final report with rerun/quit prompt
• Quick mode (non-interactive):
  • -Site starts backup immediately without wizard steps.
  • -Folder is optional; if omitted, backup path is taken from BACKUP_DIR (or default).
  • -DownloadLimitMbps is optional and overrides env throttling for this run.
• Site listing mode:
  • -List prints available site names and exits.
• Help mode:
  • -Help prints command usage and exits.
• Download throttling:
  • Configurable with DOWNLOAD_LIMIT_MBPS in env.
  • Configurable per quick run with -DownloadLimitMbps.
  • 0 means disabled.
• Input validation:
  • Unknown/extra arguments return a clean error and suggest -Help.
  • -List cannot be combined with -Site, -Folder, or -DownloadLimitMbps.
• Main menu (default interactive mode):
  • Run backup
  • Update env settings
  • Exit
• Built-in env editor:
  • Updates common keys directly in env file from terminal.
  • Includes short input-format guide and examples.

Requirements

• PowerShell 7 (pwsh)
• Microsoft Entra App Registration with:
  • Sites.Read.All (Application)
  • Files.Read.All (Application)
• Admin consent granted

Configuration

Copy and edit:

cp graph-login.env.example graph-login.env

Supported variables:

• TENANT_ID (required)
• CLIENT_ID (required)
• CLIENT_SECRET (required)
• DOWNLOAD_TIMEOUT (optional, default 120)
• DOWNLOAD_LIMIT_MBPS (optional, default 0, set max download speed in Mbps)
• LOG_FILE (optional, default ./graph-backup.log)
• TOKEN_FILE (optional, default .graph_token)
• BACKUP_DIR (optional, default ./sharepoint-backup)
• SKIP_PATTERNS (optional, comma-separated globs)
• INCLUDE_PATTERNS (optional, comma-separated globs)
• INTERACTIVE_SKIP (optional, 1 or 0)

Run

pwsh ./graph-backup.ps1

Quick backup (non-interactive):

pwsh ./graph-backup.ps1 -Site Test -Folder D:\backup
pwsh ./graph-backup.ps1 -Site Test
pwsh ./graph-backup.ps1 -Site Test -DownloadLimitMbps 10
pwsh ./graph-backup.ps1 -Site Test -Folder D:\backup -DownloadLimitMbps 0.5

List sites:

pwsh ./graph-backup.ps1 -List

Help:

pwsh ./graph-backup.ps1 -Help

Output

• Backup folder:
  • ./sharepoint-backup
• Token files:
  • ./.graph_token
  • ./.graph_token.expires_at
• Log file:
  • ./graph-backup.log (or LOG_FILE value)

Notes

• Site filtering is interactive in the wizard (no SITE_FILTER env usage).
• Quick mode uses exact site match on displayName, name, or id.
• Skipped files are not counted as downloaded and are attempted again in future runs.
• During download, progress panel is terminal-only and not written to log.
• If backup is interrupted (Ctrl+C), partially downloaded *.part files are not resumed automatically.

Security

• Do not commit graph-login.env, token files, logs, or backup data.
• Rotate CLIENT_SECRET immediately if exposed.