Configure HTTPS for the ATRS API

Configure a trusted HTTPS connection to the ATRS API so your application can send credentials and requests securely.

This procedure uses a dedicated IPv4 port on the Windows ATRS server. For shared ports, SNI, IPv6 or a reverse proxy, have your administrator use the deployment procedure for that configuration.

Before you begin

You need:

A working local API connection and the current protocol and port.
An unused dedicated HTTPS port and the DNS hostname applications will use.
A CA-issued PFX certificate with its private key and that hostname in its DNS SAN.
A certificate chain trusted by the application hosts.
The Windows identity shown in the API service’s Log On properties.
Approved client IPv4 addresses or subnets.
An elevated Windows PowerShell terminal on the server.

Plan a short service interruption. Record the original settings before changing them.

1. Stop the API service

In Options → REST API, click Stop and wait for the API service to stop. Protocol and port can be changed while this service is stopped.

2. Import and inspect the certificate

Import the PFX into Local Computer → Personal and inspect it:

$AtrsPfxPath = Read-Host "PFX file path"
$AtrsPfxPassword = Read-Host "PFX password" -AsSecureString
Import-PfxCertificate -FilePath $AtrsPfxPath -CertStoreLocation Cert:\LocalMachine\My -Password $AtrsPfxPassword -ErrorAction Stop
$AtrsThumbprint = (Read-Host "Imported server certificate thumbprint").Replace(" ","")
$AtrsCertificate = Get-Item -LiteralPath "Cert:\LocalMachine\My\$AtrsThumbprint" -ErrorAction Stop
if (-not $AtrsCertificate.HasPrivateKey -or $AtrsCertificate.NotAfter -le (Get-Date)) { throw "A valid certificate with a private key is required" }
$AtrsCertificate | Format-List Subject,DnsNameList,NotBefore,NotAfter,EnhancedKeyUsageList,Thumbprint,HasPrivateKey

In certlm.msc, check the DNS SAN, Server Authentication usage, validity dates and certificate chain. The certificate must have its private key. See Microsoft’s PFX import instructions for additional guidance.

3. Check the selected port

Enter your deployment values and inspect existing listeners and reservations:

$AtrsHttpsPort = [int](Read-Host "Dedicated unused HTTPS port")
if ($AtrsHttpsPort -lt 1 -or $AtrsHttpsPort -gt 65535) { throw "Invalid port" }
$AtrsBinding = "0.0.0.0:$AtrsHttpsPort"
$AtrsUrlPrefix = "https://*:$AtrsHttpsPort/"
$AtrsServiceIdentity = Read-Host "Exact Windows account shown in the API service Log On properties"
$AtrsAllowedClients = Read-Host "Approved client IPv4 address or subnet"
netsh http show sslcert
netsh http show urlacl
Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -eq $AtrsHttpsPort }

Proceed when the chosen port has no conflicting listener, certificate binding or URL reservation. Check hostname and IPv6 entries too. Retain the listings so you can identify which resources this procedure creates.

4. Save the deployment record

Save the selected settings and a new application identifier. Run the remaining server steps in this same elevated terminal.

$AtrsApplicationId = "{" + [guid]::NewGuid().ToString() + "}"
$AtrsFirewallName = "ATRS-HTTPS-" + [guid]::NewGuid().ToString()
$AtrsTlsRecordPath = Join-Path (Get-Location) ("atrs-https-"+[guid]::NewGuid().ToString()+".json")
@{Binding=$AtrsBinding; UrlPrefix=$AtrsUrlPrefix; ApplicationId=$AtrsApplicationId; Thumbprint=$AtrsThumbprint; Store="MY"; ServiceIdentity=$AtrsServiceIdentity; FirewallName=$AtrsFirewallName} | ConvertTo-Json | Set-Content -LiteralPath $AtrsTlsRecordPath -Encoding UTF8 -ErrorAction Stop

Bind the certificate

Attach the inspected certificate to the dedicated port:

netsh http add sslcert "ipport=$AtrsBinding" "certhash=$AtrsThumbprint" "appid=$AtrsApplicationId" certstorename=MY
if ($LASTEXITCODE -ne 0) { throw "Certificate binding failed; do not start the changed listener" }

Expect a successful certificate-binding message. Stop if the command fails and inspect the existing bindings before proceeding.

5. Reserve the URL

Grant the recorded service identity access to the listener URL:

netsh http add urlacl "url=$AtrsUrlPrefix" "user=$AtrsServiceIdentity"
if ($LASTEXITCODE -ne 0) { throw "URL reservation failed; remove only this new certificate binding before retrying" }

Expect a successful URL-reservation message. If it fails, check the service identity and existing reservations; remove only this procedure’s new binding if you need to restart setup.

6. Allow the approved clients

Create the scoped firewall rule and inspect the completed binding and reservation:

New-NetFirewallRule -Name $AtrsFirewallName -DisplayName $AtrsFirewallName -Direction Inbound -Action Allow -Protocol TCP -LocalPort $AtrsHttpsPort -RemoteAddress $AtrsAllowedClients -ErrorAction Stop
netsh http show sslcert "ipport=$AtrsBinding"
netsh http show urlacl "url=$AtrsUrlPrefix"
Write-Host "TLS deployment record: $AtrsTlsRecordPath"

Confirm each command succeeds. Keep the printed deployment-record path for renewal or recovery. The generated application GUID identifies this binding; keep it with the record.

For Windows command details, see certificate bindings, netsh http and firewall rules.

7. Start the HTTPS listener

In Options → REST API, set Protocol to https and Port to the bound port. Click Start and confirm the service shows as running.

8. Verify from the application host

Replace the example hostname and port, then call Ping from the application host:

$AtrsBaseUrl = "https://atrs.example.com:9001"
$AtrsPing = Invoke-RestMethod -Method Get -Uri "$AtrsBaseUrl/api/Service/Ping" -Headers @{Accept="application/json"} -TimeoutSec 30
if ($AtrsPing -ne 1) { throw "Unexpected Ping response" }

Expect HTTP 200 and JSON 1 with normal certificate validation enabled. Resolve trust, expiry or hostname errors before sending credentials.

Complete Authentication and Token Management, including the protected IsSchedulerRunning check, using this HTTPS base address.

Renew the certificate

In a new elevated terminal, load the deployment record and inspect the current binding:

$AtrsTlsRecordPath = Read-Host "Path to the intended TLS deployment record"
$AtrsTlsRecord = Get-Content -LiteralPath $AtrsTlsRecordPath -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop
$AtrsBinding=$AtrsTlsRecord.Binding
$AtrsUrlPrefix=$AtrsTlsRecord.UrlPrefix
$AtrsApplicationId=$AtrsTlsRecord.ApplicationId
$AtrsThumbprint=$AtrsTlsRecord.Thumbprint
$AtrsFirewallName=$AtrsTlsRecord.FirewallName
$AtrsServiceIdentity=$AtrsTlsRecord.ServiceIdentity
netsh http show sslcert "ipport=$AtrsBinding"

Confirm the binding still belongs to this deployment. Retain the old certificate, import and inspect the replacement, then stop the API service. Update only this binding:

$AtrsReplacementThumbprint = (Read-Host "Validated replacement certificate thumbprint").Replace(" ","")
netsh http update sslcert "ipport=$AtrsBinding" "certhash=$AtrsReplacementThumbprint" "appid=$AtrsApplicationId" certstorename=MY
if ($LASTEXITCODE -ne 0) { throw "Renewal binding update failed" }

Start the API service. Repeat the remote Ping and authenticated check, and inspect the certificate presented to the client. When those checks succeed, update the record:

$AtrsUpdatedTlsRecord = @{Binding=$AtrsBinding; UrlPrefix=$AtrsUrlPrefix; ApplicationId=$AtrsApplicationId; Thumbprint=$AtrsReplacementThumbprint; PreviousThumbprint=$AtrsThumbprint; Store="MY"; ServiceIdentity=$AtrsServiceIdentity; FirewallName=$AtrsFirewallName}
$AtrsUpdatedTlsRecord | ConvertTo-Json | Set-Content -LiteralPath $AtrsTlsRecordPath -Encoding UTF8 -ErrorAction Stop

If renewal fails, stop the service, run the update command with the previous thumbprint, restart and verify. Keep the old certificate until recovery is no longer required.

Restore the previous configuration

If initial setup fails, stop the API. In the same terminal, or after loading the deployment record, remove only the resources this procedure created:

netsh http delete urlacl "url=$AtrsUrlPrefix"
netsh http delete sslcert "ipport=$AtrsBinding"
Remove-NetFirewallRule -Name $AtrsFirewallName -ErrorAction Stop

Restore the original protocol and port in ATRS, start the service and repeat its local Ping check. Resume network credential requests when a trusted HTTPS endpoint is working.

Troubleshooting

Symptom	What to check
Certificate import fails	PFX path, password, permissions and private key.
Binding or reservation fails	Existing IPv4, IPv6 or hostname binding; exact service identity.
Service cannot listen	Port conflict, URL reservation and selected protocol/port.
Local works; remote fails	Firewall client scope, routing and DNS.
Client rejects certificate	Hostname, dates and complete trusted chain.