Setting Up a Target System¶

This guide walks through registering a target system in the Zaita platform and configuring it for certificate deployment. For an overview of how target system deployment works, see Target Systems — Introduction.

Prerequisites¶

Before you begin, ensure the following:

You are signed in to the Zaita web portal with the Deployment Administrator or Super Administrator role.
A Bridge is deployed and connected in the network segment where the target system resides. The Bridge must be able to reach the target system over the required protocol (WinRM or SSH).
A service account has been created on the target system with the permissions required for certificate installation. See Best Practices for per-system account requirements.

Step 1 — Register the Target System¶

Navigate to Admin → Target Systems in the web portal.
Select Add Target System.
Configure the common settings:
- Name — a descriptive name (for example, prod-web-01 or Exchange — Sydney).
- Description — optional notes on the system's role or location.
- System Type — select the type of system from the supported list.
- Bridge — select the Bridge that will perform deployments to this system. The Bridge must have network access to the target.
- Hostname / IP Address — the address the Bridge will connect to.
Configure the authentication method for the selected system type (see below).
Save the target system.

Step 2 — Configure Authentication¶

Windows Systems (WinRM)¶

Windows-based target systems use Windows Remote Management (WinRM) for authentication. WinRM over HTTPS (port 5986) is strongly recommended over HTTP (port 5985).

Field	Description
Username	A local or domain account with the required permissions on the target system
Password	The account password, stored encrypted in the platform
Port	WinRM port — `5986` for HTTPS (recommended), `5985` for HTTP
Use HTTPS	Enabled by default. Disable only in isolated environments where HTTPS is unavailable
Skip Certificate Validation	Disables TLS validation of the WinRM endpoint's certificate. Use only when the WinRM endpoint uses a self-signed certificate in a trusted network

Preparing a Windows System for WinRM¶

WinRM must be enabled on the target system before the Bridge can connect. Run the following on the target system from an elevated PowerShell prompt:

# Enable WinRM
Enable-PSRemoting -Force

# Configure HTTPS listener (recommended)
$cert = New-SelfSignedCertificate -DnsName $env:COMPUTERNAME -CertStoreLocation Cert:\LocalMachine\My
New-Item -Path WSMan:\Localhost\Listener -Transport HTTPS -Address * -CertificateThumbprint $cert.Thumbprint -Force

# Open WinRM HTTPS port in Windows Firewall
New-NetFirewallRule -Name "WinRM HTTPS" -DisplayName "WinRM HTTPS" -Protocol TCP -LocalPort 5986 -Action Allow

Note: For domain environments, WinRM is typically configured via Group Policy. Consult your Active Directory team before enabling WinRM manually on domain-joined systems.

Configuring Just Enough Administration (JEA)¶

Just Enough Administration (JEA) is a PowerShell security technology that restricts what a remote session can do on a Windows system. Instead of granting the deployment account full administrative access, JEA creates a constrained PowerShell endpoint that only exposes the specific cmdlets and parameters required for certificate deployment.

Using JEA is strongly recommended for all Windows target systems. It enforces least privilege at the PowerShell session level, ensuring the service account used by the Bridge can only perform certificate management operations — even if the account's credentials are compromised.

Step 1 — Create a Role Capability File¶

A Role Capability file (.psrc) defines which cmdlets, functions, and parameters are available inside the JEA session. Create a file for Zaita certificate deployment operations.

On the target system, from an elevated PowerShell prompt:

# Create the JEA module directory
$modulePath = "$env:ProgramFiles\WindowsPowerShell\Modules\ZaitaJEA"
New-Item -Path "$modulePath\RoleCapabilities" -ItemType Directory -Force

# Generate the role capability file
New-PSRoleCapabilityFile -Path "$modulePath\RoleCapabilities\ZaitaCertDeploy.psrc"

Edit the generated file at $modulePath\RoleCapabilities\ZaitaCertDeploy.psrc and set the VisibleCmdlets to the cmdlets required for your target system type:

@{
    # Unique identifier for this role capability
    GUID               = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

    # Cmdlets available in the JEA session
    VisibleCmdlets      = @(
        # Certificate store management
        'Import-Certificate',
        'Import-PfxCertificate',
        'Get-ChildItem',
        'Remove-Item',

        # Service management (adjust for your target system type)
        'Restart-Service',
        'Get-Service',

        # IIS management (include only for IIS target systems)
        'Get-WebBinding',
        'New-WebBinding',
        'Remove-WebBinding',
        'Set-WebBinding',
        'New-Item',
        'Get-Website'
    )

    # Functions available in the JEA session (optional)
    # VisibleFunctions    = @()

    # External commands the session can run (optional)
    # VisibleExternalCommands = @()

    # Providers available in the session
    VisibleProviders    = @('Certificate', 'FileSystem')
}

Note: Adjust the VisibleCmdlets list to match your target system type. For example, Exchange Server deployments will need Exchange Management Shell cmdlets (Enable-ExchangeCertificate, Import-ExchangeCertificate), while SQL Server deployments may need Set-ItemProperty for registry-based configuration.

Step 2 — Create a Session Configuration File¶

A Session Configuration file (.pssc) ties the role capability to a user or group and defines the JEA endpoint.

# Generate the session configuration file
New-PSSessionConfigurationFile -Path "$modulePath\ZaitaCertDeploy.pssc" `
    -SessionType RestrictedRemoteServer `
    -RunAsVirtualAccount `
    -TranscriptDirectory "$env:ProgramData\JEATranscripts\Zaita" `
    -RoleDefinitions @{
        # Map your deployment service account or group to the role capability
        'DOMAIN\zaita-deploy' = @{ RoleCapabilities = 'ZaitaCertDeploy' }
    }

Key settings:

Setting	Purpose
SessionType	`RestrictedRemoteServer` — starts from a minimal session with no access, then adds only what the role capability allows
RunAsVirtualAccount	The session runs under a temporary local administrator account that is created and destroyed per session. The connecting user never holds persistent admin privileges
TranscriptDirectory	All commands executed in the JEA session are logged to transcript files for audit purposes
RoleDefinitions	Maps the deployment service account (or group) to the role capability file created in Step 1

Note: RunAsVirtualAccount is the recommended setting. It allows the session to perform administrative operations (such as writing to the certificate store) without granting the connecting account local administrator rights. The virtual account is automatically cleaned up when the session ends.

Step 3 — Register the JEA Endpoint¶

Register the session configuration as a new PowerShell remoting endpoint on the target system:

# Register the JEA endpoint
Register-PSSessionConfiguration -Name 'ZaitaCertDeploy' `
    -Path "$modulePath\ZaitaCertDeploy.pssc" `
    -Force

# Restart WinRM to apply
Restart-Service WinRM

Step 4 — Verify the JEA Endpoint¶

Test the endpoint by connecting from another machine (or locally) as the deployment service account:

# Connect to the JEA endpoint
Enter-PSSession -ComputerName <target-hostname> `
    -ConfigurationName ZaitaCertDeploy `
    -Credential (Get-Credential)

# List available commands — only the cmdlets defined in the role capability should appear
Get-Command

If the session connects successfully and Get-Command returns only the expected cmdlets, the JEA endpoint is correctly configured.

Important: When configuring the target system in the Zaita portal, set the WinRM Endpoint Configuration field to ZaitaCertDeploy so the Bridge connects to the JEA-constrained endpoint rather than the default PowerShell endpoint.

Linux Systems (SSH)¶

Linux-based target systems use SSH for authentication. SSH key-based authentication is strongly preferred over password authentication.

Field	Description
Username	A service account on the target system with the required permissions
Authentication Method	`SSH Key` (recommended) or `Password`
SSH Private Key	The private key corresponding to the public key installed on the target system (for SSH key auth)
Password	The account password (for password auth only)
Port	SSH port — default is `22`

Preparing a Linux System for SSH Key Authentication¶

On the target system, create the service account and authorise the deployment key:

# Create a dedicated deployment account
sudo useradd --system --no-create-home --shell /bin/bash zaita-deploy

# Create the .ssh directory
sudo mkdir -p /home/zaita-deploy/.ssh
sudo chmod 700 /home/zaita-deploy/.ssh

# Add the public key (generate a key pair and store the private key in the platform)
echo "ssh-ed25519 AAAA... your-deployment-key" | sudo tee /home/zaita-deploy/.ssh/authorized_keys
sudo chmod 600 /home/zaita-deploy/.ssh/authorized_keys
sudo chown -R zaita-deploy:zaita-deploy /home/zaita-deploy/.ssh

Step 3 — Configure System-Specific Settings¶

Each system type has additional configuration fields that control where certificates are installed and how services are managed.

Microsoft IIS¶

Field	Description
Site Name	The IIS site to update the HTTPS binding on (for example, `Default Web Site`)
Certificate Store	Windows certificate store to install into — typically `My` (Personal)
Binding IP	IP address for the HTTPS binding — use `*` for all interfaces
Binding Port	HTTPS port — default is `443`
SNI Required	Enable if the site uses Server Name Indication
Restart IIS	Whether to restart the IIS service after binding update — enabled by default

Windows Certificate Store¶

Field	Description
Store Location	`LocalMachine` or `CurrentUser`
Store Name	The certificate store name — typically `My` (Personal), `Root`, or `TrustedPeople`

Microsoft Exchange Server¶

Field	Description
Exchange Services	The Exchange services to enable the certificate for — select from `SMTP`, `IIS`, `IMAP`, `POP`
Restart Services	Whether to restart the selected Exchange services after certificate assignment

Remote Desktop Services¶

Field	Description
Certificate Store	Windows certificate store — typically `My` (Personal)
Apply to RDP Listener	Applies the certificate to the RDP-TCP listener on the target system

Microsoft SQL Server¶

Field	Description
Certificate Store	Windows certificate store — typically `My` (Personal)
Force Encryption	Configures SQL Server to require encrypted connections
Restart SQL Server	Whether to restart the SQL Server service after certificate assignment — required for the new certificate to take effect

Nginx¶

Field	Description
Certificate Path	Full path to write the certificate file (for example, `/etc/nginx/ssl/server.crt`)
Key Path	Full path to write the private key file (for example, `/etc/nginx/ssl/server.key`)
Reload Command	Command to reload Nginx — default is `systemctl reload nginx`

Apache HTTP Server¶

Field	Description
Certificate Path	Full path to write the certificate file
Key Path	Full path to write the private key file
CA Chain Path	(Optional) Full path to write the CA chain/bundle file
Restart Command	Command to restart Apache — default is `systemctl restart apache2` or `systemctl restart httpd`

HAProxy¶

Field	Description
PEM Bundle Path	Full path to write the combined PEM file (certificate + key, concatenated) required by HAProxy
Reload Command	Command to reload HAProxy — default is `systemctl reload haproxy`

Postfix¶

Field	Description
Certificate Path	Full path to write the certificate file
Key Path	Full path to write the private key file
Restart Command	Command to restart Postfix — default is `systemctl restart postfix`

Custom Script (Bash)¶

Field	Description
Certificate Path	Full path to write the certificate file
Key Path	Full path to write the private key file
Script Path	Full path to the Bash script to execute after files are written

The script is executed by the Bridge after the certificate and key have been written to the configured paths. The paths are passed as positional arguments:

/path/to/your/script.sh <certificate-path> <key-path>

The script must exit with code 0 on success. Any non-zero exit code is treated as a deployment failure and reported back to the platform.

Step 4 — Test the Connection¶

After saving the target system, test the Bridge's connectivity and authentication:

Navigate to Admin → Target Systems.
Select the target system.
Select Test Connection.

The platform dispatches a connectivity test job to the assigned Bridge. The Bridge attempts to authenticate against the target system and reports the result. A successful test confirms the Bridge can reach the target and the credentials are correct, but does not install any certificate.

If the test fails, review the error details returned in the portal and verify: - The Bridge has network access to the target system's hostname and port. - The credentials are correct and the service account has the required permissions. - WinRM or SSH is enabled and accessible on the target system.

Step 5 — Configure Certificate Profiles¶

Once the connection test passes, configure one or more Certificate Profiles for the target system. A Certificate Profile defines the certificate attributes — Common Name, SANs, key algorithm, validity, and extensions — that will be used when a certificate is requested and deployed to this system.

Navigate to Admin → Target Systems.
Select the target system.
Open the Certificates tab.
Select Add Certificate Profile and complete the profile fields.

In addition to the certificate attributes (Common Name, algorithm, validity, etc.), each profile includes:

Renewal Threshold — the percentage of the certificate's validity period that must elapse before automatic renewal is triggered. The default is 70%. Adjust this based on how much lead time you want before expiry.
Deployment Configuration — per-profile overrides for the certificate file path, key file path, and reload command. If your target system hosts multiple services with certificates in different directories, set distinct paths per profile. Leave these blank to use the target system defaults.

A target system should have at least one certificate profile before any deployment jobs are triggered. For systems that host multiple services or virtual hosts, add a separate profile for each certificate.

For full details on profile fields and policy validation, see Managing Target Systems — Certificate Profiles.

Step 6 — Trigger the First Deployment¶

With a certificate profile saved, trigger the initial deployment:

Navigate to Admin → Target Systems.
Select the target system.
Open the Certificates tab and select the certificate profile.
Select Deploy.

The platform creates a Provisioning order and queues it for the assigned Bridge. You can monitor its progress in Admin → Target Systems → Orders. Once complete, the profile records the deployment timestamp, and subsequent renewals will be handled automatically based on the configured threshold.