Set TLS on the JFrog Platform

📘

Note

The way to enable a secure cookie is by enabling TLS on access. When you have HTTPS, the JPD blocks insecure access to the application (HTTP) and adds the secure flag to all JPD cookies.

Step 1: Enable TLS in the JFrog Platform

By default, TLS is disabled in the JFrog Platform. When you enable TLS, all communications to the JFrog Platform are required to use TLS, including service-to-service communication within the platform. In the JFrog Platform, Access acts as the CA and signs the TLS certificates used by all the different JFrog Platform services.

📘

Note

Any options you need to set in the TLS certificate require you to enable TLS.

To enable TLS, set the tls entry (under the security section) in the Access YAML Configuration file to 'true' and rename the file toaccess.config.import.yml.

security:
  tls: true

For Artifactory nodes, the root CA is distributed automatically via the database, and there is no need to copy the Access root CA manually.

For all other JFrog product node, copy the Access root CA manually to the location $JFROG_HOME/{product}/var/etc/security/keys/trusted. For example, copy the Access root CA to $JFROG_HOME/xray/var/etc/security/keys/trusted for Xray.

To set trust in the Access CA by an external server, for example, a load balancer, load the Access root CA file to the external service key store.

📘

Note

When you enable TLS in Artifactory, the UI port remains 8082, while the Artifactory direct service port changes from 8081 to 8443.

Step 2: Set the TLS Certificate

You can choose from the following options to set the TLS certificate.

• Option 1: Use Access as a Root CA with an Access-generated self-signed certificate
• Option 2: Provide your own signed certificate
• Option 3: Provide a custom CA certificate to Access

You can also choose to provide your own signed certificate provided you meet the Prerequisites for Custom TLS Certificate.

Prerequisites for Custom TLS Certificate

When providing your own custom TLS certificate, you will need to provide the matching private key. The certificate will be used by ports 8443 (Artifactory) and 8082 (the Platform router).

By default the JFrog Platform (from Artifactory 7.x and above) requires two public ports. You will need to ensure that both ports are using the same certificate.

• 8443: served by Artifactory (running on Tomcat). This is an open port for direct communication with Artifactory on HTTPS.
• 8082: served by the router

Your custom certificate must meet the following prerequisites.

• The private key must use the RSA algorithm
• The private key must be at least 1024-bit
• The certificate must match the provided private key
• The certificate's issuer must match the CA certificate subject
• The certificate's subject must match the property shared.node.ip from system.yaml
• The certificate's Subject Alternative Names (SAN) must include the certificate's subject
• Key usage extension must be marked CRITICAL
• Key usage digitalSignature extension must be enabled
• Key usage keyEncipherment extension must be enabled
• Extended key usage tlsWebServerAuthentication must be enabled
• Extended key usage tlsWebClientAuthentication must be enabled

Option 1: Use Access as a Root CA with an Access-generated self-signed certificate

1. With TLS enabled, restart the Artifactory node and let the router generate the self-signed certificate with Access.
2. Enable TLS on Artifactory by settingartifactory.tomcat.httpsConnector.enabled in the system.yaml file to true.
3. Restart the Artifactory node.

Option 2: Provide your own signed certificate

This option uses a Custom TLS certificate with the Artifactory and Router ports. Your custom CA certificate must meet the prerequisites.

📘

Note

If you have not started the application for the first time, you need to create the /router/keys/ folder manually.

1. Copy the certificate and key files to the bootstrap/router/keys/custom-server.crt and bootstrap/router/keys/custom-server.key.

   • custom-server.key is the private key file

   • custom-server.crt is the cert file

   Use exactly these names.

2. Copy the CA of the custom TLS certificate in etc/security/keys/trusted/.

3. Restart the Artifactory node and let the router use the bootstrapped certificate.

4. Enable TLS on Artifactory by setting artifactory.tomcat.httpsConnector.enabled to true in the system.yaml file.

5. Restart the Artifactory node again.

6. Copy the CA of the custom TLS certificate in etc/security/keys/trusted/ of all the JFrog Products nodes installed in the same JPD.

7. If applicable, copy the CA to the load balancer.

Option 3: Provide a custom CA certificate to Access

You can provide a custom CA certificate and a matching private key, to be used by Access for signing the TLS certificates used by all the different JFrog Platform nodes.

Your custom CA certificate must meet the prerequisites.

To load a custom CA certificate and matching private key.

1. Create ca.crt and ca.private.key files and place them under $JFROG_HOME/artifactory/var/bootstrap/etc/access/keys.
2. Restart Artifactory.

Regenerate a new Access CA certificate

In some scenarios you might want to force Access to generate a new CA Certificate. To force JFrog Access to regenerate the CA certificate and matching private key, do the following.

1. Create a reset_ca_keys file and place it under $JFROG_HOME/artifactory/var/bootstrap/etc/access/keys.
2. Restart Artifactory.
3. If you have already set TLS between Artifactory and other JFrog Platform nodes, copy the new ca.crt to the trusted directories on all the JFrog Platform nodes.