Configure SSL or TLS for AgilePoint NX Portal

Prerequisites

• AgilePoint NX OnPremises or AgilePoint NX PrivateCloud.
• To use secure communication, AgilePoint NX requires an SSL or TLS certificate to be installed for each communication port used for AgilePoint Server on the AgilePoint Server machine.
• A full chain SSL or TLS certificate in PFX or PEM format.
  • PFX - The file must be in .pfx format and requires a password.
  • PEM - In most cases, a PEM certificate consists of two files: a private key file (.pem or .key) and a certificate file (.crt or .pem).
  Note: Make sure the SSL certificate chain is complete.

Good to Know

• For security, AgilePoint recommends you use a standard SSL or TLS certificate, and not a self-signed certificate.
• SSL or TLS is required for AgilePoint Server if you use on-premises SharePoint over SSL or TLS.
• AgilePoint NX supports any version of SSL or TLS, but limitations to the versions of SSL or TLS you can use in your environnment may apply based on software or systems outside of AgilePoint NX. The following are examples of restrictions that may apply to the SSL or TLS versions that could apply in your environment. However, the specifc rules depend on your specific configuration:
  • AgilePoint Server relies on the version of SSL or TLS that is configured for .NET on your AgilePoint Server machine. For example, by default, .NET 4.7.1 supports TLS 1.2 or higher.

    This configuration can be changed, but any downgrade in the supported version of SSL or TLS can result in security risks. For more information, see the documentation from Microsoft.

  • Outside services, such as Salesforce, may require certificates with higher levels (or specific levels) of SSL or TLS.

    You can test your certificate with several third-party, web-based services—for example, https://www.digicert.com/help/

  • If you want to connect to mobile apps that use iOS 9 or higher, your certificate must use Apple's App Transport Security standard.

    For more information, refer to NSAppTransportSecurity from Apple.

• The security protocols supported by third-party technologies are subject to change are the responsibility for the associated vendors. These are subject to change without notice from AgilePoint.
• After you configure AgilePoint Server and AgilePoint NX Portal for SSL or TLS, you also must configure serveral other components if they are used in your environments.

  For more information, refer to:

  • Configure SSL or TLS for Analytics Center
  • Change the URL for Mobile Devices to use HTTPS
  • Configure AgilePoint NX to Connect With On-Premises SharePoint with HTTPS

How to Start

1. On the AgilePoint Server machine, in Windows Explorer, right-click the file (AgilePoint Server installation folder) C:\Program Files\AgilePoint\AgilePoint Server\WCFConfigurationUtility.exe, and click Run as Administrator.

   
   
   

Procedure

1. On the AgilePoint Server Manager, select your AgilePoint Windows Service instance.
2. On the Networking tab, in the SSL Settings section, turn on Use Secure Connection (SSL).
3. In the Domain field, enter the common name or domain name for your SSL certificate.
4. Restart the AgilePoint Server instance.

   For more information, refer to Restarting AgilePoint Server and AgilePoint Portal.

Procedure

1. In a command prompt, enter mmc.
2. On the Console Root screen, click File > Add/Remove Snap-in.
3. On the Add or Remove Snap-ins screen, select Certificates, and click Add.
4. On the Certificates snap-in screen, click Computer account.
5. On the Select Computer screen, click Local computer.
6. Click Finish.
7. On the Selected snap-ins section, click Certificates (Local Computer).
8. Click Ok.
9. Click Certificates (Local Computer) > Personal.
10. Right-click on the Certicates and select All Task > Import.
11. On the Certificates Import wizard, click the Next button.
12. In the File name field, browse your SSL certificate.
13. Click Next.
14. On the Private key protection screen, in the Password field, enter the password for the private key.

    This screen shows only when the private key is secured with password.

15. On the Certificate Store screen, select Place all certicates in the following store.
16. In the Certificate Store field, click the Browse button, and select Personal.
17. Click Next.
18. Click Finish.
19. On the Console Root screen, double-click on the imported SSL certificate.
20. On the Certificate screen, click the Details tab.
21. In the Show field, select ALL.
22. Select Thumbprint.
23. Copy the value of the thumbprint and paste it in the text editor.

Prerequisites

• This procedure is only required if an SSL or TLS certificate is already configured for AgilePoint NX portal, and you are replacing the existing certificate with a new one.

Good to Know

• This action removes the association between the certificate and the port number. The certificate is not deleted from the folder path. The same certificate file can be applied to a different port.

How to Start

1. On the AgilePoint Server machine, open this folder:

   (NX Portal installation folder - v9.0 and higher) C:\Program Files\AgilePoint\AgilePointPortalInstance\tools\windows

2. Right-click the file AgilePoint.Portal.Management.exe, and click Run as Administrator.

Procedure

1. On the SSL Management Utility screen, click the Remove SSL tab.

   
   
   

2. On the Remove SSL tab, in the Port field, enter the port number from which to remove the SSL or TLS certificate.

   
   
   

3. Click Remove.

How to Start

1. On the AgilePoint Server machine, open this folder:

   (NX Portal installation folder - v9.0 and higher) C:\Program Files\AgilePoint\AgilePointPortalInstance\tools\windows

2. Right-click the file AgilePoint.Portal.Management.exe, and click Run as Administrator.

Procedure

1. On the SSL Management Utility screen, in the Select the type of Certificate field, select the type of certificate to import.

   
   
   

2. In the Upload Certificate File field, click Browse.

   
   
   

3. Select the certificate from the AgilePoint Server machine to use to configure SSL or TLS.

   The certificate must be in .pfx or .pem format.

   
   
   

4. Do one of these:
   • For a .pfx certificate, do this:
     1. In the Passpharse field, enter the password for the certificate.

        The password is stored in encrypted format in the web.yaml file.

        
        
        

   • For a .pem certificate, do the this:
     1. In the Upload Key File field, click Browse.

        
        
        

     2. Select a private key file from the AgilePoint Server machine.

        
        
        

5. Click Update.

   The utility copies the SSL or TLS certificate files to this folder:

   (NX Portal installation folder - v9.0 and higher) C:\Program Files\AgilePoint\AgilePointPortalInstance\Certificates

6. Click the Apply SSL tab.

   
   
   

7. On the Apply SSL tab, in the Port field, enter the port number to associate with the SSL or TLS certificate.

   
   
   

8. In the CertHashID field, paste the value of the thumbprint you created in Create a thumbprint for the certificate.

   
   
   

9. Click Apply.

   The utility associates the SSL or TLS certificate with the specified port.

10. Restart the AgilePoint Server instance.

    For more information, refer to Restarting AgilePoint Server and AgilePoint Portal.

Good to Know

• When you configure the SSL or TLS certificate for the first time, you must change the URLs in the AgilePoint NX Portal configuration file from HTTP to HTTPS.

How to Start

• On the AgilePoint Server machine, in a text editor, open the AgilePoint NX Portal configuration file:

  (NX Portal configuration folder - v9.0 and higher) C:\Program Files\AgilePoint\AgilePointPortalInstance\config\web.yaml

Procedure

1. In web.yaml, change the value of the key httpsenabled to true:

   "httpsenabled": true,

2. To change the REST URL, find the agilepointserverurl key and change the value so it starts with https://

   The REST URL is the URL for your AgilePoint Server instance.

   For more information, refer to Find your AgilePoint Server Instance REST URL.

   Format:

   "agilepointserverurl": "[Your AgilePoint NX Portal URL]/AgilePointServer",

   Example:

   "agilepointserverurl": "https://myagilepointnxdomain.com:13490/AgilePointServer",

3. To change the Portal URL, find the portalurl key, change the value so it starts with https://

   The Portal URL represents the AgilePoint Portal Instance URL.

   For more information, refer to Find your Portal Instance URL.

   Example:

   "portalurl": "https://myagilepointnxdomain.com:13490",

4. To change the IdP URL, find the idpurl key and change the value so it starts with https://

   The value of the IdP URL is the same as the Portal URL, followed by /idp.

   Format:

   [Your AgilePoint NX Portal URL]/idp

   Example:

   "idpurl": "https://myagilepointnxdomain.com:13490/idp",

5. Save and close the file web.yaml.
6. Restart the AgilePoint Server instance.

   For more information, refer to Restarting AgilePoint Server and AgilePoint Portal.

To test the HTTPS AgilePoint NX Portal REST URL, do the procedure in this topic.

Procedure

1. Open HTTPS REST URL for the AgilePoint NX Portal.

   Format:

   https://[fully qualified domain name]

   Example:

   https://myagilepointnxdomain.com

Error Message 1

If the SSL certificate in use was generated with a legacy encryption mechanism, this error shows:

unsupported

AgilePoint strongly recommends to obtain a new SSL certificate. However, if you still want to support legacy encryption, do these:

1. On the AgilePoint Server machine, in a text editor, open this file:

   (NX Portal installation folder - v9.0 and higher) C:\Program Files\AgilePoint\AgilePointPortalInstance\windows-service\AgilePointPortalService.exe.config

2. Change the value of the arguments key to --openssl-legacy-provider build/index.js.

   <add key="arguments" value="--openssl-legacy-provider build/index.js" />

3. Restart your AgilePoint Portal instance.

   For more information, refer to Restarting AgilePoint Server and AgilePoint Portal

Error Message 2

If the password specified for the .pfx file is not encrypted, this error shows:

The encrypted data is in an invalid format

To resolve this issue, specify the encrypted password.

For more information, refer to Configure an SSL or TLS Certificate for AgilePoint NX Portal.

Error Message 3

If the password specified for the .pfx file is not correct, this error shows:

Looks like the password provided for the pfx certificate type is not matching. Please check your password and try again

To resolve this issue, specify the correct password.

For more information, refer to Configure an SSL or TLS Certificate for AgilePoint NX Portal.