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.

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.

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.

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
6. Click the Validate AD integration settings button to make sure that the information you've entered is valid.

Using computer management tools

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.

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).

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.

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.

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.

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.

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 https://www.parallels.com/products/ras/resources/.