To configure SAML in Parallels RAS, you need the following:

1. Microsoft Active Directory with the following two user accounts present:

   • Enrollment agent user: used to enroll certificates through RAS Enrollment Server (ES) on behalf of the authenticated user.

   • NLA User: used to initiate the NLA connection with RD Session Hosts and/or VDI guests.

   See Active Directory user account configuration for required permissions and delegations. Note that Azure Active Directory Domain Services (AADDS) are not supported to be used with SAML SSO.

2. Microsoft Enterprise Certification Authority (CA) including the following templates:

   • Enrollment Agent Certificate Template

   • Smartcard Logon Certificate Template

3. Third-party Identity Provider (IdP) such as Azure, Okta, Ping Identity, Gemalto SafeNet, and others. This is where the user accounts will reside. User accounts in IdP must be synchronized with the Microsoft Active Directory environment. Please consult with the provider on how to properly synchronize users.

4. Domain Controllers must have Domain Controller certificates. The certificates on the Domain Controllers must support smart card authentication. Certificates are created using the Microsoft CA certificate template named Domain Controller Authentication. Manually created Domain Controller certificates might not work. If you get an error "Request Not Supported", you may need to recreate Domain Controller certificates. Make sure RD Session Hosts and VDIs have the root certificate issued by the CA in the Trusted Root Certification Authorities store.

5. A Parallels RAS Farm with RD Session Host and/or VDI workloads (running on 64-bit OS).

6. For security reasons, the RAS Enrollment Server is recommended to be installed on a dedicated host. The host should be a standalone server that does not have any other components and roles installed.

7. Both SAML and RAS Enrollment Server configurations are Site-specific settings within the RAS environment. RAS administrators must have "Allow viewing of site information" and "Allow site changes" permissions delegated.

RAS Enrollment Server

• Windows Server 2012 R2 up to Windows Server 2022

RD Session Hosts

• Windows Server 2012 R2 (x64 bit versions) up to Windows Server 2022

Desktop operating systems (guest VMs and Remote PCs)

• Windows 7 up to Windows 11

Please note that 32-bit operating systems are not supported.

Parallels Client

• Parallels Client version 18 or 19 is required.

• Supported platforms include Windows, Mac, Linux, iOS, Android.

Security Assertion Markup Language (SAML) is an XML-based authentication that provides single sign-on (SSO) capability between different organizations by allowing user authentication without sharing the local identity database. Parallels RAS 17.1 and newer support the SAML authentication mechanism.

SAML (2.0) SSO was introduced in Parallels RAS 17.1 supporting HTML5 initiated authentication using Web Client or Parallels Client for Windows. Parallels RAS 18 extends the client support for initiating SAML authentication using the default OS browser or the browser embedded in Parallels Client.

As part of the SAML SSO process, the new RAS Enrollment Server communicates with Microsoft Certificate Authority (CA) to request, enroll, and manage digital certificates on behalf of the user to complete authentication without requiring the users to put in their Active Directory credentials. Service providers and enterprises with multiple subsidiaries don’t have to maintain their own internal Identity Management solutions or complex domains/forest trusts. Integrating with third-party Identity Providers allows customers and partners to provide end users with a true SSO experience.

Supported delivery options are:

• Web Client

• Web Client initiated SAML for Windows

• Web Client initiated SAML for Mac and Linux

• Web Client initiated SAML for Android, iOS and iPadOS

• Parallels Client for Windows initiated SAML authentication

• Parallels Client for Mac initiated SAML authentication

• Parallels Client for Linux initiated SAML authentication

• Parallels Client for iOS/iPadOS initiated SAML authentication

• Parallels Client for Android initiated SAML authentication

The below high-level logical diagram depicts SAML authentication and login process within a Parallels RAS environment:

The SAML authentication and login steps on the diagram above are:

1. RAS Secure Gateway redirects the Parallels Client login request to the IdP site.

2. The user authenticates with IdP.

3. IdP redirects the user to the RAS Secure Gateway with the SAML Assertion.

4. The user is authenticated using the SAML Assertion and the user is logged in.

5. The list of the available RAS published resources is retrieved.

6. The user chooses a published resource and launches it from Parallels Client.

7. The launch request from the user is sent to the server side and the resource is started on the available server.

8. A Parallels RAS session is established.

9. User certificate is processed:

   • Certificate is requested.

   • Certificate is created.

   • Encryption is preformed using the certificate.

10. Smartcard logon.

To create a smartcard logon certificate template:

1. From the Certificate Authority server, launch the Certificate Authority management console (MMC) from Administrative Tools.

2. Expand the CA, right -click on the "Certificate Templates" folder and select Manage.

3. Right click on the "Smartcard Logon" certificate template and then select Duplicate.

4. The new template properties open in the General tab. Type a template name in the text box. Note that the real name automatically appears in the second text box with no spaces. Remember this name. You will need it later to configure of SAML feature. The options on this tab should be configured as follows:

   • Template display name: PrlsSmartcardLogon

   • Template name: PrlsSmartcardLogon

   • Validity period: 1 years

   • Renewal period: 6 weeks

   • Publish certificate in Active Directory: OFF

   • Do not automatically re-enroll if a duplicate certificate exists in Active Directory: OFF

1. Select the Cryptography tab and set the following:

• Provider category: Legacy Cryptographic Service Provider (read-only).

• Algorithm name: Determined by CSP

• Minimum key size: The desired minimum key size up to 4096 bits

In the section Choose which cryptographic providers can be used for requests, choose Requests must use one of the following providers. In the following list of providers, select your desired provider.

1. Select the Issuance Requirements tab and set the following:

• CA certificate manager approval: OFF

• This number of authorized signatures: 1

• Policy type required in signature: Application policy

• Application policy: Certificate Request Agent

• Same criteria as for enrollment: ON

1. Select the Security tab and do the following:

• Click Add.

• Add the enrollment agent user account.

• Allow (select) the "Read" and "Enroll" permissions. Click Apply and OK.

Issue the certificate template

To issue the certificate template that you've created:

1. Run Certificate Authority again and right click on Certififcate Templates, select new and click on Certificate Template to Issue.

2. Select the certificate template you've created in the previous steps (i.e. Prls Smarcard Logon) and click OK.

3. The certificate template should appear in the Certificate Templates list.

Security Assertion Markup Language (SAML) is a standard for exchanging authentication information between identity and service providers. SAML authentication is a single sign-on mechanism where a centralized identity provider (IdP) performs user authentication, while the service provider (SP) only makes access control decisions based on the results of authentication.

The main benefits of using SAML authentication are as follows:

• Service providers don't need to maintain their own user databases. User information is stored in a centralized database on the identity provider side. If a user has to be added or removed, it only needs to be done in a single database.

• Service providers don't need to validate users themselves, so there's no need for a secure authentication and authorization implementation on the provider's side.

• Single sign-on means that a user has to log in once. All subsequent sign-ons (when a user launches a different application) are automatic.

• Users don't have to type in credentials when signing in.

• Users don't have to remember and renew passwords.

• No weak passwords.

The single sign-on process

SAML single sign-on can be initiated on the service provider side or on the identity provider side. The two scenarios are outlined below.

The SAML single sign-on process initiated on the service provider side consists of the following steps:

1. A user opens Parallels Client (one of the and connects to the service provider.

2. The service provider sends a message to the identity provider, asking to authenticate the user.

3. The identity provider asks the user for a username and password.

4. If the user credentials are correct, an authentication response (assertion) is sent to the client and then passed to the service provider. The response contains a message that the user has logged in successfully; the identity provider signs the assertion.

5. The user is presented with the published applications list. When the user launches an application, there's no prompt for credentials.

Single sign-on can also be initiated on the identity provider side, in which case the basic steps are the following:

1. A user logs in to identity provider via a web browser and is presented with a list of enterprise applications, including Parallels RAS.

2. Once Parallels RAS is selected, the assertion is sent to the client, then passed to the service provider configured for Parallels RAS.

3. Users are presented with the RAS published applications list.

4. When the user launches an application, there is no prompt for credentials.

To create the Enrollment Agent template:

1. From the Certificate Authority server, launch the Certificate Authority management console (MMC) from Administrative Tools.

2. Expand the CA, right -click on the "Certificate Templates" folder and select Manage.

3. Right-click the Enrollment Agent template and choose Duplicate Template. The new template properties window opens. On the General tab, configure the following properties:

   • Template display name: PrlsEnrollmentAgent

   • Template name: PrlsEnrollmentAgent

   • Validity period: 2 years

   • Renewal period: 6 weeks

   • Publish certificate in Active Directory: ON

   • Do not automatically re-enroll if a duplicate certificate exists in Active Directory: OFF

1. Select the Cryptography tab and set the following values:

   • Provider category: Legacy Cryptographic Service Provider (read-only).

   • Algorithm name: Determined by CSP

   • Minimum key size: The desired minimum key size up to 4096 bits

In the section Choose which cryptographic providers can be used for requests, choose Requests must use one of the following providers. In the following list of providers, select your desired provider.

1. Select the Security tab and do the following:

• Click Add.

• Add the enrollment agent user account.

• Allow (select) the "Read" and "Enroll" permission. Click Apply and OK.

Issue the certificate template

To issue the certificate template that you've created:

1. Run Certificate Authority again and right click on Certificate Templates, select new and click on Certificate Template to Issue.

2. Select the certificate template you've created in the previous steps (i.e. Prls Enrollment Agent) and click OK.

3. The certificate template should appear in the Certificate Templates list.

The enrollment agent user and NLA user must be created in Microsoft Active Directory. The following describes how to create these users.

Enrollment agent user account

The enrollment agent user account is required to enroll certificates through RAS Enrollment Server on behalf of the authenticated user. Please note that the enrollment agent user requires logon privileges on the machine where RAS Enrollment Server Agent is installed.

NLA user account

The NLA User is needed to initiate the NLA connection with RD Session Hosts and/or VDI guests. Please note that the NLA user requires log on privileges to the session host.

The NLA User must be a member of the Remote Desktop Users group and be granted the Allow log on through Remote Desktop Services permission. At the same time the NLA User must be prohibited to logon via Remote Desktop Services.

To exclude the NLA User account, it must be assigned the Deny log on through Remote Desktop Services user right.

To achieve both goals, you can use local or domain GPOs (linked to OU or domain wide).

A restart of the device is not required for this policy setting to be effective. Any change to the user rights assignment for an account becomes effective the next time the owner of the account logs on.

Group Policy settings are applied through GPOs in the following order, which will overwrite settings on the local computer at the next Group Policy update:

1. Local policy settings

2. Site policy settings

3. Domain policy settings

4. OU policy settings

Create a new GPO or use Default Domain Policy GPO as follows:

1. Open the Group Policy Management Console (GPMC).

2. Open or create a GPO linked with the OU where the RDSH or VDI objects reside.

3. Navigate to Computer Configuration > Windows Settings > Security Settings > Local Policies > User Rights Assignment and open "Allow log on through Remote Desktop Services" option.

4. Choose to add User or Group..., add the NLA user and click OK.

1. Navigate to Computer Configuration > Windows Settings > Security Settings > Local Policies > User Rights Assignment and open the Deny log on through Remote Desktop Services option.

2. Choose to add User or Group..., add the NLA user and click OK.

RAS Enrollment Server communicates with Microsoft Certificate Authority (CA) to request, enroll, and manage digital certificates on behalf of a user for SSO authentication in the Parallels RAS environment.

Setup and configure RAS Enrollment Server

You can remotely install the RAS Enrollment Server Agent on a specified server from the RAS Console. You can also install the Agent by running the standard RAS installer on the desired server.

To remotely install the RAS Enrollment Server:

1. In the RAS Console, navigate to Farm > Site > Enrollment servers.

2. Click Tasks > Add.

3. Specify the FQDN or IP address of the server where you want the RAS Enrollment Server Agent to be installed.

4. Click Next.

5. In the Enrollment Server Agent Information dialog, click Install and follow the onscreen instructions.

To install the RAS Enrollment Server using the Parallels RAS installer:

1. Run the Parallels RAS installer on the server where you want the RAS Enrollment Server Agent installed.

2. On the Select Installation Type page, select Custom and click Next.

3. Clear all other components and select the Parallels RAS Enrollment Server component.

4. Click Next and follow the onscreen instructions.

5. Once the RAS Enrollment Server is installed, open the RAS Console and navigate to Farm > Site > Enrollment servers.

6. Click Tasks > Add.

7. Enter the Enrollment Server FQDN or IP address and click Next.

8. Follow the onscreen instructions to add the server to the Farm.

Obtain and copy the registration key

If you perform a manual installation using the RAS installer, it is necessary to place a registration key file on the Enrollment Server host. This step is not required if the RAS Enrollment Server Agent was remotely deployed from the RAS Console.

First, you need to obtain the registration key file as follows:

1. Open the RAS Console and navigate to Farm > Site > Enrollment servers.

2. Click Tasks > Export registration key.

3. Save the key to a file named registration.crt.

Once you have the registration.crt file, copy it to the following folder on the server where you have the RAS Enrollment Server installed, by default in the following path:

C:\Program Files (x86)\Parallels\ApplicationServer\x64

Configure AD integration

After you added the RAS Enrollment Server in the RAS Console, you need to configure AD integration for it as follows:

1. In the RAS Console, navigate to Farm > Site > Enrollment Servers.

2. Select the AD Integration tab.

3. In the Certificate authority (CA) section, specify the configuration string of your Enterprise CA where the new certificate templates, (Prls Enrollment Agent and Prls Smartcard Logon) were created. This should be done in the following format:

   CAhostname.domain\issuing CA name

   Alternatively, you can click the [...] button to select a CA. For configuration details, see Configure certificate authority templates.

4. In the Enrollment Agent section, specify the Enrollment Agent username and password. For configuration details, see Active Directory user account configuration.

5. In the NLA user section, specify the NLA username and password. For configuration details, see Active Directory user account configuration.

6. Click the Validate AD integration settings button to make sure that the information you've entered is valid.

Using computer management tools

You can perform standard computer management tasks on a RAS Enrollment Server host right from the RAS Console. These include Remote Desktop Connection, PowerShell, Computer Management, Service Management, Event Viewer, IPconfig, Reboot, and others. To access the Tools menu, click Tasks > Tools and choose a desired tool. For requirements and usage information, see Computer management tools.

For high availability, multiple Enrollment Servers (ESs) can be added to each Site. All enabled and verified ESs will be used in an active/active fashion. Upon user login, requests from workload VMs such as RD Session Hosts or VDIs are equally distributed among the available ESs. In case of failures on a particular ES, the next available ES is selected and the SAML SSO authentication process continues. Specifically required for manual deployment of multiple ESs, it is important to note that all ESs in the same site share the same registration key which is required to be deployed in the specified path as mentioned in the RAS Enrollment Server configuration section.

Parallels RAS 17.1 and newer support the Security Assertion Markup Language (SAML) authentication mechanism. SAML is an XML-based authentication that provides single sign-on (SSO) capability between different organizations by allowing user authentication without sharing the local identity database.

As part of the SAML SSO process, the new RAS Enrollment Server communicates with Microsoft Certificate Authority (CA) to request, enroll, and manage digital certificates on behalf of the user to complete authentication without requiring the users to put in their Active Directory credentials. Service providers and enterprises with multiple subsidiaries don’t have to maintain their own internal Identity Management solutions or complex domains/forest trusts. Integrating with third-party Identity Providers allows customers and partners to provide end users with a true SSO experience.

When you have the SAML SSO authentication configured, you can test it as described below.

Service provider initiated authentication

1. Use a web browser to open the RAS Web Client (or use a platform-specific Parallels Client), specifying the Theme to which you assigned the identity provider.

2. Start a published application. Check that the application session was started successfully.

3. Create one more Theme, add one more IdP providers and then connect specifying the new Theme. Launch another application.

Identity provider initiated authentication

1. Use the web browser to connect to the identity provider portal.

2. Start a published application. Check that the application session was started successfully.

Parallel Web Client

No additional configuration is needed.

Parallels Client for Windows

See Parallels Client for Windows User’s Guide.

Parallels Client for Mac

To configure Parallels Client for Mac for SAML SSO authentication:

1. Select a connection (or create a new one) and open its properties.

2. On the Connection tab, in the Login section, select Web as authentication type.

3. Select the Advanced tab and select or clear the Use default OS browser option (Web authentication section). If the option is selected, the SAML SSO login dialog will open in the default browser. If the option is cleared, the browser built into the Parallels Client will be used.

4. Close the dialog to save the connection properties.

When connecting to Parallels RAS, a dialog will open in a web browser asking the user to enter credentials to be verified by the identity provider. If the credentials are valid, the list of published applications will appear in the Parallels Client.

Parallels Client for Linux

To configure Parallels Client for Linux for SAML SSO authentication:

1. Select a connection (or create a new one) and open its properties.

2. On the Connection tab, in the Log in section, select Web as authentication type.

3. If you want to configure additional settings, do the following:

   1. Install the QtWebEngine library.

   2. Select the Advanced Settings tab and click the Connection advanced settings button.

   3. Select or clear the Use default OS browser option in the Web Authentication section. If the option is selected, the SAML SSO login dialog will open in the default browser. If the option is cleared, the browser built into the Parallels Client will be used.

   4. If you are using the built-in browser, select or clear the Open browser window to complete log out option in the Web Authentication section. If this option is selected, a URL will open to perform the logout from SAML. By default, this web page will not be displayed, but if you need to interact with the browser, you can enable this option.

4. Close the dialog to save the connection properties.

On the service provider side (the Parallels RAS side), you need to enable Web (SAML) authentication and add the identity provider to the RAS Farm.

Enable Web (SAML) authentication

1. In the RAS Console, navigate to Connection > Authentication.

2. In the Allowed authentication types section, select the Web (SAML) option.

Adding an IdP to the RAS Farm

To add an IdP:

1. In the RAS Console, navigate to Connection > SAML. If the tab page is disabled, make sure you enabled Web (SAML). See above.

2. Click Tasks > Add.

3. In the Add Identity Provider wizard, specify a provider name.

4. In the Use with Theme drop-down list, select a Theme to which the IdP will be assigned. If you don't have a specific Theme yet, you can use the default Theme or you can select "<not used>" and assign a Theme later. Note that there can be multiple IdPs configured in the same RAS Farm. However, at this time, one IdP can be assigned to one Theme.

5. Select one of the following methods that the wizard will use to obtain the IdP information:

   • Import published IdP metadata: Import from an XML document published on the Internet. Specify the document URL taken from the IdP side configuration.

   • Import IdP metadata from file: Import from a local XML file downloaded from the IdP application. Specify the file name and path in the field provided.

   • Manually enter the IdP information: Select this option and then enter the information manually on the next wizard page.

6. Click Next.

7. If the configuration was imported in the previous step, the next page will be populated with data obtained from the XML file. If you've selected to enter the IdP data manually, you'll have to enter the values yourself:

   • IdP entity ID: Identity provider entity ID.

   • IdP certificate: Identity provider certificate data. To populate this field, you need to download the certificate from the IdP side, then open the downloaded file, copy its contents and paste it into this field.

   • Logon URL: Logon URL.

   • Logout URL: Logout URL.

   Select the Allow unencrypted assertion option if needed.

1. At this point, you can configure service provider (SP) settings to be imported on the IdP side (IdP portal). You can do it now or you can do it later. To do it now, follow the steps below. To do it later, click Finish and then, when needed, open the identify provider object properties, select the SP tab and do the same steps as described below.

2. To configure SP settings, click the Service provider information button.

3. In the dialog that opens, enter the host address. The IdP will redirect to this address, which should be accessible from the end user browser.

4. The other fields including SP Entity ID, Reply URL, Logon URL and Logout URL are prepopulated based on the host address. The SP Certificate is autogenerated.

5. Next step is to complete the IdP configuration based on the values above. These values can be manually copied or exported as a metadata file (XML). Click the Export SP metadata to file link. Save the metadata as an XML file. Import the XML file into your IdP.

6. Close the dialog and click Finish.

Configuring user account attributes

When user authentication is performed by the IdP, user account attributes in Active Directory are compared with the matching attributes in the IdP user database. You can configure which attributes should be used for comparison as described below.

The following table lists available attributes:

* The attributes in the SAML name column are editable and can be customized based on the IdP that you are using.

To configure attributes:

1. In the RAS Console, right-click an IdP that you've added in previous steps.

2. In the IdP Properties dialog, select the Attributes tab. On this tab, you can select or clear the attributes to be used for comparison or create custom ones:

   • Attributes that are selected will be compared for a match.

   • The names of all of the preconfigured SAML attributes (the IdP side) can be modified to match the AD attributes as required.

   • The custom attribute can be used to allow any SAML attribute name to match any AD attribute value. By default, it is the email address.

3. Configure and enable the desired attributes as needed based on the attributes configured on the IdP side.

4. Click OK to close the dialog.

Attributes configuration tips

• When possible, use automation for user synchronization (such as Microsoft Azure AD Connect for Azure IdP configuration) between your Active Directory and the IdP to minimize user identity management overhead.

• Choose a user identification attribute that is unique to your environment, such as the User Principal Name (UPN) or Immutable ID (ObjectGuid) when possible. Alternatively, you can use other unique identifiers such as email address. In this case make sure that the Email address field in the user object in the AD is configured. If you use Microsoft Exchange Server, use the Exchange Addresses tab and Exchange policies.

• If using UPN as an attribute, you can also configure alternative UPN suffixes. This can be done from Active Directory Domains and Trusts (select root > right-click to open the Properties dialog). Once a new alternative UPN suffix is created, you can change the UPN on the user object properties from Active Directory Users and Computers.

Adding an account picture

For additional personalization, you can add a custom account picture which will be shown on the Windows logon screen during the user login when using Single Sign-On. This can be done as described in https://kb.parallels.com/en/129028.

In addition to specifying SAML SSO options directly on the client side, you can also set them via the Parallels Client Policy in the RAS Console. To do so:

1. In the RAS Console, select the Policies category.

2. Open the policy properties and navigate to Session > Connection > Primary Connection.

3. In the Authentication type drop-down list, select Web.

4. Navigate to Session > Connection > Web authentication.

5. Select or clear the Use default OS browser option. If the option is selected, the SAML SSO login dialog on the client side will open in the default browser. If the option is cleared, the browser built into the Parallels Client will be used.

See also .

Error messages

Error messages appear in the web browser when something goes wrong with SAML SSO authentication.

Pre HTML5 loading

Post HTML5 loading

Once an application or desktop is launched

For examples of how to integrate various Identity Providers with Parallels RAS, please read the SAML SSO Authentication Examples guide, which is available on the Parallels website at .

When user authentication is performed by the IdP, user account attributes in Active Directory and the IdP are compared with each other for a match. Attributes to be compared are configured on the IdP and in the RAS Console. For details, see SP side configuration (RAS side).

On the identity provider side, you need to do the following:

1. Log in to your preferred IdP platform and create a generic or RAS specific SAML-based application to be used with the Parallels RAS environment.

2. Configure the application and take note of the following configuration properties to be added in Parallels RAS later:

   • Entity ID

   • Logon URL

   • Logout URL

   • Certificate (base64)

3. Alternatively, you can export a metadata file to be imported in Parallels RAS. For additional help, see SAML integration examples and tips.

For security reasons, it is advisable to configure enrollment agent restrictions for a CA to allow only the newly created Enrollment Agent User permissions to enroll certificates on behalf of the users. To do so, follow the steps below.

1. Open the Certification Authority snap-in, right-click the name of the CA, and then click Properties.

2. Click the Enrollment Agents tab, click Restrict enrollment agents, and click OK on the message that appears.

3. Under Enrollment agents, click Add, type the name of the Enrollment agent user created in the previous steps and then click OK. Click Everyone, and then click Remove.

4. Under Certificate Templates, click Add, select the templates that were created (Prls Enrollment Agent and Prls Smartcard Logon) and then click OK. When you have finished adding the names of certificate templates, click <All>, and then click Remove.

5. Under Permissions, click Add, type the names or groups, which are the users or group expected to login to the RAS environment using SAML, and then click OK. Click Everyone, and then click Remove.

6. If you want to block the enrollment agent from managing certificates for other users, computers, or groups, under Permissions, select this user, computer, or group, and then click Deny.

7. When you are finished configuring enrollment agent restrictions, click OK or Apply.