PKI Authentication for Nexus

Repository Manager | Reading time: 8 minutes

In this guide:

Overview

This technical guide explains how public key infrastructure (PKI) authentication works with Nexus products - both Repository Manager and IQ Server. This is written for Nexus administrators, and should take about 15 minutes to read. By the end of this article, you’ll be able to:

  • Understand what PKI authentication is and why you may want to implement it at your organization.
  • Set up and configure a reverse proxy server for PKI authentication.
  • Configure Nexus Repository Manager and/or Nexus IQ Server to accept the SSO header containing the user identifier.

Using PKI Authentication

The basics of PKI authentication are about how two objects learn to communicate messages securely. This secure relationship is based on trust, and PKI is a robust system that understands a lot of different networks that may or may not share a common trust authority. The PKI system negotiates trust with a root that then tells you all the other things you can trust. Think of it like an introduction by a friend to someone you don’t already know - meaning there are some PKI keys you already trust (your friend) that can then delegate their trust (and yours) to other keys you don’t yet know (the person you just met). In terms of Nexus products, the PKI service says “I have verified that this user is X.” This is then passed through the reverse proxy which creates a header containing this identifier. Nexus products (Repository Manager or IQ Server) trust this header and the user is then granted access.

With Nexus products, implementing PKI authentication is usually driven by an enterprise requirement. For instance, use of PKI is mandated on Federal Government networks and systems. It’s important to remember that PKI is all about authentication. We’re not talking about authorization here. This means using PKI to authenticate lets you determine who a user is, but not what they can access. PKI is a secure form of authentication because a certificate usually has a key or PIN associated with it that is required for use. Unique and signed certificates are provided for each build user, user for a particular application, or an NPE (nonperson entity). There are no group accounts with this method - every person and non-person is issued a unique certificate that is traceable back to that entity.

Implementing PKI provides a modern and secure form of authentication. At Sonatype, most plugins and servers support PKI authentication using an appropriately configured reverse proxy server. We’ll go over the reverse proxy setup in the next section.

Using a Reverse Proxy Server

A reverse proxy is a kind of server that sits between a user’s browser and a Nexus server (IQ or Repository). The reverse proxy can perform authentication activities and then add additional information to a request on behalf of the client. You need a reverse proxy server to use PKI authentication with Nexus products.

You can use a single reverse proxy in front of multiple Nexus services (say IQ and Repository) or run a separate co-located proxy process on each server. Using a single proxy for multiple Nexus services requires that they listen on different ports, whereas the co-located proxies allow you to use the same port, say 443, for each service.

PKI works within the reverse proxy server by requesting a certificate from the client to see who they are and then verifying that the certificate was issued by the designated Certificate Authority (CA) and has not been revoked (via a Certificate Revocation List - CRL). If that process is successful, then the reverse proxy creates a header that contains some sort of identifier (like an email address, ID number, or full name). That header is passed onto Nexus Repository Manager (or IQ Server) along with the original content of the session. Nexus servers are configured to accept this header as an authoritative source. From here, the servers have to use some mechanism, such as LDAP, to look up the authorization portion of this transaction. The diagram below is a visual example of how the reverse proxy setup could work:

If you need some examples of reverse proxy setup, you should check out Apache or NGINX.

NOTE: All traffic to the Nexus servers must pass through the reverse proxy server.

When you’re configuring PKI, it’s very important to do it in a way that does not allow anyone to bypass the reverse proxy server. All traffic to Nexus Repository (and IQ Server) has to pass through the reverse proxy, otherwise someone could insert the header into their traffic stream and be anyone they want to be. To ensure this doesn’t happen, you should isolate the Nexus servers so that you can’t get to them directly, forcing you to go through the reverse proxy.

Configuring the Reverse Proxy

The following is an example proxy configuration in Apache. When you connect to the proxy server, it’s going to do the authentication piece, and if successful, then it’s going to insert the X-SSO-USER header and pass your traffic through.

The first snippet basically says, “hey I want you to be an SSL proxy.” The SSL verify client require line says that you have to provide a client certificate. The CA Certificate file line says that it has to be issued from that authority. And finally, the SSO user header is defined.

SSLProxyEngine on
   SSLProxyVerify none
   SSLProxyCheckPeerCN off
   SSLProxyCheckPeerName off

   SSLOptions +StdEnvVars
   SSLVerifyClient require
   SSLCACertificateFile “/etc/pki/tls/certs/Your-CA-Cert.crt”

   # set header to upstream, SSL_CLIENT_S_DN_CN can change to use other identifiers
   RequestHeader set X-SSO-USER “%{SSL_CLIENT_S_DN_CN}

NOTE: It doesn’t matter what you use as the request header name (in this case X-SSO-USER) - it just has to be the same on both the reverse proxy and the respective Nexus Server.

Next, the following snippet says “anything that comes through, send it to the server listening on localhost port 8443.” This configuration would be appropriate for a reverse proxy running on the same host as the Nexus server, with incoming traffic going to port 443 and then being proxied to the server on port 8443. In this situation, the Nexus server on port 8443 should be bound to localhost only, or the firewall should block direct traffic to port 8443.

# Proxy requests
#<LocationMatch “/(.*)“>
 ProxyPass / https://127.0.0.1:8443/ connectiontimeout=5 timeout=90 retry=0
 ProxyPassReverse / https://127.0.0.1:8443/
#</LocationMatch>

Configuring IQ Server for PKI

The IQ Server can be configured to accept a reverse proxy configuration in the config.yml file, allowing you to specify the exact header field to be used:

# Configures reverse proxy authentication for the web UI.
reverseProxyAuthentication:
   # Set to true to activate authentication
   enabled: true
   # Name of the HTTP request header field that carries the username
   usernameHeader: "X-SSO-USER"
   # Set to true for backward compatibility with old client plugins
   csrfProtectionDisabled: false
 # The service URL that will be redirected to when a user requests logout.
 logoutUrl: http://localhost/logout/index.html

Configuring Nexus Repository for PKI

Nexus Repository Manager reverse proxy configuration is done via the user interface.

Nexus Repository Manager 2

Remote user authentication support in Nexus Repository Manager v2 can be activated via the user interface by activating the Rut Auth Realm and configuring the Rut Auth capability as displayed below:

  1. Log in as a user with administrative rights.
  2. Access Server via the Administration menu section on the left.
  3. Navigate to the Security Settings section.
  4. Move the Rut Auth Realm to the top of the Selected Realms list.
  5. Save the Server settings.
  6. Access the Capabilities configuration in the Administration menu section.
  7. Add a capability by clicking New.
  8. Select Rut Auth as the Type for the new capability.
  9. Configure the HTTP Header name to the value used by your PKI system, e.g. X-SSO-USER.
  10. Click Add to save the new capability.

With this configuration in place, any username that is passed to Nexus Repository Manager v2 via the configured HTTP header field is assumed to be authenticated. The access level for the specific user is determined by the access rights for a matching user name found in the internal security setup or any configured LDAP system and the associated roles.

Nexus Repository Manager 3

Remote user authentication support in Nexus Repository Manager v3 can be activated via the user interface by activating the Rut Auth Realm and configuring the Rut Auth capability as displayed below:

  1. Log in as a user with administrative rights.
  2. Access the Server configuration in the Administration menu section on the left.
  3. Navigate to the System section and select Capabilities.
  4. Click Create Capability and then select Rut Auth.
  5. Configure the HTTP Header name to the value used by your PKI system, e.g. X-SSO-USER, and click Create capability.
  6. Now click Realms under Security in the Administration menu on the left.
  7. Move the Rut Auth Realm to the top of the Active list.
  8. Click Save.

With this configuration in place, any username that is passed to Nexus Repository Manager v3 via the configured HTTP header field is assumed to be authenticated. The access level for the specific user is determined by the access rights for a matching user name found in the internal security setup or any configured LDAP system and the associated roles.

Further Reading

In addition to this guide, we have some supplemental info in our help docs that may be helpful for PKI implementation.