By the numbers

This isn’t just another admin tool—it’s a comprehensive enterprise platform built for scale and serious identity management:

• 59+ pre-built report templates across Active Directory, Azure AD, and Microsoft 365
• 15+ Active Directory reports covering users, passwords, locked accounts, privileged access, and computer inventory
• 10+ Azure AD reports for guest management, MFA status, risky sign-ins, and conditional access policies
• 130+ backend tests with 85%+ code coverage ensuring production reliability
• 4 authentication methods supporting LDAP, Azure AD OAuth 2.0, JWT tokens, and cookie sessions
• Real-time WebSocket updates every 30 seconds for system health and log streaming
• Multiple export formats including Excel, CSV, PDF, and JSON for downstream integration
• 15-minute deployment from clone to operational dashboard using Docker Compose
• Dual CI/CD platforms with GitLab CI and GitHub Actions demonstrating enterprise DevOps practices

Why I Built This

If you’ve ever tried to answer a simple “Who has access to what?” question across
on-prem Active Directory, Azure AD, and Microsoft 365, you know how fast things get messy.
Scripts, partial exports, and one-off dashboards don’t scale. I wanted a single, approachable
web app where admins and business users can generate accurate reports, monitor identity health,
and stop the back-and-forth for routine data requests.

That goal became SimpleAdminReporter—a comprehensive, containerized application that unifies
reporting for AD, Azure AD, and Microsoft 365. It ships with pre-built templates, a visual query builder,
scheduled delivery, one-click exports, and real-time health monitoring.

The problem it solves

• Scattered data sources: Identity data lives in multiple systems with incompatible query languages (LDAP, PowerShell, Graph API)
• Technical barriers: Business users wait days for IT to run custom reports or struggle with complex scripts
• Compliance pressure: Auditors demand evidence of access reviews, password policies, and privilege management—often with 24-48 hour turnaround
• No historical tracking: Point-in-time snapshots provide no trending data for capacity planning or anomaly detection
• Security blind spots: Without unified visibility, risky configurations (disabled MFA, stale admin accounts, guest access sprawl) go unnoticed

SimpleAdminReporter addresses all of these by providing a unified interface, zero-code report building, scheduled automation, comprehensive audit trails, and real-time monitoring—all while maintaining enterprise security standards.

What makes this different

• Truly unified platform: First-class support for all three identity systems (AD, Azure AD, M365) in a single application—not bolted-on integrations.
• Zero-code query builder: Drag-and-drop interface with dynamic field discovery—no LDAP queries, no PowerShell, no Graph API complexity required.
• Production-ready from day one: Comprehensive test coverage (130+ tests, 85%+ coverage), structured logging, rate limiting, and security hardening included.
• Real-time observability: WebSocket-powered dashboards stream system health, query performance, and logs without polling or page refreshes.
• Enterprise authentication: Four authentication methods including unified mode supporting both JWT and cookie sessions simultaneously.
• Background job processing: Redis-backed Bull queues prevent UI blocking and support horizontal scaling for heavy workloads.
• Dual CI/CD platforms: Reference implementations for both GitLab CI and GitHub Actions demonstrating best practices for either ecosystem.
• MIT licensed & self-hosted: Complete control over your identity data—no SaaS vendor lock-in, no per-user pricing, no data leaving your network.

What it does (at a glance)

• Unified interface for AD, Azure AD, and Microsoft 365 reporting.
• 59+ pre-built reports you can run immediately (inactive users, password expiry, license usage, Teams activity, risky sign-ins).
• Custom Query Builder with drag-and-drop, advanced filtering (10+ operators), and template sharing—no SQL/LDAP required.
• Scheduled reports with configurable frequency (daily, weekly, monthly) and email delivery for stakeholders.
• One-click export to Excel, CSV, PDF, and JSON with formatting preservation and large dataset support.
• Real-time dashboards with WebSocket updates every 30 seconds for system health, queue status, and execution logs.
• Enterprise security with multi-source auth, RBAC, encrypted credential storage, comprehensive audit trails, and API rate limiting.
• Full-text log search across audit events and system logs with advanced filtering and export capabilities.
• Report history with execution status, performance metrics, and result caching for repeat queries.

Solution flow at a glance

sequenceDiagram
    participant User as Admin / Business User
    participant UI as React UI
    participant API as API Gateway
    participant Queue as Bull Queue
    participant Worker as Background Worker
    participant Data as PostgreSQL / Redis
    participant Directories as AD & Azure APIs

    User->>UI: Configure or schedule report
    UI->>API: Submit request via REST/WebSocket
    API->>Queue: Enqueue reporting job
    Queue->>Worker: Dispatch job for execution
    Worker->>Data: Query cached and persisted data
    Worker->>Directories: Fetch live directory insights
    Directories-->>Worker: Return identity data
    Data-->>Worker: Persist results & audit trail
    Worker-->>API: Publish completion status
    API-->>UI: Push updates and deliver exports
    API-->>User: Provide dashboards, exports, notifications

In short: tasks that used to take hours now take minutes, and teams shift from reactive to proactive
identity governance.

Key features you can use today

Pre-built reports (59+ templates)

Active Directory (15+ reports)

• Inactive Users: Identify accounts not used in X days (configurable threshold) for deprovisioning
• Password Expiry: Users with passwords expiring in next N days for proactive notifications
• Locked Accounts: Currently locked users with lockout timestamps and reason codes
• Disabled Users: All disabled accounts with last modification dates for cleanup audits
• Privileged Users: Members of Domain Admins, Enterprise Admins, Schema Admins, and custom privileged groups
• Password Never Expires: Accounts with non-expiring passwords violating security policies
• Users Without Password Expiry: Service accounts and exceptions requiring review
• Recently Created Users: New accounts in last N days for onboarding verification
• Recently Modified Users: Account changes for change management correlation
• Computer Inventory: All domain-joined computers with OS version, last logon, and location
• Stale Computer Accounts: Computers inactive beyond threshold for cleanup
• Group Membership: Members of specific groups with nested expansion
• Empty Groups: Groups with no members for organizational unit cleanup
• OU Structure: Organizational unit hierarchy with object counts
• Service Accounts: Accounts identified by naming convention or attributes

Azure AD (10+ reports)

• Guest Users: All B2B guest accounts with invitation status and last activity
• MFA Status: Users with MFA enabled/disabled/enforced states for security posture
• Risky Sign-ins: Authentication attempts flagged by Azure AD Identity Protection
• Conditional Access Policies: All CA policies with assigned users/groups and conditions
• License Assignment: Users by license type (E3, E5, F3) with consumption tracking
• Inactive Azure AD Users: Accounts without sign-in activity in X days
• Admin Role Assignments: Users with privileged Azure AD roles (Global Admin, Security Admin, etc.)
• Sign-in Logs: Authentication history with IP addresses, locations, and device details
• Application Permissions: Enterprise apps with granted API permissions and consent type
• Device Inventory: Managed devices with compliance status and OS versions

Microsoft 365 (10+ reports)

• Mailbox Usage: Storage consumption by user with quota thresholds
• OneDrive Storage: Per-user storage with sharing activity and quota status
• Teams Activity: Active teams, member counts, and last activity timestamps
• SharePoint Sites: Site collection inventory with storage, owners, and external sharing settings
• License Utilization: Assigned vs available licenses by SKU for cost optimization
• Inactive Mailboxes: Mailboxes without recent activity for archival consideration
• Shared Mailboxes: All shared mailboxes with delegate access lists
• Distribution Lists: All distribution groups with member counts and owners
• Calendar Permissions: Users with delegate access to calendars
• External Sharing: Files and folders shared with external users

Visual Query Builder

Build custom reports without writing a line of PowerShell or LDAP:

• Dynamic field discovery: Automatically detects available attributes from connected data sources (AD schema, Graph API endpoints)
• Drag-and-drop interface: Select fields, add them to report columns, reorder with mouse
• 10+ filter operators: Equals, not equals, contains, starts with, ends with, greater than, less than, between, in list, regex match
• Multi-condition logic: Combine filters with AND/OR operators for complex queries
• Real-time preview: See sample results (first 10 rows) before running full query
• Template sharing: Save custom reports as templates for team reuse
• Field aliasing: Rename technical field names to business-friendly labels
• Sorting & grouping: Multi-column sorting and group-by aggregation

Example use case: “Show me all users in the Sales OU who haven’t logged in for 90 days AND have mailboxes over 10GB”—built in 60 seconds without scripting.

Scheduling, history & export

• Flexible scheduling: Daily, weekly, monthly, or custom cron expressions
• Email delivery: Automatically send reports to distribution lists with customizable subject lines and body text
• Execution history: Complete audit trail with timestamps, user context, status (success/failure), row counts, and execution time
• Result caching: Recent query results cached for instant retrieval without re-execution
• Export formats:
  • Excel (.xlsx): Formatted with headers, filters, and auto-sized columns
  • CSV: Standard comma-separated for universal compatibility
  • PDF: Formatted tables with pagination and headers for executives
  • JSON: Structured data for API integration and downstream automation
• Large dataset handling: Streaming exports for reports with 10k+ rows without memory exhaustion
• Scheduled cleanup: Automatic purging of old execution history based on retention policies

Monitoring & logs

• Real-time health dashboard: WebSocket updates every 30 seconds showing component status (database, Redis, LDAP, Graph API)
• System metrics: CPU usage, memory consumption, active connections, queue depth
• Query performance: Average execution time, slowest queries, cache hit rates
• Audit logs: User authentication, report execution, configuration changes, permission modifications
• System logs: Application errors, warnings, integration failures, background job status
• Full-text search: Search across all logs with filtering by severity, user, date range, and message content
• Log export: Download filtered logs as CSV or JSON for SIEM integration
• Rate limit monitoring: Track API rate limit consumption per user/IP to prevent throttling

Architecture & technology stack

High-level architecture

The application follows a clean, containerized multi-tier architecture:

• Presentation layer: React SPA served by Nginx reverse proxy with SSL termination and static file caching
• API layer: Node.js/Express REST API with Socket.io WebSocket server for real-time updates
• Business logic layer: Service classes handling authentication, report generation, data access, and external integrations
• Data access layer: Prisma ORM for PostgreSQL, custom LDAP client for Active Directory, Graph SDK for Azure/M365
• Data layer: PostgreSQL 17 for relational data (users, reports, history, logs), Redis 7 for session storage, caching, and job queues
• Background processing: Bull queue workers for async report generation, scheduled jobs, and email delivery

flowchart TD
    Users[Administrators & Analysts] -->|HTTPS| Nginx[NGINX Reverse Proxy]
    Nginx --> SPA[React SPA]
    SPA -->|REST & WebSocket| API[Node.js / Express API]
    API --> Services[Domain Services]
    Services -->|Prisma ORM| PostgreSQL[(PostgreSQL 17)]
    Services -->|Cache & Sessions| Redis[(Redis 7)]
    Services --> Queue[Bull Queues]
    Queue --> Workers[Background Workers]
    Workers --> Exports[Scheduled Exports & Emails]
    Services --> LDAP[[Active Directory]]
    Services --> Graph[[Microsoft Graph API]]
    Services --> SMTP[[SMTP / Email Providers]]

Network isolation

Docker Compose defines two separate networks:

• Frontend network: Nginx and React container accessible from host
• Backend network: API, database, and Redis isolated from external access
• Database security: PostgreSQL and Redis accessible ONLY within Docker network—no host port exposure
• Service mesh: All inter-service communication over internal Docker DNS

Technology stack (detailed)

Frontend

• React 19.1.1: Latest React with concurrent features and automatic batching
• TypeScript 5.9.2: Static typing for compile-time error detection and IDE intelligence
• Ant Design 5.27.0: Enterprise-grade UI component library with 60+ components
• Redux Toolkit 2.8.2: State management with RTK Query for server state and caching
• Vite 7.1.2: Lightning-fast dev server with Hot Module Replacement (HMR) and optimized production builds
• Socket.io Client 4.8.1: WebSocket client for real-time dashboard updates
• Recharts: Composable charting library for data visualization
• React Router 7: Declarative routing with code splitting and lazy loading

Backend

• Node.js 20+: LTS runtime with native fetch, test runner, and performance improvements
• Express.js 5.1.0: Minimalist web framework with middleware ecosystem
• TypeScript 5.9.2: Shared type definitions with frontend for end-to-end type safety
• Prisma 6.14.0: Type-safe ORM with migrations, introspection, and query optimization
• Bull 4.16.5: Redis-based queue for reliable background job processing with retry logic
• Socket.io 4.8.1: WebSocket server with fallback transports and room-based broadcasting
• Winston 3.16.0: Structured logging with transports for file, console, and external log aggregation
• Passport.js: Authentication middleware supporting multiple strategies
• Helmet: Security middleware setting HTTP headers (CSP, HSTS, X-Frame-Options)
• Express Rate Limit: Configurable rate limiting per endpoint/user

Data layer

• PostgreSQL 17: Latest PostgreSQL with parallel query execution, partition improvements, and JSON enhancements
• Redis 7: In-memory data store for session management, caching, and job queues with persistence (AOF + RDB)
• Prisma migrations: Version-controlled schema changes with rollback support
• Connection pooling: Configurable pool sizes for optimal database performance

Integration

• LDAPJS 8.0.9: Pure JavaScript LDAP client for Active Directory queries with connection pooling
• Microsoft Graph Client 3.0.7: Official Graph SDK with automatic retry, throttling, and batch support
• Azure MSAL 3.7.1: Microsoft Authentication Library for OAuth 2.0/OIDC flows
• Nodemailer: Email delivery for scheduled reports with SMTP/OAuth support

Infrastructure

• Docker Compose 2.0+: Multi-container orchestration with environment-specific compose files
• Nginx 1.27: Reverse proxy with SSL termination, static file serving, and load balancing support
• Alpine Linux: Minimal base images (5MB) reducing attack surface and image size
• Multi-stage builds: Separate build and runtime stages for optimized final images

External integrations

• Active Directory: LDAP/LDAPS connection with bind credentials, supports simple bind and SASL
• Azure AD: OAuth 2.0 authorization code flow with PKCE, client credentials for app-only access
• Microsoft 365: Graph API v1.0 and beta endpoints with delegated and application permissions
• SMTP Servers: Support for Office 365, Gmail, SendGrid, and custom SMTP with TLS

Security by design

Multi-source authentication

• LDAP/Active Directory: Bind authentication against on-prem AD with optional LDAPS encryption
• Azure AD OAuth 2.0: Modern authentication with authorization code flow, PKCE, and refresh tokens
• JWT tokens: Stateless authentication with RS256 signing and configurable expiration
• Cookie sessions: HTTP-only, secure, SameSite cookies with server-side session storage in Redis
• Unified authentication: Simultaneous support for both JWT and cookie sessions in same deployment
• Multi-factor authentication: Leverages Azure AD MFA when using OAuth flow

Role-based access control (RBAC)

• Granular permissions: 20+ permissions controlling access to reports, configuration, user management, logs
• Role templates: Pre-defined roles (Admin, Report Manager, Report Viewer, Auditor) with customizable permissions
• User management: Create local users or sync from AD/Azure AD with group-based role assignment
• Row-level security: Users see only reports they created or have been granted access to
• Permission inheritance: Hierarchical permissions with explicit deny support

Data protection

• Encrypted credential storage: AES-256-GCM encryption for stored LDAP/Graph API credentials using application master key
• Secrets management: Environment variables for sensitive config, support for Azure Key Vault and HashiCorp Vault integrations
• Database encryption: PostgreSQL supports TDE (Transparent Data Encryption) for data-at-rest
• TLS in transit: HTTPS for all web traffic, LDAPS for AD connections, TLS for SMTP
• Password hashing: bcrypt with configurable cost factor (default 12 rounds)

Audit logging

• Comprehensive event tracking: Authentication attempts, report execution, configuration changes, permission modifications, export actions
• Immutable logs: Append-only log tables with database constraints preventing modification
• Contextual information: User identity, IP address, user agent, timestamp, request ID for correlation
• Log retention: Configurable retention policies with automatic archival to object storage
• SIEM integration: Export logs as JSON or syslog format for Splunk, ELK, Sentinel ingestion

API security

• Rate limiting:
  • General endpoints: 100 requests per 15 minutes per IP
  • Authentication: 10 login attempts per 15 minutes per IP
  • Report generation: 30 reports per minute per user
  • Log exports: 5 exports per 10 minutes per user
• CSRF protection: Double-submit cookie pattern for state-changing operations
• Security headers: Content Security Policy, HSTS, X-Frame-Options, X-Content-Type-Options
• Input validation: Schema-based validation with Joi/Zod for all API inputs
• SQL injection prevention: Parameterized queries via Prisma ORM
• LDAP injection prevention: Input sanitization for special characters in LDAP filters

Real-time observability

Health monitoring

The application surfaces component health and query metrics in real time via WebSocket connections:

• Component status: Database connection, Redis availability, LDAP connectivity, Graph API reachability
• Update frequency: Health checks pushed to connected clients every 30 seconds
• Visual indicators: Color-coded status (green/yellow/red) with last check timestamp
• Degraded mode: Application continues operating with reduced functionality when dependencies fail

Performance metrics

• Query execution time: Histogram of report generation times (p50, p95, p99 latencies)
• Cache hit rate: Percentage of queries served from cache vs fresh execution
• Queue depth: Pending background jobs awaiting processing
• Active connections: Current WebSocket connections and HTTP sessions
• Memory usage: Node.js heap utilization and garbage collection metrics
• Database pool: Active/idle connections, wait time, query queue length

Structured logging

Winston-based logging with multiple transports:

• Log levels: Error, warn, info, debug with environment-based configuration
• Structured format: JSON logs with consistent fields (timestamp, level, message, metadata, context)
• Request correlation: Unique request IDs for tracing operations across logs
• Transports: Console for development, file rotation for production, syslog for SIEM integration
• Performance impact: Async logging to avoid blocking event loop

Who benefits

IT administrators

• Reduce manual work: Fewer custom PowerShell scripts, faster answers to routine questions
• Consistent exports: Standardized report formats for compliance and change management
• Self-service delegation: Empower teams to run approved reports without opening tickets
• Troubleshooting: Real-time logs and health monitoring for faster incident response

Security & compliance teams

• Audit readiness: Pre-built compliance reports for SOX, HIPAA, PCI-DSS requirements
• Evidence collection: Scheduled exports automatically generate monthly access reviews
• Privileged access monitoring: Track admin account usage and permission changes
• Immutable audit trails: Complete history of who ran what reports when

Business users

• Self-service reporting: Run approved reports without IT bottleneck (with proper permissions)
• Zero training required: Visual query builder requires no technical knowledge
• Scheduled delivery: Receive weekly/monthly reports automatically via email
• Executive dashboards: PDF exports formatted for leadership consumption

MSPs & consultancies

• Multi-tenant ready: Architecture supports deployment per client with isolated data
• Standardized deliverables: Consistent reporting across customer base
• Client portals: RBAC enables client access to their own reports
• Rapid deployment: 15-minute setup per customer using Docker Compose

Deployment scenarios

Single-server deployment (small/medium organizations)

Target: 100-1,000 users, single location, on-prem or cloud VM
Requirements: 4-core CPU, 8GB RAM, 50GB storage, Docker installed
Architecture: All containers (frontend, backend, database, Redis) on single host
Deployment time: 15 minutes using docker-compose.yml

High-availability deployment (enterprise)

Target: 1,000+ users, multiple locations, business-critical
Requirements: Load balancer, 2+ app servers, external PostgreSQL cluster, Redis Sentinel
Architecture:

• Load balancer (HAProxy/Nginx) distributes traffic across API servers
• Stateless API containers (2-4 instances) with session affinity disabled
• Managed PostgreSQL (Azure Database, AWS RDS, or self-hosted with streaming replication)
• Redis Sentinel cluster for HA session storage and queue management
• Shared NFS/object storage for exported reports

Deployment time: 2-4 hours including infrastructure provisioning

Cloud-native deployment (Azure/AWS/GCP)

Target: Elastic scaling, managed services, minimal ops overhead
Components:

• Compute: Azure Container Instances, AWS ECS/Fargate, or GCP Cloud Run
• Database: Azure Database for PostgreSQL, AWS RDS, or Cloud SQL
• Cache: Azure Cache for Redis, ElastiCache, or Memorystore
• Load balancing: Azure Application Gateway, ALB, or Cloud Load Balancing
• Secrets: Azure Key Vault, AWS Secrets Manager, or Secret Manager
• Monitoring: Azure Monitor, CloudWatch, or Cloud Monitoring

Benefits: Auto-scaling, managed backups, built-in HA, simplified patching

Development environment

Target: Local development, feature testing, CI/CD validation
Requirements: Docker Desktop (Windows/macOS) or Docker Engine (Linux)
Commands:

docker-compose -f docker-compose.dev.yml up -d

Features: Hot reload for code changes, debug ports exposed, seed data included

Performance benchmarks

Report generation times

• Small reports (<1,000 rows): 0.5-2 seconds (cached: <100ms)
• Medium reports (1,000-10,000 rows): 2-8 seconds
• Large reports (10,000-100,000 rows): 8-30 seconds with streaming export
• Complex LDAP queries: 3-15 seconds depending on filter complexity and domain size
• Graph API queries: 2-10 seconds with automatic pagination for large result sets

Concurrent user capacity

• Single-server (4-core, 8GB RAM): 50-100 concurrent users generating reports
• HA deployment (2×4-core): 200-300 concurrent users
• Dashboard viewers: 500+ simultaneous WebSocket connections on single instance

Resource consumption

• Backend API (idle): ~200MB RAM, <5% CPU
• Backend API (active): ~500MB RAM, 30-60% CPU (per core)
• PostgreSQL: ~300MB RAM base + query cache
• Redis: ~50MB RAM for session storage, scales with user count
• Frontend (Nginx): ~20MB RAM, negligible CPU

Comparison with alternatives

CI/CD & DevOps practices

Dual CI/CD platforms

The repository includes reference implementations for both major CI/CD platforms:

GitLab CI (primary)

• Modular pipeline templates: Reusable job definitions in .gitlab/ci/ directory
• Seven stages: Build → Test → Security Scan → Package → Deploy Staging → Integration Tests → Deploy Production
• Security scanning: SAST (Semgrep), dependency scanning (npm audit), container scanning (Trivy), secrets detection (Gitleaks)
• Artifact management: Docker images stored in GitLab Container Registry with tag-based versioning
• Environment-specific deployments: Separate jobs for dev/staging/production with manual approval gates

GitHub Actions (secondary)

• Simplified workflows: Single-file workflows in .github/workflows/
• Matrix builds: Test across Node.js 18/20/22 and multiple OS (Linux/Windows/macOS)
• CodeQL integration: Automated security analysis on pull requests
• Dependabot: Automatic dependency updates with security advisories
• Composite actions: Reusable action definitions for Docker build/push

Testing pyramid

• Unit tests: 130+ tests covering business logic, utilities, and services (85%+ coverage)
• Integration tests: API endpoint testing with supertest, database integration with test containers
• E2E tests: Playwright browser tests covering critical user flows (login, report generation, export)
• Contract tests: Validate Graph API and LDAP integration assumptions

Code quality

• ESLint: TypeScript-aware linting with strict rules
• Prettier: Automated code formatting enforced via pre-commit hooks
• Husky: Git hooks preventing commits without passing lint/tests
• Type coverage: 100% TypeScript with strict mode enabled

Roadmap (highlights)

Near-term (Q2 2025)

• Enhanced PDF export: Custom templates with logos, headers/footers, and branded styling
• Responsive UI: Mobile-optimized interface for report viewing on tablets/phones
• Report sharing: Generate secure links for external stakeholders with expiration
• Advanced filtering: Saved filter sets and filter templates for common scenarios

Mid-term (Q3-Q4 2025)

• Multi-factor authentication: TOTP/SMS-based MFA for local accounts
• Advanced analytics: Trend analysis, anomaly detection, and predictive insights
• SIEM integration: Push audit logs to Splunk, ELK, Microsoft Sentinel via native connectors
• Custom data sources: Plugin architecture for integrating non-Microsoft systems (ServiceNow, Okta, Salesforce)

Long-term (2026)

• Multi-tenant architecture: SaaS-ready deployment with tenant isolation and custom branding
• Machine learning: Automated anomaly detection for unusual access patterns
• Workflow automation: Trigger actions based on report results (e.g., auto-disable inactive accounts)
• API marketplace: Community-contributed report templates and integrations

Getting started (15 minutes to dashboard)

Prerequisites

Before beginning, ensure you have:

• Docker 20.10+ with Docker Compose 2.0+ installed and running
• Git for repository cloning
• Windows WSL2 (for Windows users) or native Linux/macOS environment
• 4GB RAM minimum (8GB recommended for production workloads)
• 10GB available disk space for images, database, and logs
• Network access to Active Directory (LDAP/LDAPS port 389/636) and Azure AD (HTTPS 443) if using those integrations
• Service accounts:
  • Active Directory: Domain user with read permissions (or dedicated service account)
  • Azure AD: Application registration with User.Read.All, Group.Read.All, Directory.Read.All permissions

Installation steps

1. Clone repository

git clone https://github.com/ilyafedotov-ops/SimpleAdminReporter
cd SimpleAdminReporter

2. Configure environment

cp .env.example .env
nano .env  # or use your preferred editor

Required environment variables:

# Database
DATABASE_URL="postgresql://admin:changeme@postgres:5432/reporter"

# Redis
REDIS_URL="redis://redis:6379"

# Application secrets
JWT_SECRET="generate-a-random-32-char-string-here"
ENCRYPTION_KEY="generate-another-random-32-char-string"

# Optional: Active Directory
AD_URL="ldap://dc.example.com:389"
AD_BIND_DN="CN=Service Account,OU=Users,DC=example,DC=com"
AD_BIND_PASSWORD="your-service-account-password"
AD_BASE_DN="DC=example,DC=com"

# Optional: Azure AD
AZURE_TENANT_ID="your-tenant-id"
AZURE_CLIENT_ID="your-app-registration-client-id"
AZURE_CLIENT_SECRET="your-client-secret"

# Optional: SMTP for scheduled report delivery
SMTP_HOST="smtp.office365.com"
SMTP_PORT="587"
SMTP_USER="reports@example.com"
SMTP_PASSWORD="your-email-password"

3. Build and launch containers

docker-compose build
docker-compose up -d

# Verify all containers are running
docker-compose ps

Expected output:

NAME                STATUS              PORTS
frontend            Up 30 seconds       80/tcp, 0.0.0.0:80->80/tcp
backend             Up 30 seconds       3000/tcp
postgres            Up 30 seconds       5432/tcp
redis               Up 30 seconds       6379/tcp

4. Initialize database

# Run Prisma migrations to create tables
docker-compose exec backend npm run prisma:migrate

# Seed database with sample reports (optional)
docker-compose exec backend npm run prisma:seed

5. Create admin user

# Generate initial admin credentials
docker-compose exec backend npm run reset-admin-password

# Output will show:
# Admin user created successfully!
# Username: admin
# Password: [randomly-generated-password]
# IMPORTANT: Change this password after first login!

6. Access application

Open browser to http://localhost and login with admin credentials.

Verify deployment

After login, verify functionality:

1. Dashboard: Check system health shows all components green
2. Pre-built reports: Navigate to Reports → Pre-built and run “Active Directory – All Users” test report
3. Custom query: Try the Query Builder to create a simple custom report
4. Logs: Verify audit logs show your login and report execution
5. Export: Download a report as Excel to confirm export functionality

Next steps

1. Change admin password: Navigate to User Settings and update default password
2. Configure data sources: Settings → Data Sources → Add your AD/Azure AD credentials
3. Test connectivity: Settings → Data Sources → Test Connection for each source
4. Create users: Settings → User Management → Create additional users with appropriate roles
5. Schedule reports: Pick a pre-built report → Click Schedule → Configure frequency and recipients
6. Customize reports: Clone a pre-built report and modify fields/filters to match your needs
7. Set up SSL: Configure Nginx with your SSL certificate (see docs/SSL-SETUP.md)
8. Review security: Audit default RBAC roles and adjust permissions per your security policy

Troubleshooting & FAQ

Containers fail to start

Symptoms: docker-compose ps shows containers exiting or restarting
Diagnosis:

docker-compose logs backend
docker-compose logs postgres

Common causes:

• Port conflicts: Port 80 already in use → Change ports in docker-compose.yml
• Database connection failure: Check DATABASE_URL in .env matches postgres service name
• Missing environment variables: Verify required vars (JWT_SECRET, ENCRYPTION_KEY) are set

Cannot connect to Active Directory

Symptoms: “LDAP connection timeout” or “Invalid credentials” errors
Diagnosis:

# Test LDAP connectivity from backend container
docker-compose exec backend npm run test-ldap

Solutions:

• Network access: Ensure Docker containers can reach AD server (may need network_mode: host for on-prem)
• Credentials: Verify AD_BIND_DN and AD_BIND_PASSWORD are correct
• LDAPS certificate: For LDAPS, add AD CA certificate to backend container
• Firewall: Verify port 389 (LDAP) or 636 (LDAPS) is open from Docker host to AD

Azure AD authentication fails

Symptoms: “AADSTS” error codes during login
Common errors:

• AADSTS50011 (redirect mismatch): Add http://localhost/auth/callback to app registration redirect URIs
• AADSTS65001 (consent required): Grant admin consent for API permissions in Azure portal
• AADSTS700016 (invalid client): Verify AZURE_CLIENT_ID and AZURE_CLIENT_SECRET match app registration

Reports timeout or take too long

Symptoms: Report generation exceeds 60 seconds or fails
Solutions:

• Optimize LDAP filters: Add indexed attributes (sAMAccountName, mail) to filters
• Limit result size: Add row limit in query builder (e.g., max 10,000 rows)
• Enable caching: Settings → Performance → Enable query result caching
• Increase timeout: Edit .env → REPORT_TIMEOUT_MS=120000 (120 seconds)
• Background processing: Large reports automatically queue—check queue status in dashboard

How do I backup the database?

# Backup PostgreSQL to file
docker-compose exec postgres pg_dump -U admin reporter > backup_$(date +%Y%m%d).sql

# Restore from backup
docker-compose exec -T postgres psql -U admin reporter < backup_20250101.sql

For production, configure automated backups using PostgreSQL's built-in backup tools or managed database snapshots.

Can I run this in Kubernetes?

Yes! The application is stateless (sessions in Redis) and supports horizontal scaling. Example Helm chart:

• Deployment: 2+ backend replicas with readiness/liveness probes
• Service: ClusterIP service with session affinity (for WebSockets)
• Ingress: Nginx ingress with TLS termination
• External services: PostgreSQL StatefulSet or managed database (Azure Database, RDS)
• Redis: Redis Sentinel StatefulSet for HA session storage

Community Helm chart: charts/simpleadminreporter/ (coming Q2 2025)

What are the licensing implications?

SimpleAdminReporter: MIT License—free for commercial use, modification, distribution
Dependencies: All dependencies use permissive licenses (MIT, Apache 2.0, BSD)
Microsoft Graph: Requires appropriate Microsoft 365 licenses (E3/E5) for users being queried
Active Directory: No additional licensing required beyond existing Windows Server licenses

How do I enable HTTPS/SSL?

1. Obtain SSL certificate (Let's Encrypt, commercial CA, or self-signed for testing)
2. Place certificate files in nginx/ssl/ directory
3. Edit nginx/nginx.conf to enable SSL configuration block
4. Update .env with FRONTEND_URL=https://your-domain.com
5. Restart containers: docker-compose restart

Detailed guide: docs/SSL-SETUP.md

Can I customize the UI (logo, colors, branding)?

Yes! The frontend supports theming:

• Logo: Replace frontend/src/assets/logo.png
• Colors: Edit frontend/src/theme.ts (primary color, accent, backgrounds)
• Company name: Update COMPANY_NAME in .env
• Rebuild: docker-compose build frontend

Multi-tenant branding (tenant-specific logos/colors) planned for 2026 roadmap.

Project status & license

SimpleAdminReporter is production-ready (version 1.0.0) with comprehensive testing, CI/CD pipelines,
environment templates, and Docker Compose deployment files. The application has been deployed in real-world environments
serving 100-1,000 user organizations.

The project is licensed under MIT License, making it free for commercial use, modification, and distribution.
Contributions welcome via GitHub pull requests.

Current status:

• ✅ Core functionality complete and stable
• ✅ 85%+ test coverage with 130+ tests
• ✅ Security hardening and audit logging implemented
• ✅ Docker Compose deployment validated across Linux/Windows WSL2/macOS
• ✅ Documentation complete (README, API docs, deployment guides)
• 🚧 Kubernetes Helm chart (Q2 2025)
• 🚧 Mobile-responsive UI (Q2 2025)

Closing thoughts

If admin reporting across AD, Azure AD, or Microsoft 365 is a headache in your environment, SimpleAdminReporter can make it fast,
flexible, and user-friendly. It's built to scale with modern stack components and empower business teams with self-service capabilities
while maintaining enterprise security standards.

Key takeaways:

• 59+ pre-built reports eliminate months of script development
• Zero-code query builder democratizes reporting beyond IT teams
• Real-time monitoring and audit trails provide operational visibility
• Production-ready architecture with 85%+ test coverage and dual CI/CD platforms
• MIT license provides complete control and customization freedom

Whether you're an IT administrator drowning in report requests, a compliance officer preparing for audits,
or an MSP standardizing deliverables across clients—SimpleAdminReporter provides the foundation for proactive
identity governance.

Explore the project here:
github.com/ilyafedotov-ops/SimpleAdminReporter