M365 License Analyzer

Open-source Microsoft 365 license analysis and optimization tool for Tabletop Exercises and strategic planning

🎯 What is This?

M365 License Analyzer is a comprehensive toolkit designed to help organizations conduct license optimization tabletop exercises. It collects Microsoft 365 license assignment data, imports it into a PostgreSQL database, and provides visualization through Grafana dashboards—enabling data-driven decisions about license allocation, cost optimization, and compliance.

Key Features

✅ Automated License Inventory - PowerShell scripts to collect M365 license data via Microsoft Graph API
✅ Flexible Deployment - Run standalone scripts or deploy full PostgreSQL + Grafana stack
✅ Docker Support - One-command deployment with docker-compose
✅ Sample Data Included - Test with anonymized data before connecting to your tenant
✅ Grafana Dashboards - Pre-built visualizations for license utilization and optimization
✅ Group-Based Licensing Analysis - Understand how licenses are assigned through groups
✅ Inactive User Detection - Identify unused licenses for cost savings
✅ Export Options - CSV and HTML reports for executive briefings

🚀 Quick Start

Option 1: Standalone (CSV Reports Only)

Perfect for quick assessments without database infrastructure.

# 1. Clone the repository
git clone https://github.com/MSSecCSA/M365LicenseAnalyzer-Public.git
cd M365LicenseAnalyzer-Public

# 2. Configure settings (interactive)
.\Setup-Configuration.ps1 -Interactive

# 3. Connect to Microsoft 365 and generate inventory
.\scripts\Generate-LicenseInventory.ps1

# Output: data/exports/LicenseInventory_YYYYMMDD.csv

Option 2: Full Stack (Docker + Grafana)

Best for ongoing monitoring and visual dashboards.

# 1. Clone and configure
git clone https://github.com/MSSecCSA/M365LicenseAnalyzer-Public.git
cd M365LicenseAnalyzer-Public
.\Setup-Configuration.ps1 -Interactive

# 2. Start Docker stack (PostgreSQL + Grafana)
.\docker\start-stack.ps1

# 3. Collect license data
.\scripts\Generate-LicenseInventory.ps1

# 4. Import to database
.\scripts\Import-ToPostgreSQL.ps1 -UseDocker

# 5. Open Grafana
Start-Process "http://localhost:3000"
# Login: admin / (password from .env file)

📋 Prerequisites

Required

PowerShell 5.1+ (Windows) or PowerShell 7+ (Cross-platform)

Microsoft Graph PowerShell SDK

Install-Module Microsoft.Graph -Scope CurrentUser

Optional (for Full Stack)

Docker Desktop (for containerized PostgreSQL + Grafana)
- Download Docker Desktop

Microsoft 365 Permissions

Your account needs these Microsoft Graph API permissions:

User.Read.All
Organization.Read.All
Directory.Read.All

Note: Global Reader or License Administrator roles typically have these permissions.

📖 Documentation

Core Guides

Installation Guide - Detailed setup for all deployment scenarios
Configuration Guide - Understanding config.json and environment variables
Usage Guide - Running scripts and interpreting results
Docker Guide - Container deployment and troubleshooting
Grafana Setup - Dashboard configuration and customization

Advanced Topics

Tabletop Exercise Guide - How to run a license optimization workshop
Data Schema - Database structure and relationships
Troubleshooting - Common issues and solutions
Contributing - How to contribute to this project

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Microsoft 365 Tenant                      │
│  (Users, Licenses, Groups, Activity Data via Graph API)    │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      │ Microsoft Graph API
                      │ (PowerShell SDK)
                      ▼
┌─────────────────────────────────────────────────────────────┐
│           M365 License Analyzer (This Tool)                  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ PowerShell Scripts                                    │  │
│  │  • Generate-LicenseInventory.ps1                     │  │
│  │  • Import-ToPostgreSQL.ps1                           │  │
│  └──────────────┬───────────────────────────────────────┘  │
│                 │                                            │
│                 ▼                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ CSV Exports (data/exports/)                          │  │
│  │  • License inventory                                  │  │
│  │  • User activity                                      │  │
│  │  • Group assignments                                  │  │
│  └──────────────┬───────────────────────────────────────┘  │
│                 │                                            │
│                 ▼                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ PostgreSQL Database (Docker/Standalone)              │  │
│  │  • sku_inventory                                      │  │
│  │  • user_licenses                                      │  │
│  │  • user_activity                                      │  │
│  │  • licensing_groups                                   │  │
│  └──────────────┬───────────────────────────────────────┘  │
│                 │                                            │
│                 ▼                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Grafana Dashboards (Docker/Standalone)               │  │
│  │  • License utilization                                │  │
│  │  • Cost analysis                                      │  │
│  │  • Inactive users                                     │  │
│  │  • Group-based licensing                              │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

🎓 Use Cases

1. License Optimization Tabletop Exercise

Facilitate a workshop where stakeholders analyze current license allocation and identify cost-saving opportunities.

Example Scenarios:

Identify users with E5 licenses who only use E3 features
Find inactive licenses (users who haven't signed in for 90+ days)
Analyze group-based licensing for optimization opportunities
Calculate potential savings from rightsizing licenses

2. Ongoing License Monitoring

Deploy the full stack and monitor license utilization trends over time.

3. Compliance Auditing

Generate reports showing license assignments for compliance reviews.

4. Budget Planning

Forecast license costs based on current usage patterns and growth projections.

📊 Sample Outputs

CSV Report Example

UserPrincipalName,DisplayName,Department,SkuName,SkuId,AssignmentStatus
[email protected],John Doe,Engineering,Office 365 E3,6fd2c87f-b296-42f0-b197-1e91e994b900,Active
[email protected],Jane Smith,Marketing,Office 365 E5,c7df2760-2c81-4ef7-b578-5b5392b571df,Active

Grafana Dashboard Preview

License Utilization Gauge - Percentage of licenses consumed vs. available
Cost Breakdown by SKU - Visual representation of spend by license type
Inactive Users Table - Sortable list of users with unused licenses
Group-Based Licensing Overview - Groups and their assigned licenses

🔒 Security & Privacy

Data Sensitivity

This tool collects:

✅ User Principal Names (emails)
✅ Display Names
✅ Department/Job Title (if available)
✅ License assignments
✅ Last sign-in dates

❌ Does NOT collect:

Email content
Files or documents
Personal conversations
Detailed activity logs beyond sign-in

Best Practices

🔐 Keep config.json secure - Contains database credentials
🔐 Use least-privilege accounts - Read-only Graph API permissions
🔐 Store data locally - Keep CSV exports and databases on secure infrastructure
🔐 Anonymize for demos - Use provided sample data for demonstrations

Data Retention

Review your organization's data retention policies
CSV exports should be treated as sensitive data
Consider encrypting data at rest

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

Code style guidelines
How to submit pull requests
Feature request process
Bug report templates

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

Third-Party Licenses

PostgreSQL - PostgreSQL License
Grafana - AGPL v3
Microsoft Graph PowerShell SDK - MIT License

🙋 Support & Community

Getting Help

Documentation: Check the docs/ folder first
Issues: GitHub Issues
Discussions: GitHub Discussions

Acknowledgments

This project was developed from lessons learned conducting Microsoft 365 license optimization tabletop exercises for enterprise organizations. Special thanks to the IT teams who provided feedback and real-world use cases.

🗺️ Roadmap

Azure AD Premium P1/P2 license analysis
Power Platform license tracking
Cost projection modeling
Automated remediation workflows
Multi-tenant support
REST API for integration

⚡ Quick Links

Made with ❤️ for Microsoft 365 Administrators

Empowering organizations to optimize their M365 licensing investments through data-driven decision making.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
data		data
docker		docker
docs		docs
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
Setup-Configuration.ps1		Setup-Configuration.ps1
config.template.json		config.template.json

License

MSSecCSA/M365LicenseAnalyzer-Public

Folders and files

Latest commit

History

Repository files navigation