Single Sign-On to Desktop (SSO2D)

Available in Q4 2026 - updates to the .OVA Cluster Nodes are required for this feature.

Single Sign-On to Desktop settings for On‑Premises Deployments

Overview

Single Sign-On to Desktop (SSO2D) allows users to sign in to the Apporto Portal through their organisation’s identity provider and launch their on-premises Windows desktops without a second login.

This guide covers the Active Directory, certificate-service, Windows host and Apporto configuration required to enable SSO2D. It is intended for the Windows, Active Directory and Apporto administrators responsible for the deployment.

Who should use this guide

  • Windows administrators managing Apporto for SSO2D requirements.

Architecture and sign-in flow

The diagram shows how portal sign-in, certificate enrolment and desktop launch fit together across Apporto Cloud and the customer’s on-premises environment.

SSO2D.png

Prerequisites

  • One or two Windows CE-Agent (Certificate Enrollment Agent) VMs to run the Apporto SSO Certificate Service. One VM can be used for a proof of concept; two are recommended for production. The examples in this guide use Windows Server 2022.

  • Access to a Domain Controller and an Active Directory Certificate Authority (CA) for obtaining certs.

  • Group Policy Management Console (GPMC), with permissions to create and link GPOs to the target organisational units (OUs).

  • Access to the Apporto portal/tenant UI control plane to configure SSO2D settings.

  • The approved Apporto SSO Certificate Service and Windows ApportoService MSI installers.

  • Updated .OVA cluster nodes that support SSO2D.

  • Where portal sign-in uses an identity provider, an IdP attribute containing the user’s AD sAMAccountName.

  • Optionally, installation of Redis Cache using 3rd party Memuraoi.

The following Windows service builds are referenced by this guide. Contact Apporto Support or Engineering for the approved builds to use.

Component

Build referenced

Apporto SSO Certificate Service

1.0.627 or later

Windows ApportoService

1.1.1257 or later

The Windows policies in this guide assume RDP is used for desktop connections. Unless stated otherwise, they are Computer Configuration policies.

These recommendations and configuration should be validated in a staging OU before production rollout.

Network requirements

Configure the required network and Windows Firewall rules before testing. Refer to the on-premises deployment prerequisites and required ports for the wider deployment requirements.

The certificate-service configuration references the following ports:

Port

Purpose

TCP 443

HTTPS, where used by the deployment

TCP 3443

Default HTTPS port for the Apporto SSO Certificate Service

TCP 6379

Redis cache, where enabled and where network access is required

Apply the rules to the relevant source and destination systems. This list does not replace the wider Active Directory, CA and Apporto deployment connectivity requirements.

Prepare Active Directory and certificate templates

Create the enrolment account and the certificate templates required by the SSO2D certificate service.

Create the Certificate Enrollment User

Within Active Directory Users and Computers, Create a new AD Domain User account that will be used for the certificate enrollment purposes. Suggested name “ApportoCEAgent”.

This account will also be used as the logon account for the Apporto SSO Certificate Service.

image-20261013-125417.png
image-20261013-125458.png

Configure the enrolment-agent template

Create three certificate templates on your AD Certificate Authority. They serve different purposes:

  • The enrolment-agent template authorises the service to request certificates on users’ behalf.

  • The user logon template defines the certificates used to sign users in to Windows.

  • The HTTPS server template secures connections to the certificate service.

Start with the enrolment-agent template:

  1. Open the Certificate Templates MMC.

  2. Right click Enrollment Agent and select Duplicate Template.

  3. Configure the template properties and permissions as per the screenshots below.

image-20261009-132310.png
image-20260930-164016.png
image-20260930-164158.png
image-20260930-164343.png

Under Application Policies, ensure that Certificate Request Agent is present.

image-20260930-164913.png

Under Key Usage, ensure Digital signature and Make this extension critical are selected, as shown.

image-20260930-165136.png

Complete the remaining properties and permissions shown below.

image-20260930-165338.png
image-20261013-125742.png

Click Apply, then OK to complete this template configuration.

Configure the user logon template

Create the template used to issue user logon certificates:

  1. Open Certificate Templates MMC.

  2. Right click Smartcard Logon and select Duplicate Template.

  3. Configure the template properties as per the screenshots below.

image-20261009-125119.png
image-20260930-165917.png
image-20260930-170018.png
image-20260930-170129.png

Add Secure Email under Application Policies:

image-20261007-134236.png

Configure Key Usage as shown:

image-20260930-170549.png

Complete the remaining properties and permissions shown below.

image-20260930-170724.png
image-20260930-170822.png

Click Apply, then OK to complete this template configuration.

Configure the HTTPS server template

Create the template used for the certificate service’s HTTPS certificate:

  1. Open Certificate Templates MMC.

  2. Right click Web Server and select Duplicate Template.

  3. Configure the template properties as per the screenshots below.

image-20261009-125312.png
image-20260930-182028.png
image-20260930-182120.png
image-20260930-182218.png
image-20260930-182306.png
image-20260930-182346.png
image-20261009-125619.png

Add the server or servers that will run the Apporto SSO Certificate Service (Apporto-Cert-Gen-Svc), as shown below:

image-20260930-183202.png

Click Apply, then OK to complete this template configuration.

Publish the certificate templates

Make the new templates available for enrolment:

  1. Open the Certification Authority MMC.

  2. Right-click Certificate Templates.

  3. Select New > Certificate Template to Issue.

    image-20260930-183810.png
  4. Select all three templates created above and click OK.

image-20261007-135056.png


Install and configure the certificate service

Install the Apporto SSO Certificate Service (Apporto-Cert-Gen-Svc) on each CE-Agent VM. The service obtains user logon certificates from Active Directory Certificate Services for use by Hyperstream during desktop launch.

Please ensure that the ports detailed in the earlier Network Requirements are open.

Enrol the enrolement-agent certificate

Complete the following steps on each CE-Agent VM:

  1. Add the ApportoCEAgent domain account to the VM’s local Administrators group. These permissions are required for the certificate-enrolment processes.

  2. Sign in to the VM as the ApportoCEAgent.

  3. Open MMC, add the Certificates snap-in and select My user account. Alternatively, run certmgr.msc.

  4. Go to Certificates - Current User > Personal > Certificates.

  5. Right-click Personal and select All Tasks > Request New Certificate.

  6. Continue with the default options until the certificate-selection page.

  7. Select the Apporto-Enroll-Agent template, then select Enroll and Finish.

  8. Open the new certificate, select the Details tab and copy its Thumbprint. Retain this value (for example paste into notepad) for use later in the configuration.

image-20261001-122013.png

Enrol and export the HTTPS certificate

The HTTPS certificate is enrolled in the local computer certificate store.

On the VM you installed RDPSSOCertGenSvc service (any user, it can be ce_agent):

  1. Open MMC and add the Certificates snap-in.

  2. Select Computer account. Alternatively, run certlm.msc.

  3. Go to Certificates - Local Computer > Personal > Certificates.

  4. Right-click Personal and select All Tasks > Request New Certificate.

  5. Continue with the default options until the certificate-selection page.

  6. Select the Apporto-Web template and open Details > Properties.

  7. Configure the certificate details as shown below. Set the Common name to the FQDN of the CE-Agent VM that you are logged into.

image-20261009-130401.png
image-20261009-130511.png
  1. Select OK, then complete enrolment.

  2. Select the enrolled Apporto-Web certificate and export it in PFX format, including its private key.

  3. Ensure that you protect the exported PFX with a password before export. Keep a note of the file path and password for use later as the PFX_FILE and PFX_PASSPHRASE parameters.

image-20261009-130754.png
image-20261009-130828.png
image-20261009-130906.png

The suggested location for the exported PFX is C:\Certs to be used in the later steps.

Install the service and configure its account

Obtain the approved Apporto SSO Certificate Service installer from Apporto Support or Engineering. For example: apporto-sso-cert-svc-1.0.627 or later version.

  1. Install the SSOCertGenSvc service application on one or more CE-Agent VMs while signed in as ApportoCEAgent, with local administrator permissions.

  2. During installation, select the HTTPS PFX certificate exported earlier.

  3. Enter the password used to protect that PFX.

  4. Enter the enrolment-agent certificate thumbprint copied earlier.

  5. Enter the user logon certificate template name. In the documented example, this is Apporto-Enroll.

Use the user logon template name here, not Apporto-Enroll-Agent.

  1. Complete the installation.

  2. Stop the Apporto-Cert-Gen-Svc service.

  3. Open its Properties > Log On settings and configure it to run as the ApportoCEAgent domain account.

image-20261013-130335.png

Configure the .env settings

Open the following file in a text editor running with administrator permissions:

C:\Program Files\Apporto\Apporto SSO Certificate Service\.env

Configure the values for the deployment.

Before configuring API_KEY: obtain the Certificate Generation Service API Key from the portal settings described under Configure the tenant’s SSO2D settings. The value must match the key configured in the portal.

Setting

Purpose

ENABLE_HTTP

Set to true if the HTTP service should be enabled. Defaults to false if not specified.

PORT

Port number of the HTTP service. Defaults to 3000 if not specified.

ENABLE_HTTPS

Enables the HTTPS service when set to true. Defaults to true if not specified.

HTTPS_PORT

Port number of the HTTPS service. Defaults to 3443 if not specified.

PFX_FILE

Path to the web certificate in PFX format (as exported earlier). Used only for providing HTTPS.

PFX_PASSPHRASE

Password protecting the HTTPS certificate PFX.

CERTIFICATE_DIR_PATH

The path of a temporary directory where the certificates will be generated.

CERTIFICATE_THUMBPRINT

Thumbprint of the enrollment-agent certificate obtained in a previous step.

CERTIFICATE_TEMPLATE_NAME

User logon certificate template name, for example Apporto-Enroll.

API_KEY

Key used for accesing REST endpoints.

ENABLE_CACHE

Optional - Enables Redis certificate caching when set to true (requires Redis instance setup). Set to false if caching is not used.

REDIS_HOST

Optional - host where Redis in installed.

REDIS_PORT

Optional - network port where Redis is listening.

REDIS_PASSWORD

Optional - Redis password.

The example below shows an .env configuration. Replace the example values with those for the deployment.

image-20261009-131555.png

Save the file and start the Apporto SSO Certificate Service. Restart the service after subsequent configuration changes.

Optional: enable certificate caching

Using Redis for certificate caching is optional. Caching speeds up the second and subsequent logins.

The documented Windows cache implementation uses Memurai, which is compatible with Redis.

  1. Download and install Memurai from Get Memurai (use the Developer Edition).

  2. Once installed modify the memurai.conf file and replace the requirepass value with your own password to be used.

image-20261006-084621.png
  1. Configure any deployment-specific host and port settings, referring to the Memurai documentation.

  2. Update the certificate service’s .env file with the matching Redis host, port and password, and set ENABLE_CACHE=true.

  3. Restart the affected services after applying the configuration.

Verify the SSO Certificate Service log

Check C:\Program Files\Apporto\Apporto SSO Certificate Service\service.log for any issues that will be reported.

If ENABLE_CACHE=false the following should be reported in the Log files during an SSO2D Hyperstream Desktop launch:

image-20261012-133314.png


Example Config for Service, Cert Mangement, .ENV file as well as Powershell script that can test a User to ensure it’s getting the correct Certificates and returns a 200.

Note-API-Key is provided from the Portal\Tenant SSO2D config settings:

################   Debug items, Test User connection for HTTPS and Cert:

$SHeader = @{ "Content-Type" = "application/json" "x-api-key" = "Ei2=BH9gaUhJnuwGl8Dpyl_w13-r/6XXQL-KL_g+LXDRw-/mXv/DKRc7DJbLKV4M" } $SBody = @{ 'username' = 'ssouser2' 'pfxPassword' = '?????????' } Invoke-WebRequest -Method Post -Uri "https://CE-Agent-Host3.JamesR.com:3443/certificate/generate" -Headers $SHeader -Body $($SBody | ConvertTo-Json) -UseBasicParsing

 ################

image-20261006-090157.png
image-20261012-175158.png



Your Root CA Certificate should be delivered on all the VMs in domain.

  1. Open Certification Authority MMC. Right click on the root CA Name - Properties.

  2. In Properties open General tab and go to Certificate #0 (this is your root CA) - View Certificate.

  3. Open Details tab and click on Copy to File…

image-20261006-091832.png


  • Next - DER encoded library and save certificate on your drive.

  • Move certificate file to your Domain Controller and Open Group Policy Management Console.

  • Select Group Policy you want to apply and go to - Computer Configuration-Policies-Windows Settings-Security Settings-Public Key Policies-Trusted Root Certification Authorities and import certificate you exported above.


GPO Required Policies

All Required AD GPO Policies in place:

RDS/VDI GPO Settings for On‑Premises Deployments

The following are additional AD GPO Policies that will be applied the the RDS Hosts that will be used to launch the SSO2D HS-Hyperstream connections into. These are just SSO2D specific policies.


Computer Configuration-Policies-Windows Settings-Security Settings-Local Policies/Security Options:

image-20250327-230509.png
image-20261013-141703.png


Computer Configuration-Policies-Administrative Templates:

image-20261013-183901.png


Portal\Tenant - Enable SSO on the Desktop

image-20261006-154805.png

Add the AD Root Certificate.

Note-The Certificate Generation Service API Key will be used to configure the .ENV file in the Apporto-Cert-Gen-Svc system.


If there will be a usage of SSO-Single sign-on using the top option shown above for Auths into the portal\tenant, note the following that will need to be adjusted:

Setup → Identity Management → SSO domains → open the domain → the attribute mapping section has a field called "User's AD name". The admin puts in the IdP attribute name that carries the sAMAccountName. It's optional, and if it's left empty we simply don't get an AD username.

  • The value has to be the exact attribute name the IdP sends, so you should supply the exact name, not just "sAMAccountName".

  • The AD name is stored on the user at login, so existing users need to sign in again after the mapping is added.

image-20261013-171425.png


Windows ApportoService

In addition to the above for any systems that will be used for SSO2D and updated Windows ApportoService .MSI build will need to be used.

Contact Support or Engineering for the latest build release to be used.

1.1.1257 or Later

The updated release contains a new .json that can be used to help verify the correct RDP GPO policies have been applied.

For initial configured it’s suggested to Disable the OS Firewall to verify connectivity. If however the RDS Hosts that will be used require Ports to be locked down, please review the following info:

Prerequisites | Required ports

image-20260921-200047.png


Configure the Server Pool - Edit settings to ensure SSO2D is Enabled for use:

image-20261012-135449.png
image-20261012-135535.png


Example of SSO2D Hyperstream Desktop Launch: