Establish TLS in Artifactory and JFrog Platform

In HTTPS, communication is encrypted using Transport Layer Security (TLS). By default, TLS between JFrog Platform nodes is disabled.

❗️
JFrog Recommends Enabling TLS at Nginx Level
If you want to terminate TLS at the load balancer level, and send HTTP requests to Artifactory, you do not need to enable TLS within the JFrog Platform. Instead, use Nginx to offload HTTPS requests to Artifactory using HTTP, and you can configure Nginx to use your own custom certificate and key. For more information, see Nginx with TLS.

In HTTPS, communication is encrypted using Transport Layer Security (TLS). By default, TLS between JFrog Platform nodes is disabled. When TLS is enabled, JFrog Access acts as the Certificate Authority (CA), signing the TLS certificates and enabling TLS communication between Artifactory, and other JFrog products. For more information, see TLS on JFrog Platform.

When deploying the JFrog Platform using Helm in a Kubernetes cluster, it is recommended that all products connect to Artifactory via its Kubernetes service. To ensure proper TLS validation, the TLS certificate issued by JFrog Access and used by the JFrog Router must include the Service URL in the Subject Alternative Name (SAN) field.

Kubernetes services for JFrog products follow a specific naming convention based on the Helm release name and product name. For example, if the Helm release is jfrog-platform, the generated service names will be as follows:

Artifactory: jfrog-platform-artifactory
Xray: jfrog-platform-xray
General: jfrog-platform-product

This naming convention is important because the full name of the Artifactory service must be added as a newly registered SAN in the Access generated certificate.

Enable TLS in Artifactory

To enable TLS in Artifactory, in the Artifactory's values.yaml file, set security.tls to true under the accessConfig section.
```
access:
  accessConfig:
    security:
      tls: true
```
Add the name of the Artifactory service as a SAN to the Access certificate. You can use Helm templating to automate the process, eliminating the need to specify values based on your release name. The following is an example:
```
access:
  accessConfig:
    security:
      tls: true
      tls-subject-alternative-names:
        - '{{ template "artifactory.fullname" . }}'
```
The template above is set up in our _helpers.tpl file and serves as the Artifactory Service name. This ensures that you always get the correct Artifactory Service name, making automation easier and eliminating the need for hardcoded values.

With the above configurations, Router and Access will now only accept HTTPS connections from external sources, including other JFrog products, when connecting to Artifactory via the service name. In this example, the release name is jfrog-platform:
```
https://jfrog-platform-artifactory:8082
```

❗️
Important
The Access certificate requires the hostname IP, specified by the property shared.node.ip in the Artifactory system.yaml. This IP is automatically added to the Access certificate during startup when Access acts as the Certificate Authority (CA). While you can use a custom certificate as described in the Access TLS documentation, this is impractical in Kubernetes due to the dynamic nature of pod IPs. Instead, we recommend using a custom certificate with Nginx for TLS termination.

Enable TLS for other Products in JFrog Platform

As all JFrog products utilize Router, enabling TLS for any JFrog product is similar.

We will use Xray as an example.

Add the following configuration in Xray’s values.yaml to allow Router to bypass initial TLS verification and pull the certificate.
```
router:
  serviceRegistry:
    insecure: true
```
Once configured, a certificate will be generated under /opt/jfrog/xray/var/data/router/keys, and Router will only accept HTTPS requests.
Ensure that Kubernetes probes communicate with Router over HTTPS by setting router.tlsEnabled=true.
```
router:
  serviceRegistry:
    insecure: true
  tlsEnabled: true
```
Modify the jfrogUrl manually to be the name of the Artifactory service. The following is an example with the service name as jfrog-platform-artifactory and uses HTTPS.
```
xray:
  jfrogUrl: https://jfrog-platform-artifactory:8082
router:
  serviceRegistry:
    insecure: true
  tlsEnabled: true
```
When using the JFrog Platform Chart, which is the recommended approach for utilizing multiple JFrog products, we can employ templating to avoid a hardcoded value for the jfrogUrl, as demonstrated in the example below.

Nginx with TLS

The following sections explain how to disble HTTP and terminate TLS with custom certificate.

Disable HTTP

By default, our Nginx is configured to handle both HTTP and HTTPS requests, so no changes are required for HTTPS to work. However, you may want to disable HTTP since the Router will only accept HTTPS requests. To accomplish this, add the following to Artifactory’s values.yaml:

nginx:
  http:
    enabled: false

If you only want to terminate TLS at the load balancer level and do not need to enable TLS from Artifactory, you must keep this option enabled. This allows Nginx to terminate SSL and pass requests to Artifactory using HTTP.

Terminate TLS with Custom Certificate

To handle HTTPS requests out of the box, we generate certificates on startup (artifactory.gen-certs in our _helpers.tpl) and use them to terminate TLS at the Nginx level. However, your load balancer may need to trust Nginx for this to work correctly.

In this case, you can provide a custom certificate for Nginx to use instead of the generated certificates.

Create a TLS secret using kubectl in the same namespace as Artifactory.

kubectl create secret tls nginx-tls-secret --cert=your-cert --key=your-key -n your-namespace

Add it to your values.yaml.
```
nginx:
  tlsSecretName: nginx-tls-secret
```
This makes Nginx use your own certificate and private key.

Example of Full JFrog Platform Chart

The following is a complete example of establishing TLS communication with Artifactory, Xray, and Distribution while using the JFrog Platform chart. Additionally, the jfrogUrl parameter is shared across all products. We can leverage Helm templating, similar to what we did with the TLS Subject Alternative Name (SAN) configuration, to ensure that the URL starts with HTTPS, corresponds to the service name of Artifactory, and ends with port 8082:

global:
 jfrogUrl: '{{ printf "https://%s-artifactory:8082" .Release.Name }}'

artifactory:
  access:
   accessConfig:
     security:
       tls: true
       tls-subject-alternative-names:
         - '{{ template "artifactory.fullname" . }}'
  nginx:
    http:
      enabled: false
    tlsSecretName: nginx-tls-secret // Optional: You may skip this if you're okay with certificates generated by the Chart.

xray:
 enabled: true
 router:
   serviceRegistry:
     insecure: true
   tlsEnabled: true

distribution:
 enabled: true
 router:
   serviceRegistry:
     insecure: true
   tlsEnabled: true

Add Custom Certificates to JFrog Platform

When Artifactory or other products need to access a remote private resource, such as an LDAP server, you will need to add custom certificates for the JFrog Platform to trust these resources.

Create a secret that contains your certificate chain.

kubectl create secret generic your-certificate-secret --from-file=your-cert.pem -n your-namespace

Specify the certificate secret in the values.yaml. It works the same for all charts.
```
global:
  customCertificates:
    enabled: true
    certificateSecretName: your-certificate-secret
```
During redeployment, the chart will modify one of the initContainers for Artifactory, Xray, or other products to copy the certificates into the trusted directory. This allows the application to load and trust them internally.

📘
Note
When using global.customCertificates within the JFrog Platform chart, all enabled products will load the certificates.

Updated 18 days ago