Skip to main content

How to Configure Request Header Authentication with Apache

Rich Seddon
Updated

Overview

Request header authentication allows you to use an external system to validate the login credentials of users accessing Nexus Repository or IQ Server. The validated user ID is sent via an HTTP request header. Request header authentication is useful to implement single sign-on (SSO), and is useful for using authentication schemes that are not currently supported, such as Kerberos.

This article will walk you through the steps needed to set up request header authentication for Nexus Repository 3 using the Apache web server. 

Configuration for IQ Server is almost identical, except that the method used to configure the request header is different. See here for details:

It is recommended that you follow the steps in this guide and get everything working as described here before attempting to configure Apache for more advanced types of authentication. It is also recommended that you test each step after completing it before proceeding to the next step.

Step 1 - Configure Nexus Repository 3 for Security Authentication and Authorization via LDAP or Crowd

An HTTP request header can only be used for authentication (validation of login credentials). Authorization (mapping of users to roles and privileges) needs to be done via another mechanism. This will allow you to map groups defined in external servers such as Active Directory to sets of roles and privileges. Instructions for configuring external user management systems can be found here:

Once you have the integration with the external user management system working then you need to grant users in your external systems access. Here is the mechanism available to do this:

For large numbers of users, it is highly recommended to use external role mappings. It's far easier to manage users in a system such as Active Directory which has been specifically designed for the task.

Once you have your user mappings configured be sure to test it. Make sure the end users you've mapped in from the external authentication system can log in and access the resources you've granted access to.

Step 2 - Configure a Request Header Authentication in Nexus Repository 3

The Nexus Repository 3 side of request header authentication is quite simple, we just need to let Nexus Repository 3 know what HTTP header is going to contain the authenticated user ID.

To set this up:

  1. Go to "administration/capabilities" in the UI
  2. Click on "new" to add a new capability
  3. Select the "Rut Auth" capability
  4. Fill in the header name. This article assumes you will use "X-Proxy-REMOTE-USER" as the header name.
  5. Save

When the capability is first created and marked Enabled, the RUT Auth Realm will automatically get added to the Selected Realms list under Administration -> Server -> Security Settings -> Selected Realms.

Make sure that this realm is added later manually if you initially add the capability but do not enable it.

For more information see here:

Step 3 - Configure Apache

Next, we need to configure four things in Apache:

  1. Load the modules needed for this setup
  2. Configure basic authentication
  3. Set the X-Proxy-REMOTE-USER header
  4. Configure Apache as a reverse proxy in front of Nexus Repository 3

Step 3a - Load Modules

The following Apache modules will be needed in order to run the configuration below:

  • mod_proxy
  • mod_proxy_http
  • mod_headers
  • mod_rewrite

These can be loaded via LoadModule directives in httpd.conf. But different distributions of Apache will have modules loaded in different ways. It's best that you consult the documentation for your Apache distribution to find the recommended mechanism for loading modules.

Step 3b - Configure Apache HTTP Basic Authentication

For the purpose of this article, we are going to set up simple authentication in Apache. You will need to replace this later with a more secure authentication system. That is not covered in this article, you'll need to consult the Apache documentation for information about other authentication systems.

Full instructions for setting up simple authentication in Apache can be found here:

Basically, you just need to run:

htpasswd -c /home/test/passwd username

The "htpasswd" command comes as part of your Apache distribuion:

Running the above command will prompt you for a password for user "username", and then write out a password file at the specified location. Additional users can be added with:

htpasswd /home/test/passwd <user-id>

Next, add a location directive to the http.conf file, and configure Apache for basic authentication using the password file you created previously:

<Location /nexus>
#Configure basic authentication (for testing purposes)
AuthType Basic
AuthName "Sonatype Nexus"
AuthBasicProvider file
AuthUserFile /home/test/passwd
Require valid-user
</Location>

You can test the above by visiting http://localhost/nexus in a browser. You should be prompted for authentication by the browser. Entering the credentials of one of the users you configured above should work.

Note: Web browsers will cache credentials entered for HTTP basic authentication until they are restarted. So you'll need to restart your browser to get the loging prompt again. Using HTTP basic browser authentication is only shown here for testing purposes, you should replace this with a more robust authentication mechanism for production purposes.

Step 3c - Set the Authenticated User ID in a Request Header

Authenticated users in Apache are made available via the REMOTE_USER server variable. Unfortunately, there doesn't appear to be a way to make server variables directly available for setting in the request header, so we need a bit of trickery:

# Make REMOTE_USER set by authentication available as environment variable
RewriteEngine on
RewriteCond %{REMOTE_USER} (.*)
RewriteRule .* - [E=ENV_REMOTE_USER:%1]
RequestHeader set X-Proxy-REMOTE-USER %{ENV_REMOTE_USER}e

The RewriteRule rule above fires for every request and sets the environment variable ENV_REMOTE_USER equal to the value of REMOTE_USER, which is itself set by the apache authorization module. The RequestHeader sets a request header named X-Proxy-REMOTE_USER with the value of ENV_REMOTE_USER in the request sent to Nexus Repository 3.

Additionally, we need to unset any authorization headers being sent from the original request, these aren't needed, and should not be sent to Nexus Repository 3. This is accomplished with:

# Remove incoming authorization headers, Nexus users are authenticated by HTTP header
RequestHeader unset Authorization

Step 3d - Configure Apache as a Reverse Proxy

Next, we need to configure Apache as a reverse proxy in front of Nexus Repository 3. For testing purposes, this will work:

# Configure apache as a reverse proxy for Nexus
ProxyPreserveHost on
ProxyPass http://localhost:8081/nexus
ProxyPassReverse http://localhost:8081/nexus

Additional configuration will likely be needed for production, particularly if you are using Apache to serve SSL (http) pages. You can find full documentation for configuring Apache as a reverse proxy for Nexus Repository 3 here:

Step 3e - Completed Configuration

For reference, here is the full configuration from above:

<Location /nexus>
#Configure basic authentication (for testing purposes)
AuthType Basic
AuthName "Sonatype Nexus"
AuthBasicProvider file
AuthUserFile /home/test/passwd
Require valid-user

# Make REMOTE_USER set by authentication available as environment variable
RewriteEngine on
RewriteCond %{REMOTE_USER} (.*)
RewriteRule .* - [E=ENV_REMOTE_USER:%1]
RequestHeader set X-Proxy-REMOTE-USER %{ENV_REMOTE_USER}e

# Remove incoming authorization headers, Nexus users are authenticated by HTTP header
RequestHeader unset Authorization

# Configure apache as a reverse proxy for Nexus
ProxyPreserveHost on
ProxyPass http://localhost:8081/nexus
ProxyPassReverse http://localhost:8081/nexus
</Location>

Step 4 - Restrict the IP subnet for Nexus Repository 3

In order to make the above configuration secure you must restrict access to Nexus Repository 3 by subnet or IP address. Without this restriction a user could bypass the Apache instance and log directly into Nexus Repository, or worse, they could craft a malicious request with the remote user header set and gain access to resources they should not normally be able to see.

There are two ways you can restrict access, by subnet, or by IP address. Restriction by subnet is easiest, and is usually sufficient, particularly if Apache and Nexus Repository are running on the same machine.

To restrict by subnet edit $NEXUS_HOME/conf/nexus.properties and look for this line:

application-host=0.0.0.0

This line is telling Nexus Repository 3 to listen for connections on all network interfaces. To restrict this, simply replace "0.0.0.0" with the IP address of the network interface which is on a restricted subnet. For example, if both Nexus Repository and Apache are on the same machine then you can tell Nexus Repository to only listen on the loopback network:

application-host=127.0.0.1

Restriction by IP address is a bit more complex, see here for details:

Step 5 - Replace Basic Authentication with a More Robust Security Mechanism

It is beyond the scope of this article to cover more advanced authorization schemes such as Kerberos, this is left as an exercise to the reader. Apache supports a wide variety of authorization schemes, a web search will turn up lots of information on how to get these working.

Here are a few resources for Kerberos that you may find useful:

Apache supports many other authentication systems, such as Oath, etc. There are lots of tutorials and examples available on the web for these.

Related articles