ms365-tenant-manager · diff

v1.1.0 to v1.2.0

89 added, 55 removed. Audit A to A.

---

name: ms365-tenant-manager

description: >

- Microsoft 365 tenant administration for Global Administrators. Use for tenant setup, Azure

- AD user management, Exchange Online and Teams config, Conditional Access policies, license

- management, and PowerShell bulk-operation scripts.

+ Generates reviewed PowerShell for Microsoft 365 admin: tenant setup and DNS, bulk

+ provisioning, offboarding, Conditional Access and security audits. Use when setting up,

+ hardening or auditing a tenant, or onboarding and offboarding users.

license: MIT + Commons Clause

metadata:

- version: 1.1.0

+ version: 1.2.0

author: borghei

category: engineering

domain: cloud-administration

- updated: 2026-06-17

+ updated: 2026-11-08

tags: [microsoft-365, azure-ad, office-365, administration]

---

# Microsoft 365 Tenant Manager

- The agent generates production-ready PowerShell scripts for M365 tenant setup, bulk user provisioning, Conditional Access policies, security audits, and license management. It automates user lifecycle operations (onboarding, offboarding), recommends license SKUs by role, and produces 7-category security audit reports via Microsoft Graph.

- ## Core Capabilities

- - **Tenant lifecycle** — setup checklists, domain verification, DNS record generation, security baseline, and PowerShell setup scripts for Exchange, SharePoint, Teams.

- - **User lifecycle automation** — bulk provisioning from CSV, secure 11-step offboarding, license recommendations by role/department, group membership suggestions, data validation.

- - **Security & compliance** — Conditional Access policy generation (report-only first), MFA enforcement, and 7-category security audits (MFA, admin roles, inactive users, guests, licenses, mailbox delegations, CA policies).

- - **License management** — SKU recommendations and distribution/cost estimates adjusted for GDPR/HIPAA compliance requirements.

- - **PowerShell generation** — Microsoft Graph-based scripts with error handling, logging, and `-WhatIf` support.

+ The agent produces reviewed, reversible PowerShell for Microsoft 365 administration: tenant setup plans and DNS records, bulk provisioning, secure offboarding, Conditional Access and 7-category security audits through Microsoft Graph and Exchange Online. The tools generate scripts from local inputs; they never connect to a tenant, so an administrator stays the one who runs every change.

## When to Use

- - New tenant setup — generate phased checklist, DNS records, and baseline scripts.

- - Security hardening — run audits and stand up Conditional Access / MFA policies.

- - Bulk user provisioning or secure offboarding.

- - License planning and quarterly utilization review.

+ - New tenant setup: phased checklist, DNS records and a baseline setup script.

+ - Security hardening: an audit first, then Conditional Access and MFA policies.

+ - Bulk user provisioning from a CSV, or offboarding a departing user.

+ - License planning by role, and quarterly utilization review.

## Clarify First

Before generating scripts, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

- - **Task:** tenant setup, security audit/hardening, bulk provisioning, or offboarding (selects `tenant_setup.py` vs `powershell_generator.py` vs `user_management.py`).

- - **Tenant inputs:** the domain, the user CSV, or the role/department data (the input the modules consume).

- - **Compliance regime:** GDPR/HIPAA or none (adjusts license SKU recommendations and the security baseline).

+ - **Task:** setup, audit and hardening, provisioning, or offboarding (selects the subcommand).

+ - **Tenant inputs:** the domain, the users CSV, the tenant config JSON, and the break-glass account to exclude from Conditional Access.

+ - **Compliance regime:** GDPR, HIPAA or none (changes license recommendations and retention steps in offboarding).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

- ## Tools

+ ## Before Applying Any Script

- The scripts are importable Python modules (instantiate a class, not a CLI). Full API, parameters, and worked examples are in [references/tools-and-workflows.md](references/tools-and-workflows.md).

+ These changes have real blast radius: a bad Conditional Access policy locks everyone out, and offboarding the wrong account cuts off a working employee.

- | Tool | Purpose | Entry point |

- |------|---------|-------------|

- | `powershell_generator.py` | Security audit, Conditional Access, and bulk license scripts | `from powershell_generator import PowerShellScriptGenerator` |

- | `user_management.py` | Provisioning, offboarding, license/group recommendations, validation | `from user_management import UserLifecycleManager` |

- | `tenant_setup.py` | Setup checklist, DNS records, setup script, license distribution | `from tenant_setup import TenantSetupManager` |

+ 1. **Read the generated script** and confirm the tenant, user and SKU values. The generator fills templates; it cannot see your tenant.

+ 2. **Keep a break-glass account** (cloud-only, excluded from every CA policy, credentials offline). Without one, a policy mistake has no way back in.

+ 3. **Report-only first.** CA policies are created as `enabledForReportingButNotEnforced`; check sign-in logs before enabling.

+ 4. **Preview with `-WhatIf`** where the script supports it (offboarding), and run bulk jobs on a pilot group of two or three users first.

+ 5. **Check legal hold and retention before offboarding.** Mailbox and OneDrive data are converted or archived, not exported; confirm the retention requirement with whoever owns it.

+ 6. **Name the approver.** Write down who approved a tenant-wide change and when, so the audit log has an owner.

- ## References

+ ## Workflow

- Load the reference that matches the task — keep this file lean and pull detail on demand:

+ 1. Gather inputs: domain, users CSV (`assets/sample_users.csv` shows the columns) or tenant config (`sample_input.json`).

+ 2. Generate with `scripts/ms365_cli.py <subcommand> ... -o file.ps1`.

+ 3. Validation checkpoint: `provision` validates every user and writes nothing if any row is invalid (exit 1); fix the CSV and rerun.

+ 4. Apply the checklist above, then hand the script to the administrator to run.

+ 5. Done when the audit script's reports show the intended state (for example zero users without MFA) and the change is recorded with its approver.

- - **[references/tools-and-workflows.md](references/tools-and-workflows.md)** — Quick Start commands, per-tool usage/parameters, the 3 end-to-end workflows (setup, hardening, offboarding), and the full Python module API for all three scripts. Read when running the tools or wiring up the API.

- - **[references/operations-and-best-practices.md](references/operations-and-best-practices.md)** — best practices, limitations, required modules/permissions, anti-patterns, the troubleshooting table, and success criteria. Read before hardening a tenant or shipping scripts.

- - **[references/powershell-templates.md](references/powershell-templates.md)** — ready-to-use script templates: Conditional Access policy examples, bulk user provisioning, and security audit scripts.

- - **[references/security-policies.md](references/security-policies.md)** — Conditional Access configuration, MFA enforcement strategies, DLP/retention policies, and security baseline settings.

- - **[references/troubleshooting.md](references/troubleshooting.md)** — common error resolutions, PowerShell module issues, permission troubleshooting, and DNS propagation problems.

+ ## Quick Start

- ## Scope & Limitations

+ ```bash

+ # from engineering/ms365-tenant-manager/

+ python3 scripts/ms365_cli.py audit --domain contoso.com -o "$(mktemp -d)/audit.ps1"

+ python3 scripts/ms365_cli.py provision --domain contoso.com --users assets/sample_users.csv | head -40

+ python3 scripts/ms365_cli.py provision --domain contoso.com --users assets/flawed_users.csv # exit 1, 2 invalid users

+ ```

- **What This Skill Covers**

+ ```bash

+ python3 scripts/ms365_cli.py conditional-access --domain contoso.com --exclude breakglass@contoso.com

+ python3 scripts/ms365_cli.py offboard --domain contoso.com --user ada.lovelace@contoso.com

+ python3 scripts/ms365_cli.py setup --config sample_input.json --part dns

+ python3 scripts/ms365_cli.py recommend-license --role "Finance Director" --department Finance --format json

+ ```

- - **Tenant lifecycle management** -- initial setup, domain verification, DNS configuration, security baseline, and service provisioning for Exchange Online, SharePoint, Teams, and OneDrive

- - **User lifecycle automation** -- bulk provisioning from CSV, license assignment by role/department, group membership recommendations, secure offboarding with mailbox preservation

- - **Security and compliance** -- Conditional Access policy generation, MFA enforcement, comprehensive 7-category security audits, and audit log enablement

- - **PowerShell script generation** -- production-ready scripts with error handling, logging, `-WhatIf` support, and Microsoft Graph best practices

+ ## Tools Overview

- **What This Skill Does NOT Cover**

+ | Tool | Purpose |

+ |------|---------|

+ | `scripts/ms365_cli.py` | CLI: `audit`, `conditional-access`, `bulk-license`, `provision`, `offboard`, `recommend-license`, `setup`. Writes to stdout or `-o FILE`; `--format json` for data subcommands. |

+ | `scripts/powershell_generator.py` | Library: audit, Conditional Access and bulk-license script templates (`PowerShellScriptGenerator`) |

+ | `scripts/user_management.py` | Library: provisioning, offboarding, license and group recommendations, user validation (`UserLifecycleManager`) |

+ | `scripts/tenant_setup.py` | Library: setup checklist, DNS records, setup script, license distribution (`TenantSetupManager`) |

- - **Hybrid identity (AD Connect)** -- on-premises Active Directory synchronization and pass-through authentication require the `senior-devops` skill and Microsoft AD Connect tooling

- - **Intune device management** -- endpoint compliance policies, app deployment, and mobile device management are outside scope; see `senior-secops` for device security posture

- - **Power Platform administration** -- Power Apps, Power Automate, and Power BI tenant-level governance fall under separate platform administration

- - **Third-party SSO and SCIM provisioning** -- integration with non-Microsoft identity providers (Okta, Ping, Auth0) requires dedicated identity engineering

+ **Exit codes (`ms365_cli.py`):** 0 output written; 1 `provision` found invalid users (no script written); 2 unusable input (missing file, bad JSON or CSV, invalid domain or user principal name). License prices are list prices baked into the module; check current Microsoft pricing before quoting them.

- ## Integration Points

+ ## Anti-Patterns

- | Skill | Integration | Data Flow |

- |-------|-------------|-----------|

- | `senior-secops` | Security audit findings feed into SecOps incident response and threat remediation workflows | Audit CSV reports (MFA status, admin roles, inactive users) → SecOps triage and hardening actions |

- | `senior-devops` | Tenant setup scripts integrate with infrastructure-as-code pipelines for repeatable deployments | Generated PowerShell scripts → CI/CD pipeline execution → tenant configuration state |

- | `senior-architect` | License distribution recommendations and tenant topology inform enterprise architecture decisions | License cost analysis and user count projections → architecture capacity planning |

- | `code-reviewer` | Generated PowerShell scripts can be reviewed for security anti-patterns and credential handling | PowerShell script output → code review for hardcoded secrets, missing error handling |

- | `aws-solution-architect` | Multi-cloud identity federation between Azure AD and AWS IAM for organizations using both platforms | Azure AD tenant configuration → cross-cloud SSO and role mapping |

- | `senior-security` | Conditional Access policies and MFA enforcement align with broader organizational security posture | CA policy configurations and security audit results → security policy compliance validation |

+ **Mistake:** Enforcing a Conditional Access policy on day one.

+ **Why it matters:** A policy that blocks legitimate sign-ins takes the whole company offline, admins included.

+ **Instead:** Create it report-only, review a week of sign-in logs, exclude the break-glass account, then enable.

+ **Mistake:** Running bulk provisioning or license scripts against everyone at once.

+ **Why it matters:** One wrong column or SKU repeats across hundreds of accounts and is slow to unwind.

+ **Instead:** Validate the CSV (the CLI refuses invalid rows), run a pilot of two or three users, then the rest.

+ **Mistake:** Deleting a departing user's account on their last day.

+ **Why it matters:** Deletion starts the clock on mailbox and OneDrive data and can breach retention or legal-hold duties.

+ **Instead:** Disable sign-in, revoke sessions, convert the mailbox to shared and keep the account until the retention owner signs off.

+ ## Reference Documentation

+ - **[references/tools-and-workflows.md](references/tools-and-workflows.md)**: CLI reference, the three end-to-end workflows (setup, hardening, offboarding) and the Python module API. Read when running the tools.

+ - **[references/operations-and-best-practices.md](references/operations-and-best-practices.md)**: best practices, required modules and roles, troubleshooting and success criteria. Read before hardening a tenant.

+ - **[references/powershell-templates.md](references/powershell-templates.md)**: hand-written Conditional Access, provisioning and audit templates.

+ - **[references/security-policies.md](references/security-policies.md)**: Conditional Access design, MFA rollout, DLP and retention, security baseline.

+ - **[references/troubleshooting.md](references/troubleshooting.md)**: module, permission and DNS propagation problems.

+ ## Files

+ | File | Purpose |

+ |------|---------|

+ | `scripts/ms365_cli.py` | Command-line entry point (stdlib only) |

+ | `scripts/powershell_generator.py`, `scripts/user_management.py`, `scripts/tenant_setup.py` | Template libraries the CLI imports |

+ | `sample_input.json` | Tenant config for `setup` (Acme, 75 users, GDPR) |

+ | `expected_output.json` | Example structured output for the sample config |

+ | `assets/sample_users.csv` | Three valid users; `provision` writes a script |

+ | `assets/flawed_users.csv` | Username with spaces, missing first name; `provision` exits 1 |

+ ## Scope & Limitations

+ **Covers:** tenant setup planning and DNS, user lifecycle (provisioning, offboarding, license and group recommendations), Conditional Access and MFA scripts, security audits, all through Microsoft Graph and Exchange Online PowerShell.

+ **Does not cover:**

+ - Hybrid identity (Microsoft Entra Connect sync, pass-through authentication).

+ - Intune device management and Power Platform governance.

+ - Third-party SSO and SCIM (Okta, Ping, Auth0).

+ - Running anything against a tenant: the scripts are generated for an administrator to review and run.