modules/Definitions/ActiveDirectory.Entro.psm1

Set-StrictMode -Version Latest

$script:ProbeModule = Join-Path (Split-Path $PSScriptRoot -Parent) 'IW.OnPremProbe.psm1'
Import-Module $script:ProbeModule -Force -WarningAction SilentlyContinue

function Get-EntroAdLdapsPorts {
    @(
        @{ Name = 'LDAP'; Port = 389 }
        @{ Name = 'LDAPS'; Port = 636 }
        @{ Name = 'Global Catalog'; Port = 3268 }
        @{ Name = 'Global Catalog SSL'; Port = 3269 }
    )
}

function Export-EntroLdapsRootCaPem {
    param(
        [Parameter(Mandatory)][string]$Fqdn,
        [int]$Port = 636
    )
    $tcp = [System.Net.Sockets.TcpClient]::new()
    try {
        $tcp.Connect($Fqdn, $Port)
        $ssl = [System.Net.Security.SslStream]::new($tcp.GetStream(), $false, { param($sender, $certificate, $chain, $errors) $true })
        $ssl.AuthenticateAsClient($Fqdn)
        $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($ssl.RemoteCertificate)
        $chain = [System.Security.Cryptography.X509Certificates.X509Chain]::new()
        [void]$chain.Build($cert)
        $root = $chain.ChainElements[$chain.ChainElements.Count - 1].Certificate
        $b64 = [Convert]::ToBase64String($root.RawData, [Base64FormattingOptions]::InsertLineBreaks)
        "-----BEGIN CERTIFICATE-----`n$b64`n-----END CERTIFICATE-----"
    }
    finally {
        $tcp.Dispose()
    }
}

function Test-ActiveDirectoryEntroCheck {
    param($Context, [bool]$WhatIf)
    $missing = [System.Collections.Generic.List[string]]::new()
    $met = [System.Collections.Generic.List[string]]::new()
    $manual = [System.Collections.Generic.List[string]]::new()
    $fqdn = [string]$Context['DcFqdn']
    if ([string]::IsNullOrWhiteSpace($fqdn)) { $missing.Add('DcFqdn') }
    else {
        try {
            [void][System.Net.Dns]::GetHostAddresses($fqdn)
            $met.Add("DNS $fqdn")
        }
        catch { $missing.Add("DNS $fqdn") }
        foreach ($row in Get-EntroAdLdapsPorts) {
            $label = "$($row.Name) $($fqdn):$($row.Port)"
            if ($WhatIf) { $manual.Add($label) }
            elseif (Test-OnPremTcpPort -HostName $fqdn -Port ([int]$row.Port)) { $met.Add($label) }
            else { $missing.Add($label) }
        }
    }
    if (-not [System.OperatingSystem]::IsWindows()) {
        $manual.Add('Service account creation requires a domain-joined Windows host with the ActiveDirectory module')
    }
    elseif (-not (Get-Module -ListAvailable -Name ActiveDirectory)) {
        $manual.Add('ActiveDirectory module is not installed on this host')
    }
    else { $met.Add('ActiveDirectory module') }
    $verdict = if ($missing.Count -gt 0) { 'Fail' } elseif ($manual.Count -gt 0) { 'Review' } else { 'Pass' }
    @{
        Subject       = @{ Kind = 'ActiveDirectory'; Label = 'On-prem Active Directory'; Name = $fqdn; Note = 'Read-only probe. The service account was not created.'; Readable = $true; ReadableFamilies = @() }
        Verdict       = $verdict
        AttemptedRead = -not $WhatIf
        Found         = $true
        Required      = @('DNS', 'LDAPS 636', 'ActiveDirectory module')
        Met           = @($met)
        Missing       = @($missing)
        Manual        = @($manual)
        PurposeMap    = @{
            'DNS'                    = 'The Worker Group can resolve the domain controller'
            'LDAPS 636'              = 'Entro binds over LDAPS'
            'ActiveDirectory module' = 'This host can create the read-only service account'
        }
        ReadNote      = "Checked $fqdn from $([Environment]::MachineName)."
    }
}

function Register-ActiveDirectoryEntroDefinitions {
    $runRequired = { param($c) [string]$c['Action'] -eq 'Run' }
    Register-IntegrationWizardDefinition @{
        Id            = 'on-prem-active-directory-entro'
        Platform      = 'OnPremActiveDirectory'
        Product       = 'Entro'
        CoreSwitch    = 'Entro'
        CliName       = 'pwsh'
        Title         = 'Entro on-prem Active Directory'
        FolderName    = 'Entro-On-Prem-Active-Directory'
        RequiredTools = @('ActiveDirectory module (RSAT) on a domain-joined Windows host')
        AccessLevels  = @()
        AdminRoles    = @('Account operator on a domain-joined Windows host (create a user, do not grant admin roles)')
        OutputsHelp   = @'
Paste into Entro (Management -> Accounts & Integrations -> Active Directory):
Nickname, Domain Controller, DC FQDN, Domain, Username (UPN), Password, Root CA PEM from root-ca.pem, Environment Nickname, Environment Type, and the Outpost Worker Group.
The service account is read-only. Do not add it to Domain Admins or other admin groups.
'@

        TargetHost    = @{
            Role  = 'Active Directory domain controller or domain-joined Windows host'
            Notes = 'Create svc_entro here. The Outpost Worker Group must reach the DC on LDAP 389, LDAPS 636, and Global Catalog 3268/3269.'
            Assert = {
                param($c)
                if (-not [System.OperatingSystem]::IsWindows()) {
                    throw 'On-prem Active Directory setup must run on a domain-joined Windows host. Use BuildScript and run the .ps1 there.'
                }
                if (-not (Get-Module -ListAvailable -Name ActiveDirectory)) {
                    throw 'The ActiveDirectory module is not installed. Install RSAT Active Directory tools, or run the generated script on a host that has them.'
                }
            }
            AssertScript = @'
if (-not [System.OperatingSystem]::IsWindows()) { throw 'Run this script on a domain-joined Windows host.' }
if (-not (Get-Module -ListAvailable -Name ActiveDirectory)) { throw 'Install the ActiveDirectory RSAT module first.' }
'@

        }
        Inputs        = @(
            @{ Name = 'Nickname'; Source = 'Supply'; Prompt = 'Nickname in Entro'; Purpose = 'Label for this directory'; Required = $true }
            @{ Name = 'DomainController'; Source = 'Supply'; Prompt = 'Domain controller short name or IP'; Purpose = 'Value for the Entro Domain Controller field'; Required = $true }
            @{ Name = 'DcFqdn'; Source = 'Supply'; Prompt = 'Domain controller FQDN'; Purpose = 'For example dc01.example.local'; Required = $true }
            @{ Name = 'Domain'; Source = 'Supply'; Prompt = 'AD DNS domain'; Purpose = 'For example example.local'; Required = $true }
            @{ Name = 'SamAccountName'; Source = 'Supply'; Prompt = 'Service account sAMAccountName'; Purpose = 'Read-only bind account'; Default = 'svc_entro'; Required = $false }
            @{ Name = 'EnvironmentNickname'; Source = 'Supply'; Prompt = 'Environment nickname'; Purpose = 'Entro environment label'; Required = $true }
            @{ Name = 'EnvironmentType'; Source = 'Supply'; Prompt = 'Environment type'; Purpose = 'Production, Staging, or Dev'; ValidateSet = @('Production', 'Staging', 'Dev'); Default = 'Dev'; Required = $false }
            @{ Name = 'WorkerGroup'; Source = 'Supply'; Prompt = 'Entro Outpost Worker Group'; Purpose = 'Worker Group that will query this domain'; Required = $false }
            @{ Name = 'Password'; Source = 'Supply'; Prompt = 'Service account password'; Purpose = 'Password for the read-only bind account'; Secret = $true; When = $runRequired; Required = $runRequired }
            @{ Name = 'OutputDirectory'; Source = 'Supply'; Prompt = 'Output directory'; Purpose = 'Wizard output directory'; Required = $false }
        )
        CheckInputs   = @(
            @{ Name = 'DcFqdn'; Source = 'Supply'; Prompt = 'Domain controller FQDN'; Purpose = 'DC to probe'; Required = $true }
            @{ Name = 'Domain'; Source = 'Supply'; Prompt = 'AD DNS domain'; Purpose = 'Domain name'; Required = $false }
            @{ Name = 'OutputDirectory'; Source = 'Supply'; Prompt = 'Output directory'; Purpose = 'Wizard output directory'; Required = $false }
        )
        CheckProbe    = { param($ctx, $whatIf) Test-ActiveDirectoryEntroCheck -Context $ctx -WhatIf:$whatIf }
        Steps         = {
            param($ctx)
            $sam = if ($ctx['SamAccountName']) { [string]$ctx['SamAccountName'] } else { 'svc_entro' }
            @(
                @{
                    Id     = 'entro-ad-network'
                    Title  = 'Confirm Outpost reachability to the domain controller'
                    Kind   = 'Manual'
                    Why    = 'Entro queries AD from the Outpost, over LDAP, LDAPS, and the Global Catalog.'
                    Manual = "From the Outpost host, resolve $($ctx['DcFqdn']) and open TCP 389, 636, 3268, and 3269. DNS uses UDP 53."
                }
                @{
                    Id    = 'entro-ad-account'
                    Title = "Create read-only account $sam"
                    Kind  = 'Ensure'
                    Why   = 'Entro binds as a normal user. Do not grant admin roles.'
                    Probe = { param($c) 'Create' }
                    Run   = {
                        param($c)
                        $account = if ($c['SamAccountName']) { [string]$c['SamAccountName'] } else { 'svc_entro' }
                        $domain = [string]$c['Domain']
                        $upn = "$account@$domain"
                        Import-Module ActiveDirectory -ErrorAction Stop
                        $existing = Get-ADUser -Filter "SamAccountName -eq '$account'" -ErrorAction SilentlyContinue
                        if ($existing) {
                            Write-Ok "$account already exists ($($existing.DistinguishedName)). It was not modified and was not added to any admin group."
                        }
                        else {
                            $secure = ConvertTo-SecureString ([string]$c['Password']) -AsPlainText -Force
                            New-ADUser -Name $account -SamAccountName $account -UserPrincipalName $upn -AccountPassword $secure -Enabled $true -PasswordNeverExpires $true -CannotChangePassword $true
                            Write-Ok "Created $upn. No admin group membership was added."
                        }
                        $c['ServiceUpn'] = $upn
                    }
                    BuildScript = {
                        param($c)
                        @'
if ([string]::IsNullOrWhiteSpace($Password)) { $Password = Read-Host 'Service account password' }
$account = if ($SamAccountName) { $SamAccountName } else { 'svc_entro' }
$upn = "$account@$Domain"
Import-Module ActiveDirectory -ErrorAction Stop
$existing = Get-ADUser -Filter "SamAccountName -eq '$account'" -ErrorAction SilentlyContinue
if ($existing) {
    Write-Host "$account already exists. It was not modified and was not added to any admin group."
} else {
    $secure = ConvertTo-SecureString $Password -AsPlainText -Force
    New-ADUser -Name $account -SamAccountName $account -UserPrincipalName $upn -AccountPassword $secure -Enabled $true -PasswordNeverExpires $true -CannotChangePassword $true
    Write-Host "Created $upn. No admin group membership was added."
}
'@

                    }
                }
                @{
                    Id    = 'entro-ad-ca'
                    Title = 'Export the LDAPS root CA as PEM'
                    Kind  = 'Ensure'
                    Why   = 'Entro wants the root CA text, including the BEGIN and END lines, not a file upload.'
                    Probe = { param($c) 'Create' }
                    Run   = {
                        param($c)
                        $pem = Export-EntroLdapsRootCaPem -Fqdn ([string]$c['DcFqdn']) -Port 636
                        $dir = if ($c['OutputDirectory']) { [string]$c['OutputDirectory'] } else { (Get-Location).Path }
                        $path = Join-Path $dir 'root-ca.pem'
                        Set-Content -LiteralPath $path -Value $pem -Encoding ascii
                        $c['RootCaPath'] = $path
                        Write-Ok "Wrote the LDAPS root CA to $path. Paste the whole PEM into Entro."
                    }
                    BuildScript = {
                        param($c)
                        @'
$tcp = [System.Net.Sockets.TcpClient]::new()
try {
    $tcp.Connect($DcFqdn, 636)
    $ssl = [System.Net.Security.SslStream]::new($tcp.GetStream(), $false, { param($sender, $certificate, $chain, $errors) $true })
    $ssl.AuthenticateAsClient($DcFqdn)
    $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($ssl.RemoteCertificate)
    $chain = [System.Security.Cryptography.X509Certificates.X509Chain]::new()
    [void]$chain.Build($cert)
    $root = $chain.ChainElements[$chain.ChainElements.Count - 1].Certificate
    $b64 = [Convert]::ToBase64String($root.RawData, [Base64FormattingOptions]::InsertLineBreaks)
    $pem = "-----BEGIN CERTIFICATE-----`n$b64`n-----END CERTIFICATE-----"
} finally { $tcp.Dispose() }
$outDir = if ($OutputDirectory) { $OutputDirectory } else { (Get-Location).Path }
$caPath = Join-Path $outDir 'root-ca.pem'
Set-Content -LiteralPath $caPath -Value $pem -Encoding ascii
Write-Host "Wrote the LDAPS root CA to $caPath. Paste the whole PEM into Entro."
'@

                    }
                }
            )
        }
        OnRunComplete = {
            param($ctx)
            $sam = if ($ctx['SamAccountName']) { $ctx['SamAccountName'] } else { 'svc_entro' }
            $upn = if ($ctx['ServiceUpn']) { $ctx['ServiceUpn'] } else { "$sam@$($ctx['Domain'])" }
            $wg = if ($ctx['WorkerGroup']) { $ctx['WorkerGroup'] } else { '(select the Outpost Worker Group)' }
            $ca = if ($ctx['RootCaPath']) { $ctx['RootCaPath'] } else { 'root-ca.pem' }
            Write-Host ''
            Write-Host 'Entro handoff' -ForegroundColor Cyan
            Write-Host ' Target host: domain-joined Windows host'
            Write-Host " Nickname: $($ctx['Nickname'])"
            Write-Host " Domain Controller: $($ctx['DomainController'])"
            Write-Host " DC FQDN: $($ctx['DcFqdn'])"
            Write-Host " Domain: $($ctx['Domain'])"
            Write-Host " Username: $upn"
            Write-Host " Root CA PEM: $ca"
            Write-Host " Environment: $($ctx['EnvironmentNickname']) ($($ctx['EnvironmentType']))"
            Write-Host " Worker Group: $wg"
            Write-Host ''
        }
    }
}

Export-ModuleMember -Function Register-ActiveDirectoryEntroDefinitions, Get-EntroAdLdapsPorts, Export-EntroLdapsRootCaPem