(Optional) Configure SSL or TLS for AgilePoint Server and 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 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 TLS or SSL, 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
  • How Do I Change the URL for Mobile Devices to use HTTPS?
  • How Do I Configure AgilePoint NX to Connect to On-Premises SharePoint with HTTPS?

Prerequisites

• Important: If your certificate is stored in the Microsoft certificate store, when you export the certificate, select Export all extended properties.

  If this option is not selected, the certificate will cause errors.

  
  
  

Procedure

1. On the AgilePoint Server machine, add the SSL or TLS certificate (.pfx or .pem) files to this folder:

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

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 your AgilePoint Server instance.

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

Prerequisites

• The numbers for the ports you use for binding in AgilePoint Server. You can find these in AgilePoint Server Manager.

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.
24. In a command prompt, enter the following command:

    netsh http add sslcert ipport=0.0.0.0:portnumber certhash=SSL-Certifcate-thumbprint-value-without-spaces appid={c929c857-e10a-48c4-b123-5713faba528e}

25. Restart your AgilePoint Server instance.

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

Procedure

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

2. Do one of these, depending upon your SSL or TLS certificate format:
   • PFX certificate:
     1. Encrypt the password:
        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 encrypt.bat, and click Run as administrator.
        3. In the command prompt, enter the password for the .pfx file.
        4. Click Enter.

           The encrypted password opens in the default text editor, usually Notepad.

     2. In the key pfx, enter the path and file name for your PFX certificate.

        Example:

        "pfx": "Certificates/mycertificate.pfx",

     3. In the the key pfxpassword, enter the encrypted password.

        Example:

        "pfxpassword": "658df8cbceb7499d245df32158dcf3aa83ce3558589sw2547f36d5",

   • PEM certificate:
     1. In the key sslkey, enter the path and file name of the private key file. The file name has the extension .pem or .key.

        Example:

        "sslkey": "Certificates/key.pem",

     2. In the key sslcert, enter the path and file name of the the certificate file. The file name has the extension .crt or .pem.

        Example:

        "sslcert": "Certificates/cert.pem",

3. Change the value of the key httpsenabled to true:

   "httpsenabled": true,

4. 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",

5. 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",

6. 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",

7. Save and close the file web.yaml.
8. Restart your AgilePoint Portal 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 SSL or TLS 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 SSL or TLS for AgilePoint NX Portal.