Declarative PowerShell framework to deploy and audit an Active Directory Tier Model (OUs, Groups, Users, ACL Delegations, GPOs, ADMX, MSA/gMSA/dMSA Permissions) from a single version-controlled JSON configuration file. Supports idempotent re-runs, drift detection, and reproducible builds via pinned dependency versions.
🏗️ Built with the Specify Framework - Test-driven development ensuring quality and reliability
- 🔒 Safe, repeatable deployments (WhatIf planning + convergent apply)
- 📊 Drift auditing & reporting (hash provenance + structured findings)
- 🧩 Modular, test-first architecture (Pester enforced)
- 📦 Version governance for dependencies & configuration schema
📖 Full documentation: GitHub Pages - Active Directory Tier Model
To get started with TierModel, please refer to our comprehensive documentation:
- Quick Deployment Guide - Fast-track deployment for experienced administrators
- Detailed Deployment Guide - Step-by-step deployment with explanations
- FAQ - Frequently asked questions covering upgrades, migration from previous versions, troubleshooting, and Sentinel integration
- Deployment Methodology - Understanding the deployment approach
- Drift Detection Details - Comprehensive drift auditing and remediation
- Tier Model Logging - Structured logging and diagnostics
- GPO Management Strategy - Group Policy Object management
- ADMX Management - Administrative template handling
- Conditional Principals - Domain-specific principal resolution
- CI/CD Integration - Pipeline integration and automation
- Test Tag Matrix - Pester test organization
- Test Coverage - Comprehensive test coverage analysis and roadmap
- Feature Specification - Complete requirements and user stories
- Implementation Plan - Technical architecture and design decisions
Current Test Status: ✅ ALL TESTS PASSING (Last run: June 4, 2026)
| Test Suite | Test Files | Test Cases | Status | Coverage |
|---|---|---|---|---|
| Unit Tests | 15 files | 1,091 tests | ✅ 100% Pass | 91.6% |
| Integration Tests | 6 files | 201 tests | ✅ 100% Pass | 100% |
| Manual Integration Tests | 1 file | 311 tests | ✅ 100% Pass | 100% |
| Total | 22 files | 1,603 tests | ✅ All Passing | 91.6% |
- ✅ 58/58 production files have comprehensive test coverage (12 new MSA/gMSA/dMSA cmdlets added in Phase 16)
- ✅ 100% of all automated 1,292 test cases passing
- ✅ 100% of all manual 311 test cases passing
- ✅ 91.6% overall line coverage (10,444 / 11,389 commands) — all files at 80%+, MSA/gMSA/dMSA at 90%+
- ✅
Get-TierModelConditionalGroupNames— new function with full test coverage (6 unit tests) - ✅ New in Phase 16: Unit test files for MSA/gMSA/dMSA ACL operations (Unit.MsaAclOperations.Tests.ps1, Unit.GmsaAclOperations.Tests.ps1, Unit.DmsaAclOperations.Tests.ps1)
- ✅ Mock-based testing (no Active Directory connectivity required)
- ✅ WhatIf support validation across all deployment operations
# Run all tests
.\tests\Invoke-AllTests.ps1
# Run unit tests only
.\tests\Invoke-AllTests.ps1 -TestType Unit
# Run integration tests only
.\tests\Invoke-AllTests.ps1 -TestType Integration
# Show only failures (useful for large test runs)
.\tests\Invoke-AllTests.ps1 -FailedOnly
# Run with detailed output
.\tests\Invoke-AllTests.ps1 -Detailed| Script | Purpose | Optional Features |
|---|---|---|
Deploy-TierModel.ps1 |
🚀 Deploy with scoped execution | -IncludeMsa, -IncludeGmsa, -IncludeDmsa (Managed Service Account ACL delegation) |
Audit-TierModel.ps1 |
📊 Audit and compliance checking | -IncludeMsa, -IncludeGmsa, -IncludeDmsa (Managed Service Account ACL audit) |
Contributions are welcome! Before submitting a pull request, you must ensure:
- ✅ All Pester tests pass — the CI pipeline will reject any PR with failing tests
- 🧪 New or updated tests are included — any new code or bug fix must include corresponding test cases to maintain or improve code coverage
- 📊 Code coverage stays at or above 80% — the CI enforces a minimum coverage threshold; if your changes reduce coverage below 80%, add tests until coverage is restored
- 📝 Documentation is updated for any new or changed functionality
- 🎯 Code follows project conventions
Note: The packaging step will not produce a release artifact unless all tests pass and coverage meets the minimum threshold.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
# Clone repository
git clone https://github.com/microsoft/ActiveDirectoryTierModel.git
cd ActiveDirectoryTierModel
# Run tests locally before submitting a PR
.\tests\Invoke-AllTests.ps1- PowerShell: 7.0+
- Elevation: Administrator privileges required
- Domain Admin: Membership in Domain Admins group
- Modules: ActiveDirectory, GroupPolicy (see
config/dependencies.json)
For detailed prerequisite validation, run Test-TierModelPrerequisites
Version: 1.1.0 | License: MIT | Status: ✅ Production Ready
This project uses semantic versioning (MAJOR.MINOR.PATCH) and tag-based releases.
| Bump | When | Example |
|---|---|---|
PATCH (1.0.1) |
Bug fix, typo, doc correction | Fix broken ACL rule |
MINOR (1.1.0) |
New feature, backward-compatible | Add WinLAPS parameter |
MAJOR (2.0.0) |
Breaking change | Restructure config schema |
- Ensure all changes are merged to
mainand CI is green - Tag the release:
git tag v1.1.0 git push origin v1.1.0
- The CI pipeline will automatically:
- Run all tests and enforce code coverage (80% minimum)
- Create a
TierModel-1.1.0.ziprelease asset - Publish a GitHub Release with auto-generated release notes
You can also create a release from the GitHub UI: Releases → Create a new release → enter the tag name (e.g. v1.1.0).
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.