Windows Server

info

Installing Passwork on following OS:

• Windows Server 2016
• Windows Server 2019
• Windows Server 2022

1. Minimum system requirements

Passwork is not resource demanding. The amount of resources required (RAM, CPU, HDD) and the number of servers depend on the number of active users, the amount of data stored, and the requirements for system fault tolerance.

See the Technical requirements

2. Basic steps before installation

Run PowerShell as Administrator:

• Right-click on the Start icon in the lower left corner of the screen;
• Select Windows PowerShell (Administrator) from the context menu.

danger

If Windows Server 2016 is used, you must enable the TLS protocol to download packages to the operating system as described below

PowerShell

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Create a temporary directory for downloading packages and archives:

PowerShell

if (-not (Test-Path "$env:SystemDrive\Windows\Temp\passwork_install" -PathType Container)) {
    New-Item -Path "$env:SystemDrive\Windows\Temp\passwork_install" -ItemType Directory
    Write-Host "Directory successfully created" -ForegroundColor Green
} else {
    Write-Host "Directory already exists"
}

Override user group names using SID:

PowerShell

$userGroupSid = "S-1-5-32-545"
$userSecurityIdentifier = New-Object System.Security.Principal.SecurityIdentifier($userGroupSid)
$userGroupName = $userSecurityIdentifier.Translate([System.Security.Principal.NTAccount]).Value
$userGroupName = $userGroupName.Split("\")[1]

$iis_iusrsGroupSid = "S-1-5-32-568"
$iis_iusrsSecurityIdentifier = New-Object System.Security.Principal.SecurityIdentifier($iis_iusrsGroupSid)
$iis_iusrsGroupName = $iis_iusrsSecurityIdentifier.Translate([System.Security.Principal.NTAccount]).Value
$iis_iusrsGroupName = $iis_iusrsGroupName.Split("\")[1]

Install the IIS role with the module:

PowerShell

Install-WindowsFeature -Name Web-Server -IncludeManagementTools
Install-WindowsFeature -Name Web-CGI -IncludeManagementTools

3. PHP installation

Download the PHP archive:

PowerShell

try {
    (New-Object System.Net.WebClient).DownloadFile(
        "https://repos.passwork.pro/repository/windows_packages/php_build/82/php_latest.zip", 
        "$env:SystemDrive\Windows\Temp\passwork_install\php_latest.zip"
    )
    Write-Host "PHP loaded successfully" -ForegroundColor Green
} catch {
    Write-Host "Error loading PHP: $_" -ForegroundColor Red
}

info

In case of an error, you can download the archive manually — https://repos.passwork.pro/repository/windows_packages/php_build/82/php_latest.zip

Unzip the contents to Program Files:

PowerShell

Expand-Archive `
    -Path "$env:SystemDrive\Windows\Temp\passwork_install\php_latest.zip" `
    -DestinationPath "$env:ProgramFiles\"

Add PHP utilities to the PATH variable environment:

PowerShell

if (-not ([System.Environment]::GetEnvironmentVariable("PATH", [System.EnvironmentVariableTarget]::User).Contains("$env:ProgramFiles\php8.2"))) {
    [System.Environment]::SetEnvironmentVariable(
        "PATH", 
        [System.Environment]::GetEnvironmentVariable("PATH", [System.EnvironmentVariableTarget]::User) + ";$env:ProgramFiles\php8.2", 
        [System.EnvironmentVariableTarget]::User
    )
    Write-Host "PHP directory added to PATH environment variable" -ForegroundColor Green
} else {
    Write-Host "The PHP directory is already present in the PATH environment variable"
}

warning

To test it, open a new PowerShell window and run the php -v cmdlet

Set Users permissions to the group for the PHP directory:

PowerShell

Invoke-Expression "icacls '$env:ProgramFiles\php8.2' /grant '${userGroupName}:(OI)(CI)`M'"

4. Installing MongoDB database

Download MongoDB installer:

PowerShell

try {
    (New-Object System.Net.WebClient).DownloadFile("https://repos.passwork.pro/repository/windows_packages/mongodb_database_latest.msi", "$env:SystemDrive\Windows\Temp\passwork_install\mongodb_database_latest.msi")
    Write-Host "MongoDB successfully uploaded" -ForegroundColor Green
} catch {
    Write-Host "Error loading MongoDB: $_" -ForegroundColor Red
}

info

In case of an error, you can download the installer manually — https://repos.passwork.pro/repository/windows_packages/mongodb_database_latest.msi

Install MongoDB by default:

PowerShell

try {
    Start-Process -FilePath "msiexec.exe" -ArgumentList "/l*v", "$env:SystemDrive\Windows\Temp\mdbinstall.log", "/qb", "/i", "$env:SystemDrive\Windows\Temp\passwork_install\mongodb_database_latest.msi", "SHOULD_INSTALL_COMPASS=0", "ADDLOCAL=Router,ServerService" -Wait -ErrorAction Stop
} catch {
    Write-Host "Error installing MongoDB: $_." -ForegroundColor Red
}

info

To install MongoDB on another drive, you need to add "INSTALLLOCATION=A:\MongoDB"

Create a directory for the MongoDB administration utilities:

PowerShell

if (-not (Test-Path "$env:ProgramFiles\MongoDB\Tools\")) {
    New-Item -ItemType Directory -Force -Path "$env:ProgramFiles\MongoDB\Tools\"
    Write-Host "Directory successfully created" -ForegroundColor Green
} else {
    Write-Host "Directory already exists"
}

Download administration utilities:

PowerShell

try {
    (New-Object System.Net.WebClient).DownloadFile(
        "https://repos.passwork.pro/repository/windows_packages/database_tools_latest.zip", 
        "$env:SystemDrive\Windows\Temp\passwork_install\database_tools_latest.zip"
    )
    Write-Host "Administration utilities loaded" -ForegroundColor Green
} catch {
    Write-Host "Error loading administration utilities: $_" -ForegroundColor Red
}

info

In case of an error, you can download the installer manually — https://repos.passwork.pro/repository/windows_packages/database_tools_latest.zip

Unzip content:

PowerShell

Expand-Archive `
    -Path "$env:SystemDrive\Windows\Temp\passwork_install\database_tools_latest.zip" `
    -DestinationPath "$env:ProgramFiles\MongoDB\Tools\"

Add administration utilities to the PATH variable environment:

PowerShell

if (-not ([System.Environment]::GetEnvironmentVariable("PATH", [System.EnvironmentVariableTarget]::User).Contains("$env:ProgramFiles\MongoDB\Tools"))) {
    [System.Environment]::SetEnvironmentVariable(
        "PATH", 
        [System.Environment]::GetEnvironmentVariable("PATH", [System.EnvironmentVariableTarget]::User) + ";$env:ProgramFiles\MongoDB\Tools", 
        [System.EnvironmentVariableTarget]::User
    )
    Write-Host "MongoDB administration utilities have been added to the PATH environment variable" -ForegroundColor Green
} else {
    Write-Host "MongoDB administration utilities are already present in the PATH environment variable"
}

5. Installing modules for IIS

Download archive with modules:

PowerShell

try {
    (New-Object System.Net.WebClient).DownloadFile(
        "https://repos.passwork.pro/repository/windows_packages/iis_package_latest.zip", 
        "$env:SystemDrive\Windows\Temp\passwork_install\iis_package_latest.zip"
    )
    Write-Host "Archive successfully uploaded" -ForegroundColor Green
} catch {
    Write-Host "Error loading archive: $_" -ForegroundColor Red
}

info

In case of an error, you can download the installer manually — https://repos.passwork.pro/repository/windows_packages/iis_package_latest.zip

Unzip modules for IIS:

PowerShell

Expand-Archive `
    -Path "$env:SystemDrive\Windows\Temp\passwork_install\iis_package_latest.zip" `
    -DestinationPath "$env:SystemDrive\Windows\Temp\passwork_install\"

Install Visual C++:

PowerShell

try {
    Start-Process `
        -FilePath "$env:SystemDrive\Windows\Temp\passwork_install\VC_redist.x64.exe" `
        -ArgumentList "/q" -Wait -ErrorAction Stop
    }
catch {
    Write-Host "Visual C++ installation ended with an error: $_" -ForegroundColor Red
}

Install PHP Manager:

PowerShell

try {
    Start-Process -FilePath "msiexec.exe" `
        -ArgumentList "/i $env:SystemDrive\Windows\Temp\passwork_install\PHPManagerForIIS_x64.msi /quiet /norestart" `
        -Wait -ErrorAction Stop
}
catch {
    Write-Host "PHP Manager installation failed with an error: $_" -ForegroundColor Red
}

Install URL Rewrite:

PowerShell

try {
    Start-Process -FilePath "msiexec.exe" `
        -ArgumentList "/i $env:SystemDrive\Windows\Temp\passwork_install\rewrite_amd64_en-US.msi /quiet /norestart" `
        -Wait -ErrorAction Stop
}
catch {
    Write-Host "URL Rewrite installation ended with an error: $_" -ForegroundColor Red
}

6. Getting the latest version of Passwork

Create a directory for Passwork:

PowerShell

if (-not (Test-Path "$env:SystemDrive\inetpub\wwwroot\passwork")) {
    New-Item -ItemType Directory -Force -Path "$env:SystemDrive\inetpub\wwwroot\passwork"
    Write-Host "Directory successfully created" -ForegroundColor Green
} else {
    Write-Host "Directory already exists"
}

Go to the Passwork Customer Portal and copy your certificate number:

Get the latest version of Passwork by entering your certificate number:

PowerShell

try {
    (New-Object System.Net.WebClient).DownloadFile(
        "https://portal.passwork.pro/api/download?certificate=certificate_number", 
        "$env:SystemDrive\Windows\Temp\passwork_install\passwork.zip"
    )
    Write-Host "Passwork successfully uploaded" -ForegroundColor Green
} catch {
    Write-Host "Passwork download error: $_" -ForegroundColor Red
}

Unzip Passwork to the IIS directory:

PowerShell

Expand-Archive `
    -Path "$env:SystemDrive\Windows\Temp\passwork_install\passwork.zip" `
    -DestinationPath "$env:SystemDrive\inetpub\wwwroot\passwork\"

Create a web.config for redirect rules:

PowerShell

"<?xml version=`"1.0`" encoding=`"UTF-8`"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name=`"Imported Rule 1`" stopProcessing=`"true`">
                    <match url=`"^app/(.*)/(.*)/template.([a-z-A-Z0-9]+).html`" ignoreCase=`"false`" />
                    <conditions logicalGrouping=`"MatchAll`">
                        <add input=`"{REQUEST_FILENAME}`" matchType=`"IsFile`" ignoreCase=`"false`" negate=`"true`" />
                    </conditions>
                    <action type=`"Rewrite`" url=`"app/{R:1}/{R:2}/template.html`" />
                </rule>
                <rule name=`"Imported Rule 2`" stopProcessing=`"true`">
                    <match url=`"^extension/js/(.*)/(.*)/template.([a-z-A-Z0-9]+).html`" ignoreCase=`"false`" />
                    <action type=`"Rewrite`" url=`"extension/js/{R:1}/{R:2}/template.html`" />
                </rule>
                <rule name=`"Imported Rule 3`" stopProcessing=`"true`">
                    <match url=`"^(.*)$`" ignoreCase=`"false`" />
                    <conditions logicalGrouping=`"MatchAll`">
                        <add input=`"{REQUEST_FILENAME}`" matchType=`"IsDirectory`" ignoreCase=`"false`" negate=`"true`" />
                        <add input=`"{REQUEST_FILENAME}`" matchType=`"IsFile`" ignoreCase=`"false`" negate=`"true`" />
                    </conditions>
                    <action type=`"Rewrite`" url=`"index.php?_url=/{R:1}`" appendQueryString=`"true`" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>" | Out-File -FilePath "$env:SystemDrive\inetpub\wwwroot\passwork\public\web.config" -Encoding UTF8

Set permissions for the Passwork location:

PowerShell

Invoke-Expression "icacls 'C:\inetpub\wwwroot' /grant '${userGroupName}:(OI)(CI)`M'"
Invoke-Expression "icacls 'C:\inetpub\wwwroot' /grant '${$iis_iusrsGroupName}:(OI)(CI)`M'"
Invoke-Expression "icacls 'C:\inetpub\wwwroot' /grant 'IUSR:(OI)(CI)`M'"

7. Configuring IIS web server

Connect modules in PowerShell to manage IIS:

PowerShell

Import-Module IISAdministration
Import-Module WebAdministration
Add-PsSnapin PHPManagerSnapin

Unlock the handlers configuration in IIS:

PowerShell

Invoke-Expression "$env:windir\system32\inetsrv\appcmd.exe unlock config -section:system.webServer/handlers"

Get the ports in use by the operating system:

PowerShell

function Test-PortInUse {
    param (
        [int]$Port
    )

    try {
        $listener = [System.Net.Sockets.TcpListener]::new([System.Net.IPAddress]::Any, $Port)
        $listener.Start()
        $listener.Stop()
        return $false
    } catch {
        return $true
    }
}

Check busy default ports for the website:

PowerShell

if (Test-PortInUse -Port 80) {
    $httpPort = 5353
} else {
    $httpPort = 80
}

Create a website (Passwork Web Site) with HTTP protocol:

PowerShell

New-WebSite -Name "Passwork Web Site" -Port $httpPort -PhysicalPath "$env:SystemDrive\inetpub\wwwroot\passwork\public" -Force

Register a PHP version for the website:

PowerShell

New-PHPVersion -ScriptProcessor "$env:ProgramFiles\php8.2\php-cgi.exe" -SiteName "Passwork Web Site" -VirtualPath "/"

Activate drivers and extensions for the website:

PowerShell

$availableExtensions = Get-PHPExtension -SiteName "Passwork Web Site" -VirtualPath "/"

$commands = @(
    @{Name="php_curl.dll"; Status="Enabled"},
    @{Name="php_gettext.dll"; Status="Enabled"},
    @{Name="php_zip.dll"; Status="Enabled"},
    @{Name="php_phalcon.dll"; Status="Enabled"},
    @{Name="php_mongodb.dll"; Status="Enabled"},
    @{Name="php_ldap.dll"; Status="Enabled"},
    @{Name="php_gd.dll"; Status="Enabled"},
    @{Name="php_openssl.dll"; Status="Enabled"},
    @{Name="php_soap.dll"; Status="Enabled"},
    @{Name="php_mbstring.dll"; Status="Enabled"},
    @{Name="php_mysqli.dll"; Status="Enabled"},
    @{Name="php_opcache.dll"; Status="Enabled"}
)

foreach ($command in $commands) {
    $extension = $availableExtensions | Where-Object {$_.Name -eq $command.Name}
    if (-not $extension) {
        Write-Host "$($command.Name) not available"
    } elseif ($extension.Status -eq "Enabled") {
        Write-Host "$($command.Name) already enabled"
    } else {
        Set-PHPExtension -Name $command.Name -Status Enabled -SiteName "Passwork Web Site" -VirtualPath "/"
        Write-Host "$($command.Name) activated successfully"
    }
}

Restart the IIS web server:

PowerShell

Restart-Service -Name "W3SVC"

info

Open http://localhost:80 or http://localhost:5353 test the connection to Passwork.

7. Passwork parameter checklist

When you connect to Passwork for the first time, you will need to go over the checklist that includes:

• Automatic parameter checking
• Checking connection to MongoDB database
• Generating an encryption key for MongoDB
• License verification

info

Leave all fields as they are if you are installing a new Passwork copy

After finishing the checklist, you will be offered to create the first Passwork user and set their login, password and email address for notifications.

danger

This user is always local and the owner of Passwork by default, in case of assigning LDAP/SSO user an owner, it will automatically become local and you will not be able to authorise in Passwork

8. Configuring Passwork for HTTPS access

8.1 Generating self-signed SSL certificate

Check busy default ports for the website:

PowerShell

if (Test-PortInUse -Port 443) {
    $httpsPort = 444
} else {
    $httpsPort = 443
}

Create a self-signed HTTPS certificate with a server name value:

PowerShell

$dnsName = "$env:COMPUTERNAME"
$newCert = New-SelfSignedCertificate -DnsName $dnsName -CertStoreLocation cert:\LocalMachine\My

8.2 Creating IIS binding for access to Passwork over HTTPS protocol

Create HTTPS binding in the Passwork website:

PowerShell

New-WebBinding -Name "Passwork Web Site" -IPAddress "*" -Port $httpsPort -Protocol "https"

Get the current binding of the Passwork website:

PowerShell

$binding = Get-WebBinding -Name "Passwork Web Site" -Protocol "https"

Bind a previously created self-signed certificate to the HTTPS protocol of the website:

PowerShell

$binding.AddSslCertificate($newCert.GetCertHashString(), "my")

Restart the IIS web server:

PowerShell

Restart-Service -Name "W3SVC"

info

Open https://localhost:443 or https://localhost:444 to test the connection to Passwork

8.3 Configuring Passwork to work over HTTPS protocol

When using a secure SSL connection (HTTPS), client browsers require certain flags to process Passwork data. These flags are called session.cookie_secure and disableSameSiteCookie.

If these flags are not set, browsers will not be able to establish connections and the connection will be rejected, which can lead to authorisation errors.

Set the ;session.cookie_secure parameter in the file C:\Program Files\php8.2\php.ini:

bash

session.cookie_secure = 1

Set the disableSameSiteCookie parameter in C:\inetpub\wwwroot\passwork\app\config\config.ini to Off:

bash

disableSameSiteCookie = Off

info

Do not set these parameters or reset them to their original value if you change your mind about using SSL and HTTP

9. Configure background tasks

Background tasks are tasks that are executed by the scheduler in the background. For example, LDAP synchronisation, loading favicons, and other tasks that are time-consuming, persistent, or resource-demanding.

See a guide on Background tasks.

10. Set up security

warning

Before modifying security settings, we strongly recommend to make sure that Passwork is stable and works correctly, and to back up the files you are making changes to

Server security is an important part of ensuring the protection of valuable company data and resources. It is a process that requires planning and execution to ensure maximum protection against various threats.

Look through the overview of Security settings.