Using a Certificate for the HTTPS Protocol

Requesting a SAN SSL Certificate From the Certificate Authority

This section provides an explanation on how to enable the HTTP protocol for the communication between Orchestrator and the Robots.

It is preferable to use a SAN SSL certificate submitted to a Certificate Authority rather than a self-signed one because no certificate has to be installed on Robot computers in the former case. The SAN SLL certificate issued by the Certificate Authority is trusted by all the computers in the domain.

If the primary Orchestrator machine is registered into an Active Directory that has a local Certificate Authority and an auto-enrollment policy, the user may fill a certificate request, as described in the following procedure.

1. Press Windows and R keys, type certlm.msc , and click OK to open the Certificates snap-in.
2. Right-click the Personal node, select All Tasks, then Advanced Operations, and Create Custom Request. Click Next in the Before You Begin window.
   
   

   

   
   
3. In the Select Certificate Enrollment Policy window, choose Active Directory Enrollment Policy, and click Next.
4. In the Custom Request window, pick a certificate template designated for web server use. It should be called Web Server or Web.SAN. If no template is defined, choose (No template) Legacy Key. Then, select PKCS #10 as your request format.
   
   

   

   
   
5. In the Certificate Information window, click on the Details button corresponding to your request, and then select Properties to open the Certificate Properties window and customize the certificate request.
   
   

   

   
   
6. Customize the information in the Subject tab as described below:

   6.1. In the Subject name section, go to Type, and select Common Name from the drop-down menu. In the Value field, type the fully qualified domain name (FQDN) of the machine, e.g. myhost.domain.local. Then click Add.

   6.2. In the Alternative name section, go to Type, and select DNS from the drop-down menu. In the Value field, type the machine's FQDN (the same as in step 6.1.). Then click Add.

   6.3. If Orchestrator is installed on multiple nodes, you need to add all these FQDNs, as described in step 6.2. Also add the FQDN of the load balancer.

   
   

   

   
   
7. Customize the information in the Private Key tab as described below:

   7.1. In the Cryptographic Service Provider box, go to Select cryptographic service provider (CSP), and check Microsoft RSA SChannel cryptographic Provider (Encryption).

   
   

   

   
   

   7.2. In the Key options section, make sure Key Size is set to at least 2048 and Make private key exportable is checked.

   7.3. In the Key type section, make sure Key usage is set to Exchange.

   
   

   

   
   
8. Click OK in the configuration window and Next in the Certificate Information screen.
9. In the Where do you want to save your offline request? screen, indicate a file path and file name of your choice, e.g. C:\Users\YourUser\Documents\sslRequest.req, and select Base 64 as your file format.
   
   

   

   
   
10. After the Certificate Authority accepts the enrollment request, the certificate is visible in the Personal store.
    Important:

    If the company has a standard procedure/template for obtaining the certificate, the user should refer to that procedure.

    For other environments (e.g. without auto-enrollment policy), you may still use this document as reference for the certificate parameters.

Creating a Self-Signed SAN SSL Certificate

If you need to quickly create an SSL certificate for testing purposes only, you may create a self-signed SAN SSL certificate.

Important: If your Orchestrator machine is running Windows Server 2012 R2, a workaround is needed to create a self-signed SAN SSL certificate. Refer to Creating a Self-Signed SAN SSL Certificate on a Windows Server 2012 R2 Orchestrator Machine for more details.

Creating a Self-Signed SSL Certificate on the Primary Orchestrator Machine

Open a PowerShell console as administrator, and issue the following commands. Don’t forget to customize values according to your environment.

$ssc = New-SelfSignedCertificate -FriendlyName "TestingCertificate" -DnsName "loadbalancer.domain.local","node1.domain.local","node2.domain.local"
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store( "Root", "LocalMachine")
$store.Open("MaxAllowed")
$store.Add($ssc)
$pass = ConvertTo-SecureString -String "myPass" -Force -AsPlainText
Export-PfxCertificate -Cert $ssc -FilePath "C:\temp\testingCertificate.pfx" -Password $pass

The commands above also export the C:\temp\testingCertificate.pfx file for later use.

Once the certificate has been created, make sure that:

• If ApplicationPoolIdentity is used, in the certificate console, navigate to Personal > Certificates. Then, right-click your personal Orchestrator certificate, select All Tasks > Manage Private Keys, and give full permissions to both IIS AppPool\Identity and IIS_IUSRS.

• If a custom account is used, in the certificate console, navigate to Personal > Certificates. Then, right-click your personal Orchestrator certificate, select All Tasks > Manage Private Keys, and give full permissions to the custom user that is set on the Orchestrator Application Pool.

Note:

IIS AppPool\Identity and IIS_IUSRS are local groups and should be searched for under local machine, not under domain.

Importing the SAN Self-Signed Certificate to Other Machines

In order to make the self-signed certificate available on others machines (secondary Orchestrator nodes / Robot machines), open a PowerShell console as administrator, and issue the following commands.

$pass = ConvertTo-SecureString -String "myPass" -Force -AsPlainText
$imported = Import-PfxCertificate -FilePath "C:\temp\testingCertificate.pfx" -CertStoreLocation Cert:\LocalMachine\My\ -Exportable -Password $pass
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store( "Root", "LocalMachine")
$store.Open("MaxAllowed")
$store.Add($imported)

Firefox – Allowing Exceptions

Firefox handles the process a bit differently, as it does not read the certificate information in the Windows store. Rather than installing certificates, it allows you to define exceptions for SSL certificates on particular sites.

When you visit a site which has a certificate error, the warning message in the screenshot below is displayed. The URL you are trying to access is displayed in the blue area. To create an exception to bypass this warning on that specific URL:

1. Click the Add Exception button. The Add Security Exception window is displayed.
   
   

   

   
   
2. In the Add Security Exception window, click Confirm Security Exception to configure this exception locally.
   
   

   

   
   

   Note: If a particular site redirects to subdomains within itself, you may get multiple security warning prompts with slightly different URLs every time. Add exceptions for those URLs by following the steps above.

Troubleshooting Certificates

In case you encounter problems with using a certificate with UiPathOrchestrator.msi (during installation or upgrade), here is where you can start your troubleshooting:

From Control Panel:

1. Open Manage Computer Certificates -> Personal -> Certificates. Identify your certificate and double-click it. In the General tab there should information about its validity.
2. From a command line, run the following command to diagnose the certificate: certutil -v -verifystore My <certificateThumbprint> - its summary is at the end of the output.

Note: You can find your certificate's thumbprint in the Details tab described at Step 1.

Internal Server Error

An internal server error may occur if the certificate does not have the appropriate permissions set. Run the following as Admin to grant the necessary permissions:

import-module WebAdministration
$siteName = 'UiPath Orchestrator'
$binding = (Get-ChildItem -Path IIS:\SSLBindings | Where Sites -eq $siteName)[0]
$certLoc = "cert:\LocalMachine\MY\$($binding.Thumbprint)"
$cert = Get-Item $certLoc
$keyPath = $env:ProgramData + "\Microsoft\Crypto\RSA\MachineKeys\"
$keyName = $cert.PrivateKey.CspKeyContainerInfo.UniqueKeyContainerName
$keyFullPath = $keyPath + $keyName
$acl = (Get-Item $keyFullPath).GetAccessControl('Access')
$permission="IIS_IUSRS","Full","Allow"
$accessRule = New-Object -TypeName System.Security.AccessControl.FileSystemAccessRule -ArgumentList $permission
$acl.AddAccessRule($accessRule)
Set-Acl -Path $keyFullPath -AclObject $acl

After running the script, make sure that:

• If ApplicationPoolIdentity is used, in the certificate console, navigate to Personal > Certificates. Then, right-click your personal Orchestrator certificate, select All Tasks > Manage Private Keys, and give full permissions to both IIS AppPool\Identity and IIS_IUSRS.

• If a custom account is used, in the certificate console, navigate to Personal > Certificates. Then, right-click your personal Orchestrator certificate, select All Tasks > Manage Private Keys, and give full permissions to the custom user that is set on the Orchestrator Application Pool.

Note:

IIS AppPool\Identity and IIS_IUSRS are local groups and should be searched for under local machine, not under domain.

Insights Certificate Error

If you are encountering errors when trying to change your Insights certificate, make sure to follow the instructions provided in Updating the Insights Certificate.

Chromium-based browsers certificate error

If a certificate error occurs when using Chromium-based browsers, create a self-signed certificate with a digital signature as follows:

1. Open a PowerShell console as administrator, and issue the following commands. Don’t forget to customize values according to your environment.

   $cert = New-SelfSignedCertificate -FriendlyName "MyServerSSL" -DnsName “example01” -CertStoreLocation "cert:\LocalMachine\My" -KeyUsage DigitalSignature,KeyEncipherment,DataEncipherment -KeyAlgorithm RSA -HashAlgorithm SHA256 -KeyLength 2048 -KeyUsageProperty All -Provider "Microsoft Enhanced RSA and AES Cryptographic Provider" -NotAfter (Get-Date).AddYears(5)
   $pwd = 'p@ssw0rd'
   $SSpwd = ConvertTo-SecureString -String $pwd -Force -AsPlainText 
   Export-PfxCertificate -Cert "Cert:\LocalMachine\My\$($cert.Thumbprint)" -FilePath custom_cert.pfx -Password $SSpwd
   Export-Certificate -Cert "Cert:\LocalMachine\My\$($cert.Thumbprint)" -FilePath custom_public.cer

   Note:

   The commands also export the .pfx file for later use.
2. Once the certificate has been created, you should also take into account the following scenarios:
   • If ApplicationPoolIdentity is used:
     • In the certificate console, navigate to Personal, then to Certificates.
     • Right-click your personal Orchestrator certificate, select All Tasks, then Manage Private Keys.
     • Give full permissions to both IIS AppPool\Identity and IIS_IUSRS.
   • If a custom account is used:
     • In the certificate console, navigate to Personal, then toCertificates.
     • Right-click your personal Orchestrator certificate, select All Tasks, then Manage Private Keys.
     • Give full permissions to the custom user that is set on the Orchestrator Application Pool.
   Note:

   IIS AppPool\Identity and IIS_IUSRS are local groups and should be searched for under local machine, not under domain.

Creating a Self-Signed SAN SSL Certificate on a Windows Server 2012 R2 Orchestrator Machine

Windows Server 2012 R2 does not support the -FriendlyName parameter. If your Orchestrator machine is running this operating system, you need to take the following steps to create a self-signed SAN SSL certificate:

1. Create the certificate on a machine running an OS newer than Windows Server 2012 R2, as described in the Creating a Self-Signed SSL Certificate on the Primary Orchestrator Machine section.
2. Import the self-signed SAN SSL certificate to the Windows Server 2012 R2 machine as described in the Importing the SAN Self-Signed Certificate to Other Machines section.

   Make sure to add the certificate to both the Personal and Trusted Root Certification Authorities stores.

3. Press the Windows and R keys, type certlm.msc, and click OK to open the Certificates snap-in.
4. To allow read permissions to the private key, take one of the following steps:
5. If you are using ApplicationPoolIdentity, go to Personal store > All Tasks > Manage Private Keys, and give read permission to the IIS AppPool\UiPath Orchestrator user.
6. If you are using a custom account, go to Personal store > All Tasks > Manage Private Keys, and give read permissions to the custom user that is set on the Orchestrator Application Pool.