M365 Unified

1. Install Dependencies

cd m365-unified
npm install

2. Run Setup Wizard

npm run setup
or
node scripts/setup-wizard.js

The interactive wizard will:

3. Configure Azure AD App Registration

#### Step 1: Create App Registration

1. Go to Azure Portal → Azure Active Directory → App registrations 2. Click New registration 3. Name: m365-unified-skill (or your choice) 4. Supported account types: Single tenant 5. Redirect URI: Leave empty (not needed for app-only auth) 6. Click Register

#### Step 2: Create Client Secret

1. In your app registration → Certificates & secrets 2. Click New client secret 3. Description: m365-unified-secret 4. Expires: Choose 12-24 months 5. Click Add 6. ⚠️ IMPORTANT: Copy the secret value immediately (you can't see it again!)

#### Step 3: Configure API Permissions

1. In your app registration → API permissions 2. Click Add a permission → Microsoft Graph 3. Select Application permissions (NOT delegated!) 4. Add the permissions you need:

| Feature | Permissions | |---------|-------------| | Email (read) | Mail.Read | | Email (send) | Mail.Send | | Email (full) | Mail.ReadWrite | | SharePoint | Sites.ReadWrite.All | | OneDrive | Files.ReadWrite.All | | Planner | Tasks.ReadWrite, Group.Read.All | | Webhooks | User.Read (minimum for validation) |

5. Click Grant admin consent for [Your Tenant] (admin action required)

#### Step 4: Copy IDs

From the app registration Overview page, copy:

4. Configure Environment

Copy the template and fill in your values:

cp config/template.env .env

Edit .env:

# Required - Authentication
M365_TENANT_ID=""
M365_CLIENT_ID=""
M365_CLIENT_SECRET=""
Optional - Feature Toggles
M365_ENABLE_EMAIL=true
M365_ENABLE_SHAREPOINT=false
M365_ENABLE_ONEDRIVE=false
M365_ENABLE_PLANNER=false
M365_ENABLE_WEBHOOKS=false
Optional - Module Config
M365_MAILBOX="user@domain.com"
M365_SHARED_MAILBOXES="team1@domain.com,team2@domain.com"
M365_SHAREPOINT_SITE_ID=".sharepoint.com,,"
M365_PLANNER_GROUP_ID=""
M365_WEBHOOK_URL="https://your-domain.com/webhook/m365"
M365_WEBHOOK_SECRET=""

5. Test Connection

npm test
or
node scripts/test-connection.js

1. Never commit .env - Already in .gitignore 2. Use app-only permissions (not delegated) for automated tasks 3. Restrict mailbox access via Azure AD app assignment 4. Rotate secrets every 12-18 months 5. Monitor sign-in logs in Azure AD regularly 6. Use HTTPS for webhook endpoints 7. Validate webhook signatures with client state secret

Mailbox Access Restrictions

By default, Mail.ReadWrite grants access to ALL mailboxes in the tenant. To restrict:

#### Option 1: Azure AD App Assignment (Recommended)

1. Azure AD → Enterprise Apps → Your App → Users and groups 2. Add ONLY the users/mailboxes that should have access 3. Remove "All users" if present

#### Option 2: Application Access Policies (Exchange PowerShell)

# Create security group with specific mailboxes
New-DistributionGroup -Name "M365AppAccess" -Type Security
Add mailboxes to group
Add-DistributionGroupMember -Identity "M365AppAccess" -Member "user@domain.com"
Create access policy
New-ApplicationAccessPolicy -AppId "CLIENT-ID" -PolicyScopeGroupId "M365AppAccess" -AccessRight RestrictAccess

Permission Scopes Reference

| Feature | Minimum Permissions | Recommended | |---------|-------------------|-------------| | Email (read) | Mail.Read | Mail.Read | | Email (send) | Mail.Send | Mail.Send | | Email (full) | Mail.ReadWrite | Mail.ReadWrite | | SharePoint | Sites.Read.All | Sites.ReadWrite.All | | OneDrive | Files.Read.All | Files.ReadWrite.All | | Planner | Tasks.Read, Group.Read | Tasks.ReadWrite, Group.Read.All | | Webhooks | User.Read | User.Read |