Installation Guide

Get Started with IdentityHealthCheck

Deploy in minutes with Windows Installer or PowerShell. Read-only assessment—no system modifications, ever.

System Requirements

IdentityHealthCheck runs entirely in your environment. No cloud data transfer required.

Operating System

  • Windows Server 2016+
  • Windows 10/11 Pro/Enterprise
  • Ubuntu 20.04+ / Debian 11+
  • RHEL 8+ / CentOS Stream 8+
  • macOS 12+ (Monterey)

Hardware

  • CPU: 2+ cores (4 recommended)
  • RAM: 4GB minimum (8GB recommended)
  • Disk: 10GB free space
  • Network: HTTPS outbound to identity platforms

Software

  • PowerShell 5.1+ / PowerShell 7+
  • .NET 6.0 Runtime (Windows installer)
  • Python 3.9+ (optional, for scripts)

Permissions

  • AD: Domain User (read-only)
  • Entra ID: Global Reader role
  • AWS: IAM ReadOnlyAccess policy
  • Okta: Read-only Admin API token

Read-Only Guarantee

IdentityHealthCheck uses read-only API permissions only. No write operations, no configuration changes, no data modifications. Safe for production environments.

Windows Installer

Native Windows installation with GUI setup wizard. Ideal for Windows-only environments.

1

Download the Installer

Download from your customer portal or request access:

Customer Portal Request Access
2

Run as Administrator

Right-click IdentityHealthCheck-Setup.exe and select "Run as administrator". Follow the setup wizard.

3

Enter License Key

Your license key was provided via email. Enter it during setup or in Settings after installation.

4

Configure Windows Service (Optional)

For scheduled assessments, install as a Windows Service:

# Install as Windows Service (Run as Administrator) sc create IdentityHealthCheck binPath= "C:\Program Files\IdentityFirst\IdentityHealthCheck.exe --service" start= auto sc description IdentityHealthCheck "IdentityHealthCheck Identity Security Assessment Service" sc start IdentityHealthCheck

PowerShell Module

Command-line interface for automation, scripting, and CI/CD integration.

1

Install from PowerShell Gallery

# Install the module Install-Module -Name IdentityHealthCheck -Scope CurrentUser # Import and verify Import-Module IdentityHealthCheck Get-Command -Module IdentityHealthCheck
2

Configure License

# Set license key (persists across sessions) Set-IHCLicense -LicenseKey "your-license-key" # Verify license Get-IHCLicenseStatus
3

Run Quick Assessment

# Scan Active Directory (current domain) Invoke-IHCAssessment -Platform ActiveDirectory -OutputPath "C:\Reports" # Scan Entra ID (Azure AD) Connect-IHCEntraID -TenantId "your-tenant-id" -ClientId "your-client-id" Invoke-IHCAssessment -Platform EntraID -OutputPath "C:\Reports" # Full multi-platform scan Invoke-IHCAssessment -Platform All -OutputPath "C:\Reports" -Format PDF,JSON,HTML

Python Installation

Lightweight, cross-platform deployment using Python. Perfect for SMEs wanting maximum flexibility with zero licensing costs.

Cost-Effective for SMEs

Python is completely free and open source. No container licensing, no subscription fees for runtime. Runs on any platform—Windows, Linux, or macOS—with minimal resource requirements.

1

Install Python 3.9+

Download Python from python.org or use your package manager:

# Windows (PowerShell) - Using winget winget install Python.Python.3.12 # Or download from: https://www.python.org/downloads/ # Ensure "Add Python to PATH" is checked during installation # Verify installation python --version
2

Install IdentityHealthCheck Package

# Create virtual environment (recommended) python -m venv ihc-env # Activate virtual environment # Windows: ihc-env\Scripts\activate # Linux/macOS: # source ihc-env/bin/activate # Install IdentityHealthCheck pip install identityhealthcheck # Verify installation ihc --version
3

Configure and Run

# Set license key ihc config set license YOUR-LICENSE-KEY # Quick scan of Active Directory ihc scan --platform ad --output ./reports # Scan Entra ID ihc scan --platform entra --tenant-id YOUR-TENANT-ID --output ./reports # Full multi-platform assessment ihc scan --platform all --output ./reports --format pdf,html,json
4

Schedule Automated Scans (Optional)

Use Windows Task Scheduler or cron for regular assessments:

# Windows - Create scheduled task (PowerShell as Admin) $action = New-ScheduledTaskAction -Execute "python" -Argument "-m identityhealthcheck scan --platform all --output C:\Reports" $trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Monday -At 6am Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "IdentityHealthCheck Weekly Scan" # Linux/macOS - Add to crontab # crontab -e # 0 6 * * 1 /path/to/ihc-env/bin/ihc scan --platform all --output /reports

SME Tip

For the simplest setup, download our all-in-one Python installer which bundles Python and all dependencies. Single click deployment—no command line required. Request the bundled installer.

Container Deployments — Coming Soon

Docker and Kubernetes deployment options are on our roadmap for organisations requiring containerised infrastructure.

Docker

Single container and Docker Compose deployments for development and testing environments.

Kubernetes

Helm charts and K8s manifests for enterprise-scale orchestrated deployments.

Interested in container deployments? Register your interest and we'll notify you when these options become available.

Platform Connector Setup

Configure read-only access to your identity platforms.

Active Directory

Requires: Domain User account with read access to AD objects. No special permissions needed—standard user is sufficient.

Microsoft Entra ID (Azure AD)

Requires: App Registration with Microsoft Graph API permissions (Directory.Read.All, AuditLog.Read.All). Global Reader role recommended.

Setup Guide

AWS IAM

Requires: IAM User or Role with ReadOnlyAccess policy. Cross-account access supported via IAM roles.

Setup Guide

Okta

Requires: API Token with Read-only Admin scope. Created in Okta Admin Console → Security → API.

Setup Guide

Google Cloud IAM

Requires: Service Account with Viewer role on organisation/projects. Workspace Admin SDK access for Workspace assessment.

Setup Guide

Your First Scan

Run your first assessment and understand your results.

1

Select Platforms

Choose which identity platforms to assess. Start with one (e.g., Active Directory) for fastest results.

2

Start Assessment

Click "Start Assessment" or run Invoke-IHCAssessment. Typical scan time: 15-45 minutes depending on environment size.

3

Review Findings

Your report includes:

  • Health Score: 0-100 overall security rating
  • Findings: Prioritised by Critical, High, Medium, Low
  • Remediation: Step-by-step fix instructions
  • Compliance: NIST, ISO 27001, CIS Controls mapping
4

Export Reports

Download in PDF (executive), HTML (interactive), JSON/CSV (integration), or DOCX (documentation) formats.

View Sample Report

Troubleshooting

Connection Timeout

Symptom: "Connection timed out" when scanning AD or Entra ID.

Solution: Verify network connectivity to domain controllers or Microsoft Graph API. Check firewall rules allow LDAPS (636) and HTTPS (443).

Permission Denied

Symptom: "Access denied" or "Insufficient permissions" errors.

Solution: Verify the service account has required read permissions. For Entra ID, ensure API permissions are granted admin consent.

License Validation Failed

Symptom: "Invalid license" or "License expired" message.

Solution: Check license key for typos. Ensure system clock is accurate (NTP sync). Contact support if issue persists.

Full Documentation

For detailed troubleshooting, API reference, and advanced configuration, visit our documentation portal.

Support

Need help with installation? Our team is here to assist.

Email Support

support@identityfirst.net

Response within 24 hours

Phone Support

+44 (0) 7968 169 571

Mon-Fri, 9am-5pm GMT

WhatsApp Community

Join our community

Peer support & tips

Assisted Setup

Book a session

Free for Enterprise customers

Ready to Secure Your Identities?

Deploy IdentityHealthCheck today and get your first security assessment in under an hour.