Cloud customer?
Start for Free >
Upgrade in MyJFrog >
What's New in Cloud >





Overview

In many cases, an organization may provide access to Artifactory through a reverse proxy such as NGINX or Apache. In some cases, for example with Artifactory as Docker registry, this set up is even mandatory. To simplify configuring a reverse proxy, Artifactory provides a Reverse Proxy Configuration Generator screen in which you can fill in a set of fields to generate the required configuration snippet which you can then download and install directly in the corresponding directory of your reverse proxy server. You can also use the REST API to manage reverse proxy configuration.

For best security, when using Artifactory behind a reverse proxy, it must be co-located on the same machine as the web server, and Artifactory should be explicitly and exclusively bound to the Proxy host.

We also recommend that you set your Custom Base URL to match your Public Server Name.

Page Contents

 


Reverse Proxy Settings

To configure a reverse proxy, in the Administration module, select Artifactory  | HTTP Settings.

Add your settings, save and click Download to generate your reverse proxy snippet. Place the configuration file in the right place under your reverse proxy server installation and reload the configuration. 

Using NGINX? Note these requirements.

To use NGINX as a reverse proxy to work with Docker, you need NGINX v1.3.9 or higher. The NGINX configuration file should be placed under the sites-enabled directory.

For more details, please refer to Configuring NGINX.

Using Apache? Note these requirements.

Some features in the Apache configuration are only supported from Apache HTTP Server v2.4.

To use Apache as your reverse proxy server, make sure you have the following modules installed and activated:

  • proxy_http
  • rewrite
  • deflate
  • headers
  • proxy_balancer
  • proxy_connect
  • proxy_html
  • ssl
  • lbmethod_byrequests
  • slotmem_shm
  • proxy

Best practice

When using a reverse proxy, it is recommended to pass the X-JFrog-Override-Base-Url header as follows:

For NGINX:

proxy_set_header X-JFrog-Override-Base-Url  $http_x_forwarded_proto://$<host>:<server port>

For Apache:
RewriteCond %{REQUEST_SCHEME} (.*)
RewriteRule (.*) - [E=my_scheme:%1]
[...]
RequestHeader set X-JFrog-Override-Base-Url %{my_scheme}://<server_name>

Server Provider
Set the server provider type: Embedded Tomcat, Nginx and Apache.
Internal Hostname
The internal server name for Artifactory which will be used by the web server to access the Artifactory machine.
If the web server is installed on the same machine as Artifactory you can use localhost, otherwise use the IP or hostname.
Internal Artifactory Port
Direct access to Artifactory for REST API and downloads. This can be configured from the Artifactory System YAML file.
Internal Router Port
Access to the JFrog Platform services REST API and web UI. This can be configured from the Artifactory System YAML file.
Public Server Name
The server name which will be publicly used to access Artifactory within the organization.
Use HTTP
When set, Artifactory will be accessible via HTTP at the corresponding port that is set.
Use HTTPS
When set, Artifactory will be accessible via HTTPS at the corresponding port that is set.
HTTP Port
The port for access via HTTP. The default value is 80.
HTTPS Port
The port for access via HTTPS. The default value is 443.



Using a Load Balancer in High Availability Setups

When configuring Artifactory in a High Availability (HA) setup, Artifactory will automatically adjust the provided settings to include a Load Balancing section within the HTTP settings, allowing for proxying more than one Artifactory instance.


Docker Reverse Proxy Settings

When using Artifactory as an on-prem private Docker registry, the Docker client can access Artifactory through a reverse proxy or directly through Artifactory's embedded Tomcat.

JFrog Artifactory Cloud Docker Registries

 Note that accessing an Artifactory Docker registry on a JFrog Artifactory Cloud installation does not use a reverse proxy since it is external to your organization.

Using a Reverse Proxy

The Docker client can access Artifactory through a reverse proxy using the Subdomain Method(recommended) or through the Ports Method.

For each of these methods, your Docker repositories must be configured with the corresponding Reverse Proxy settings in the Docker Repository Configuration Advanced tabThe Reverse Proxy Configuration screen also sets up your Docker Repository configuration.

Configuring Artifactory as your Docker Registry

This section describes how to obtain your reverse proxy configuration according whether you are using the subdomain method or port bindings. 

Using Subdomain

If you select Subdomain as the Reverse Proxy Method, when configuring a Docker Repository, the Registry Name in the Docker Repository Configuration Advanced tab will be set automatically to the required value, and will use the Repository Key as the Subdomain.

Wildcard certificate

Using the Subdomain method requires a Wildcard certificate such as.*.myservername.org. You also need to ensure that the certificate you use supports the number of levels used in your subdomain.

Docker Settings in HTTP SettingsCorresponding HTTP Settings in Docker Repository Advanced Configuration

Using Port Bindings

If you select Port as the Reverse Proxy Method, when configuring a Docker Repository, you will need to set the Registry Port in the Docker Repository Configuration Advanced tab. Together with the Public Server Name, this is the port the Docker client will use to pull images from and push images to the repository. Note that in order for all of your Docker repositories to be included in your reverse proxy configuration, first you need to set the port for each Docker repository defined in your system, and only then generate the reverse proxy configuration. Note also that each repository must be bound to a unique port

Best Practice

We recommend creating a Virtual Docker Repository which aggregates all of your other Docker repositories, and use that to pull and push images. This way you only need to set up the NGINX configuration for that virtual repository.

Docker Settings in HTTP SettingsCorresponding HTTP Settings in Docker Repository Advanced Configuration


Using Direct Access

To access your Docker repositories Without a Reverse Proxy, you should select Repository Path as the Docker Access Method in the Docker Setting Panel of the HTTP Settings screen. 

Docker Settings in HTTP SettingsCorresponding HTTP Settings in Docker Repository Advanced Configuration

Configuring a Reverse Proxy to Support mTLS 

From Artifactory release 7.38.4, you can also authenticate users using mTLS. To do so will require a reverse proxy and some setup on the front reverse proxy (Nginx).

Reverse Proxy for Cloud Customers

To configure a reverse proxy to support mTLS in the Cloud, you will need to contact JFrog Support to set this up for you.

Configure the Nginx Proxy for Self-hosted Customers

To configure the Nginx proxy, you will need to set this configuration in the Nginx configuration file, and to set the Platform configuration via the system.yaml file. See Configuring Nginx for details.

  1. Set up mTLS by providing a trusted certificate for the JFrog Platform to trust. The trusted certificate can be either the actual client certificate to trust or a CA certificate - to trust any certificate signed by it (preferred). 
  2. Then, use the client certificates to authenticate API requests with the JFrog Platform (requests from untrusted client certificates will be blocked).
  3. You will be able to revoke certificates by revoking (removing) the provided trusted certificate(s). You can also revoke a specific client certificate without requiring revoking the trusted CA certificate using the OCSP protocol.

    You will be able to revoke certificates by revoking (removing) the provided trusted certificate(s). You can also revoke a specific client certificate without requiring revoking the trusted CA certificate.

Setting up mTLS Verification and Certificate Termination on the Reverse Proxy

Setting up mTLS requires you to first set up mTLS verification and certificate termination on your reverse proxy. For example, using Nginx should include something like this:

ssl_verify_client      optional;
ssl_verify_depth       2;
ssl_client_certificate /path/to/client-ca.crt;
...
proxy_set_header X-JFrog-Client-Cert "";
proxy_set_header X-JFrog-Client-Cert $ssl_client_escaped_cert;

The client-ca.crt above is an example of a single file with all trusted client CA certificates.

The reverse proxy should be responsible (by configuration) for:

  • Always removing the custom header from all incoming requests, to prevent a malicious user from adding such header on their own, tricking the platform to accept the header as an authentication and authorization mechanism
  • Adding to the request the custom header with the client certificate only for requests that were successfully mTLS-verified

After setting your reverse proxy, when a request is performed with mTLS, upon successful verification, the reverse proxy must add a custom header with the client certificate in PEM format (refer to the proxy_set_header X-JFrog-Client-Cert in the code example above).

Note that you can also set up your own custom header instead of X-JFrog-Client-Cert. If you choose to do so, you will need to set the same header via the header-name in the system.yaml file (see configuration example below) for the JFrog Platform to use the same header.

Support User Identity Extraction for Request Authorization

You will be able to use your client certificate to authenticate and authorize requests in the JFrog Platform, without the need to send additional credentials, as long as the client certificate embeds the user identity. 

To enable user-based access for client authenticating with mTLS, you can have your certificate contain a username, and the JFrog Platform will only allow access to resources to which that user has permissions.


For example, your certificate's subject might look something like this, whereby Subject: C=IL, L=Netanya, O=Maldin, OU=DO, CN=myuser@jfrog.com, and where the username you are after is "myuser" from the Subject's CN. In this case, you can set the Access YAML Configuration to look something like this:

security:
  authentication:
    mtls: # Mutual-TLS authentication configuration
      enabled: true                        # if true then mTLS is enabled
      extraction-regex: [^@]+(?=\d{0,}@)   # regular expression used to extract the username from the certificate's subject CN

You can also set your regular expression to be what ever you need, in order to parse the username as it is defined in the JFrog Platform from the subject’s CN attribute.

Reverse Proxy to Support mTLS Flow

  1. The client sends a request to the JFrog Platform.
  2. If the request includes a client certificate:
    1. The JFrog Platform will authenticate the client certificate using the configured trusted certificates and verify that the certificate has not been revoked. If the client certificate is authenticated successfully, the procedure will continue; otherwise it is blocked.
    2. The JFrog Platform will then try to extract the user identity from the client certificate.
      If the user identity was extracted successfully, the procedure will continue; otherwise it will fall back to relying on additional user authentication information (e.g., basic credentials, bearer token). 

      If the JFrog Platform is configured to require client certificates, then the request will be blocked; otherwise it will continue with the existing authorization mechanisms without mTLS.


REST API

Artifactory also supports managing reverse proxy configuration through the REST API using the following endpoints:

Get Reverse Proxy Configuration
Retrieves the reverse proxy configuration JSON.
Update Reverse Proxy Configuration
Updates the reverse proxy configuration.
Get Reverse Proxy Snippet
Gets the reverse proxy configuration snippet in text format.
Copyright © 2022 JFrog Ltd.