Hyrax - User Identification (Authentication)

Overview

This document is intended to help those that have been asked to deploy Hyrax into an environment where authentication of users is required. In many such cases Hyrax will be integrated into an existing instance of the Apache Web server (httpd) where authentication services are already configured and in use. In other cases people will be setting up a standalone instance of Tomcat and will be needing to configure it to use one of the supported authentication services. This document means to address both situations.

Terms

Authentication

This is the process of confirming the identity of the user. The end result is a User ID (uid or UID) which may be accessed by the software components via (both?) the Apache API (mod_*) and the Java ServletAPI (Tomcat servlets) used to trigger authorization policy chains or may be logged along with relevant request information.

Identity Provider (IdP)

Also known as an Identity Assertion Provider an Identity Provider (IdP) is a service that provides authentication and identity information services. An IdP is a kind of provider that creates, maintains, and manages identity information for principals and provides principal authentication to other service providers within a federation, such as with web browser profiles.

Service Provider (SP)

A Service Provider (SP) is a Web Service that utilizes an IdP service to determine the identity of it's users. Or more broadly, a role donned by a system entity where the system entity provides services to principals or other system entities.

With respect to this document Hyrax/Tomcat, and Hyrax/Tomcat/Apache each become part of an SP through the installation and configuration of software components such as mod_shib (shibboleth) .

See Service Providers, Identity Providers & Security Token Services explained for more.

Apache

There are many authentication methods available for use with our friend httpd. Each of them may have a unique installation and configuration activity, below we will discuss common changes that must be made to the Tomcat configuration plus using LDAP and Shibboleth.

NB

If you are deploying Hyrax with an existing Apache service then it is likely that all you have to do is configure Tomcat correctly and define security constrains in Apache

Configure Apache to use Tomcat a Proxy

In /etc/httpd/conf.d create a file called hyrax.conf . Edit the file and add following:

<Proxy *>
    AddDefaultCharset Off
    Order deny,allow
    Allow from all
</Proxy>
 
ProxyPass /opendap ajp://localhost:8009/opendap
ProxyPassReverse /opendap ajp://localhost:8009/opendap

This will expose the web application "opendap" (aka Hyrax) through Apache.

Tomcat/Hyrax

The primary result of the Apache authentication (the uid string) must be correctly transmitted to Tomcat. On the Tomcat side we have to open the way for this by configuring a AJP Connector object. This is done by editing the file:

$CATALINA_HOME/conf/server.xml

Edit the server.xml file, and find the AJP Connector element on port 8009. It should look something like this:

<Connector port="8009" protocol="AJP/1.3" />

This line may be "commented out," with <!-- on a line before and --> on a line after. If so, remove those lines. If you cannot find the AJP connector element, simply create it from the code above.

• In order to receive authentication information from Apache, you must disable Tomcat's native authentication. Set the tomcatAuthentication attribute to "false" - see below for an example.
• If your Apache web server is using SSL/HTTPS (and it should be), you need to tell Tomcat about that fact so that it can construct internal URLs correctly. Set the scheme attribute to "https" and the proxyPort attribute to "443" - see below for an example.
• For increased security, disable access to the connector from anywhere but the local system. Set the address attribute to "127.0.0.1" - see below for an example.

When you are finished making changes, your connector should look something like this:

    <Connector 
        port="8009" 
        protocol="AJP/1.3" 
        redirectPort="443" 
        scheme="https"
        address="127.0.0.1" 
        enableLookups="false"  
        tomcatAuthentication="false" 
        />

port

The Connector will listen on port 8009.

protocol

The protocol is AJP/1.3.

redirectPort

Secure redirects to port 443 which is the nominal Apache HTTPS port.

scheme

Ensure that scheme is HTTPS

address

The loopback address (127.0.0.1) ensures that only local requests for the connection will be serviced.

enableLookups

A value of true enable DNS look ups so that the Servlet API call HttpServletRequest.getRemoteHost() returns a host name and not an IP address. Set this to false to improve performance.

tomcatAuthentication

A value of false will allow the Tomcat engine to receive authentication information (the uid and in some cases other attributes) from Apache httpd. A value of true will cause Tomcat to ignore Apache authentication results in favor of it's own.

Restart Tomcat to load the new configuration. Now your Tomcat web applications should see all of the Apache authentication attributes. To retrieve them, use request.getRemoteUser() or request.getAttribute("ATTRIBUTE NAME"). Note that request.getAttributeNames() may not list all available attributes – you must request each attribute individually by name.

Apache Security Constraints

While the detail of the Apache security constraints differ somewhat from one IdP to the next what is consistent is that you will need to define a security constraint on Hyrax inside the httpd.conf chain of files. The most simple example, that you want all users of the Hyrax instance to be authenticated, would look something lie this:

<Location /opendap>
  AuthType YourFavoriteAuthTypeHere
  require valid-user
</Location>

Where the require valid-user attribute makes the requirement that all accessors be authenticated. More complete examples are presented in the LDAP and Shibboleth sections below.

LDAP (mod_ldap, mod_authnz_ldap)

In order to get Apache httpd to use LDAP authentication you will have configure an Apache security constraint on the Hyrax web application. For this example we will configure Apache to utilize the Forum Systems public LDAP server

• All user passwords are password.
• Groups and Users:
  • mathematicians
    • riemann
    • gauss
    • euler
    • euclid
  • scientists
    • einstein
    • newton
    • galieleo
    • tesla

Edit the file /etc/httpd/conf.d/hyrax.conf. Add the following at the end of the file:

# You may need to uncomment these two lines...
# LoadModule ldap_module modules/mod_ldap.so
# LoadModule authnz_ldap_module modules/mod_authnz_ldap.so

# You may want to comment out this line once you have it working.
LogLevel debug

<Location /opendap/data>
   Order deny,allow
   Deny from all
   AuthType Basic
   AuthName "Forum Systems Public LDAP Server-  Login with user id"
   AuthBasicProvider ldap
   AuthzLDAPAuthoritative off
   AuthLDAPURL ldap://ldap.forumsys.com:389/dc=example,dc=com
   AuthLDAPBindDN "cn=read-only-admin,dc=example,dc=com"
   AuthLDAPBindPassword password
   AuthLDAPGroupAttributeIsDN off
   ErrorDocument 401 "Please use your username and password to login this Hyrax server"
   Require valid-user
   Satisfy any
</Location>

Restart Apache httpd and you should now need to authenticate to access anything in /opendap/data

Tomcat

==