Skip to content

Latest commit

 

History

History
1143 lines (934 loc) · 43.2 KB

Hyrax_User_Authentication.adoc

File metadata and controls

1143 lines (934 loc) · 43.2 KB

User Authentication

Table of Contents

1. 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.

2. 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) .

3. Apache httpd Authentication Services Configuration

There are many authentication methods available for use with our friend httpd and each of the three illustrated here has a unique installation and configuration activity. There are some common changes that must be made to the Tomcat configuration regardless of the authentication method employed by Apache. We’ll cover those first and then examine LDAP, Shibboleth, and NASA URS IdP configurations for Apache httpd.

Note
 If you are deploying Hyrax with an existing Apache service then it is likely that all you have to do is configure httpd and Tomcat to work together and define and then define a security constraint for httpd that enforces a login requirement (valid-user) for Hyrax.

3.1. Configure Apache httpd and Tomcat to work together

In this part we configure Tomcat and Apache httpd to work together so that httpd can provide proxy and authentication services for Hyrax.

3.1.1. Configure Apache

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
Note
 The ProxyPass and ProxyPassReverse should be set to local host unless a more complex deployment issuing attempted.

This will expose the web application "opendap" (aka Hyrax) through Apache. Make sure that the AJP URLs both point to your deployment of Hyrax.

3.1.2. Taking advantage of Apache Logging

Often when authentication is needed, it is also necessary to log who has logged in and what they have accessed. Apache has a very flexible logging system; that can tell you what users asked for, where they came from, and when they made the request - among other things. For specific authentication technologies it may also be possible to log specific information about UIDs, etc. See the sections below for information on configuring Apache’s log to record that kind of technology-specific data.

3.1.3. Add SSL Capabilities to Apache

This step is not absolutely necessary, but it’s quite likely you will want to do this, particularly if you’re going to use https to access the tomcat servlet engine running the Hyrax front-end. If you use https in the AJP configuration as shown in the next section, you will need to set up Apache to support https even if users don’t access the server with that protocol (because internally, some of the server’s less performance intensive functions work by making calls to itself, and those will use https if you’ve set up tomcat to use https with AJP). However, the configuration is very simple.

First, make sure you have mod_ssl installed. For CentOS 6, use sudo yum install mod_ssl

Next make the needed certs. Here’s how to make and install a self-signed cert for CentOS 6:

# Generate private key
openssl genrsa -out ca.key 2048
 
# Generate CSR
openssl req -new -key ca.key -out ca.csr
 
# Generate Self Signed Key
openssl x509 -req -days 365 -in ca.csr -signkey ca.key -out ca.crt
 
# Copy the files to the correct locations
cp ca.crt /etc/pki/tls/certs
cp ca.key /etc/pki/tls/private/ca.key
cp ca.csr /etc/pki/tls/private/ca.csr

Configure httpd to use the newly installed certs and restart:

  • In the SSL configuration file: /etc/httpd/conf.d/ssl.conf

  • Locate the following key value pairs and make sure the values are correct with respect to your actions in the previous section:
    SSLCertificateFile /etc/pki/tls/certs/ca.crt
    and:
    SSLCertificateKeyFile /etc/pki/tls/private/ca.key

  • Restart the service: sudo /usr/sbin/apachectl restart

Note
 More complete instructions can be found here: http://wiki.centos.org/HowTos/Https.

3.1.4. Configure 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, rather than the default 8443 which is nominally directed to Tomcat.

scheme

Ensures that the scheme is HTTPS. This is a best practice and is simple enough if the server is already configured for HTTPS. If your server is not configured to utilize HTTPS, then you’ll either need to set the value of scheme to "http" or you can undertake to configure your instance of Apache httpd to support for TLS/SSL transport.

address

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

enableLookups

A value of true enables DNS look ups for Tomcat. This means that web applications (like Hyrax) will see the client system as 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 the Tomcat web applications like Hyrax should see all of the Apache authentication attributes. (These can be retrieved programmatically in the Java sServlet API by using HttpServletRequest.getRemoteUser() or HttpServletRequest.getAttribute("ATTRIBUTE NAME"). Note that HttpServletRequest.getAttributeNames() may not list all available attributes – you must request each attribute individually by name.)

3.2. Second: Configure Apache httpd to authenticate

Once Tomcat and Apache httpd are working together all that remains is to configure a security restraint on the Hyrax web application and specify the authentication mechanism which is to used to identify the user.

While the details 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 chain of httpd.conf files. The most simple example, that you want all users of the Hyrax instance to be authenticated, might look something like this:

# This is a simplified generic configuration example; see the sections below for the real
# examples for LDAP, Shibboleth or URS/OAuth2
<Location /opendap>
  AuthType YourFavoriteAuthTypeHere
  require valid-user
</Location>

Where the require valid-user attribute requires that all accessors be authenticated and where YourFavoriteAuthTypeHere would be something like Basic, UrsOAuth2 or shibboleth.

Complete examples for LDAP, URS/OAuth2, and Shibboleth IdPs are presented in the following sections.

3.2.1. LDAP

Note
 You must first configure Apache and Tomcat (Hyrax) to work together prior to completion of this section.

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

Create and edit the file /etc/httpd/conf.d/ldap.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 >
   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 into this Hyrax server"
   Require valid-user
   Satisfy any
</Location>

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

What’s happening here? Let’s look at each of the components of the <Location> directive:

<Location /opendap>

The Location directive limits the scope of the enclosed directives by URL or URL-path. In our example it says that anything on the server that begins with the URL path of /opendap will be the scope of the directives contained within. Generally The Location directive is applied to things outside of the filesystem used by Apache, such as a Tomcat service (Hyrax).

Order deny,allow

The Order directive, along with the Allow and Deny directives, controls a three-pass access control system. The first pass processes either all Allow or all Deny directives, as specified by the Order directive. The second pass parses the rest of the directives (Deny or Allow). The third pass applies to all requests which do not match either of the first two. In this example first, all Deny directives are evaluated; if any match, the request is denied unless it also matches an Allow directive. Any requests which do not match any Allow or Deny directives are permitted.

Deny from all

The Deny directive allows access to the server to be restricted based on hostname, IP address, or environment variables. The arguments for the Deny directive are identical to the arguments for the Allow directive.

AuthType Basic

The AuthType directive selects the type of user authentication for a directory. The authentication types available are Basic (implemented by mod_auth_basic) and Digest (implemented by mod_auth_digest).

AuthName "Forum Systems Public LDAP Server- Login with user id"

The AuthName directive sets the name of the authorization realm for a directory. This realm is given to the client so that the user knows which username and password to send.

AuthBasicProvider ldap

The AuthBasicProvider directive sets which provider is used to authenticate the users for this location. In this example we are saying that an LDAP service will be configured to provide the authentication service.

AuthzLDAPAuthoritative off

The AuthzLDAPAuthoritative directive is used to prevent other authentication modules from authenticating the user if this one fails. Set to off (as in this example) if this module should let other authorization modules attempt to authorize the user, should authorization with this module fail. Control is only passed on to lower modules if there is no DN or rule that matches the supplied user name (as passed by the client).

AuthLDAPURL ldap://ldap.forumsys.com:389/dc=example,dc=com

The AuthLDAPURL directive is used to define the URL specifying the LDAP search parameters. In this example the service is hosted at `ldap.forumsys.com`, on port `389`. The search will be for anyone associated with the domain components `example` and `com` (aka `example.com`).

AuthLDAPBindDN "cn=read-only-admin,dc=example,dc=com"

The AuthLDAPBindDN directive is an optional directive used to specify a `distinguished name` (DN) when binding to the server. If not present mod_authnz_ldap will use an anonymous bind. Many servers will not allow an anonymous binding and will require that the Apache service bind with a particular DN. In this example the server is instructed to bind with the common name (CN) `read-only-admin` at `example.com`

AuthLDAPBindPassword password

The AuthLDAPBindPassword directove specifies the password to be used in conjunction with the AuthLDAPBindDN. In this example the password is the word `password`.

AuthLDAPGroupAttributeIsDN off

The AuthLDAPGroupAttributeIsDN directive is a boolean valued directive that tells `mod_authnz_ldap` wether or not to use the DN of the client username when checking for group membership. In our example the value is set to off so the clients username will be used to locate the clients group membership.

ErrorDocument 401 "Please use your username and password to login into this Hyrax server" :: The ErrorDocument directive specifies what message the server will return to the client in the event of an error. In this example we define a message to be returned for all 401 (Unauthorized) errors to help the client understand that they need to be authenticated to proceed. Require valid-user :: The Require directive selects which authenticated users can access a resource. Multiple instances of this directive are combined with a logical "OR", such that a user matching any Require line is granted access. In this case it’s effect is to say that any valid user that has authenticated (via the LDAP server ldap://ldap.forumsys.com:389 with the distinguished name components dc=example,dc=com) will be allowed access. Satisfy any :: The Satisfy directive defines the interaction between host-level access control and user authentication. It may have a value of either Any or All. The any value indicates that the client will be admitted if they successfully authenticate using a username/password OR if they are coming from a host address that appears in an Allow from directive.

LDAP Authorization Constraints

The Apache module mod_authnz_ldap provides a fairly rich set of “Require” directives which can be used to control (authorize) access to resources serviced by Apache. In the example above the Require directive is quite simple:

   Require valid-user

Which says (since the defined authentication mechanism for the enclosing Location directive is LDAP) that any LDAP authenticated user may be allowed access to anything that begins with the URL-path /opendap. While that may be adequate for some sites, many others will be required to have more complex access control policies in place. The LDAP module mod_authnz_ldap provides a rich collection of Require directive assertions that allow the administrator much more finely grained access control. Rather than provide an exhaustive discussion of these options here we will provide a few basic examples and refer the reader to the comprehensive documentation for the `mod_authnz_ldap` module at the Apache project.

Grant access to anyone in the `mathematicians` group in the organization `example.com`.

    AuthLDAPURL ldap://ldap.forumsys.com:389/dc=example,dc=com
    AuthLDAPGroupAttributeIsDN on
    Require ldap-group ou=mathematicians,dc=example,dc=com

Grant access to anyone who has an LDAP attribute `homeDirectory` whose value is `home`.

    AuthLDAPURL ldap://ldap.forumsys.com:389/dc=example,dc=com
    Require ldap-attribute homeDirectory=home

Combine the previous two examples to grant access to anyone who has an LDAP attribute `homeDirectory` whose value is `home` and to anyone in the `mathematicians` group.

    AuthLDAPURL ldap://ldap.forumsys.com:389/dc=example,dc=com
    AuthLDAPGroupAttributeIsDN on
    Require ldap-group ou=mathematicians,dc=example,dc=com
    Require ldap-attribute homeDirectory=home

The possibilities are vast, but it is certainly the case that the contents of the LDAP service against which you are authenticating, and the richness of the group and attribute entries will in a large part determine the granularity of access control you will be able to provide.

3.2.2. Shibboleth (mod_shib)

Note
 You must configure Apache and Tomcat (Hyrax) to work together prior to completion of this section.

The Shibboleth wiki provides excellent documentation on how to get Shibboleth authentication services working with Tomcat. This is primarily an Apache httpd activity.

Basically you need to follow the instructions for a Native Java Install and as you read, remember - Hyrax does not use either Spring or Grails.

Installation

The logical starting point for this is with the Native Java SP Installation:

But as far as the organization of the work is concerned it is really the last page you need to process, as it will send you off to do a platform dependent Shibboleth Native Service Provider for Apache installation which needs to be completed, working, and configured before you’ll return to the Native Java SP Installation to enable the part where Tomcat and mod_shib pass authenticated user information into Tomcat.

The document path on the Natvie Java Install wiki page will send you off to do Shibboleth Native Service Provider installation which is platform dependent:

Return to the Native Java SP Installation and complete the instructions there.

Configuration

Once the SP installation is completed go to the Native SP Configuration page:

Read that page and then follow the link to the instructions for Apache:

Follow those instructions.

The Shibboleth instructions should have had you add something like this:

<Location /opendap>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  require valid-user
</Location>

to httpd.conf. This will require users to authenticate to access any part of Hyrax which may be exactly what you want. If you want more fine grained control you may want use multiple Location elements with different require attributes. For example:

<Location /opendap>
  AuthType shibboleth
  ShibCompatWith24 On
  require shibboleth
</Location>
<Location /opendap/AVHRR>
  AuthType shibboleth
  ShibCompatWith24 On
  ShibRequestSetting requireSession 1
  require valid-user
</Location>
</apache>

In this example the first Location establishes Shibboleth as the authentication tool for the entire /opendap application path, and enables the Shibboleth module over the entire Hyrax Server.

  • Since there is no ShibRequestSetting requireSession 1 line it does not require a user to be logged in order to access the path.

  • The require shibboleth command activates mod_shib for all of Hyrax.

The second Location states that only valid-users may have access "/opendap/AVHRR" URL path.

  • The require valid-user command requires user authentication.

  • The AuthType command is set to shibboleth so mod_shib will be called upon to perform the authentication.

For more examples and better understanding see the Apache Configuration section of the Shibboleth wiki.

3.2.3. Nasa’s Earthdata Login - OAuth2 (mod_auth_urs)

Earthdata Login/OAuth2 is a Single Sign On (SSO) authentication flow that utilizes HTTP redirects to guide client applications requesting an authenticated resource to a central Earthdata Login authentication point where they are authenticated, and them redirected back to their requested resource. This way user credentials, however they may be exchanged, are only ever exchanged with a single trusted service.

The Earthdata Login documentation, downloads, application registration, and application approval all require Earthdata Login credentials to access. Obtaining Earthdata Login credentials must be the very first activity for anyone wishing to retrieve, configure and deploy mod_auth_urs.

Each new instance of mod_auth_urs deployed will need to have a set of unique application credentials. These are generated by registering the new instance as an new application with the Earthdata Login system. Because each registered application is linked to a single redirectUrl, each different running instance of mod_auth_urs will need to be registered in order to successfully have the server redirect clients back from their authentication activity.

Prerequisites & Requirements
Building mod_auth_urs

The documentation for mod_auth_urs describes how to build the module from a clone of the git repo, however we found that on CentOS 6 that process had to be modified to include linking with the ssl library. Since it is a fairly simple build, we’ll duplicate it here with the caveat that a newer version of the module might have a different build recipe, so if this doesn’t work, check the official page.

With that said, to build the module for CentOS 6:

  • Make sure you have the httpd-devel and ssl-devel packages are loaded onto your host

sudo yum install httpd-devel openssl-devel;

  • Clone the mod_auth_urs git repo from the ECC system. You need a Earthdata Login for this, but you need a Earthdata Login for several other steps in this configuration process as well.

git clone https://<username>@git.earthdata.nasa.gov/scm/aam/apache-urs-authentication-module.git urs;

  • Build it using the apache extension build tool apxs in the urs directory just made by the git clone command. Note that for CentOS 6 you need to include the ssl library and that you’ll need to be root as it installs libraries into apache.

cd urs;

apxs -i -c -n mod_auth_urs mod_auth_urs.c mod_auth_urs_cfg.c mod_auth_urs_session.c mod_auth_urs_ssl.c mod_auth_urs_http.c mod_auth_urs_json.c mod_auth_urs_crypto.c;

Hyrax_Obtain_Earthdata_Login_Credentials.adoc

Compute the Authorization Code (<URSClientAuthCode>)

Before configuring mod_auth_urs, you must compute the authorization code for your freshly registered application. There are three methods for computing the URS client authorization code:

  1. Shell Script:

    echo -n "<cid>:<pw>" | base64

  2. Perl Script:

    perl -e 'use MIME::Base64; print encode_base64("<cid>:<pw>");'

  3. PHP Script:

    php -r 'echo base64_encode("<cid>:<pw>");'

In the above examples, <cid> is the Client ID (found on your application’s Application Administration page), and <pw> is your application’s password.

Configuration

The instructions for configuring the Apache module mod_auth_urs can be found here:

Notes:

  • The instructions are clear and complete but you have to be a registered Earthdata Login user with permissions to access that page in order to read it.

  • Also note that the apxs tool used to build an apache module is part of the httpd-devel package and won’t be available if you don’t have that package installed.

Once I had it installed all that was needed was to create the file /etc/httpd/conf.d/urs.conf and add the configuration content to the file. The configuration file you’ll find below is annotated and you will need to review and possibly edit the values of the following fields:

  • UrsAuthServer

  • AuthName

And you MUST edit and provide your application credential information in these fields:

  • UrsAuthGroup

  • UrsClientId

  • UrsAuthCode

  • UrsRedirectUrl

And you should review and possibly edit this value to point to an appropriate page on your server for failed authentication:

  • UrsAccessErrorUrl

Example urs.conf file for httpd:
# Load the URS module
LoadModule auth_urs_module    modules/mod_auth_urs.so
#
# Enable Debugging
# LogLevel debug
#
# START - URS module configuration
# The directory where session data will be stored
# NB: This directory MUST be readable and writable
# by the Apache httpd user!!!
#
UrsSessionStorePath /var/tmp/urs/session
#
# The address of the authentication server
# Where you registered your application/server.
#
UrsAuthServer        https://uat.urs.earthdata.nasa.gov
#
# The authentication endpoint
#
UrsAuthPath          /oauth/authorize?app_type=401
#
# The token exchange endpoint
#
UrsTokenPath         /oauth/token
#
#
# END - URS module configuration
 
# Place a URS security constraint on the Hyrax service
<Location /opendap >
 
    # Tells Apache to use URS/OAuth2 authentication in mod_auth_urs
    AuthType UrsOAuth2
 
    # This is a localization field and I think it shows up in
    # browser and GUI client generated authentication dialog boxes.
    AuthName "URS_AuthTest"
 
    # To access, a user must login.
    Require valid-user
 
    ##########################################################
    # UrsAuthGroup     This defines a name for a group of protected resources.
    # All resources with the same group will share authentication state. i.e. If a
    # user attempts to access one resource in a group and authenticates, then
    # the authentication will be valid for all other resources in the group (be
    # aware that the group name is also used as a cookie name).
    UrsAuthGroup       HyraxDataServer
 
    ##########################################################
    # UrsClientId     The ClientID that the URS application registration process
    #  assigned to your application
    UrsClientId        ******
 
    ##########################################################
    # UrsAuthCode     You compute this from the Client ID and application password
    UrsAuthCode        ******
 
    ##########################################################
    # UrsRedirectUrl  This is the redirection URL that was specified when
    # registering the application. This should include the scheme (http/https),
    # the outward facing domain (host)name (or IP address) of your server,
    # the port (if non-standard for the scheme), and path. Note
    # that the path does not need to refer to a real resource, since the module
    # will intercept it and redirect the user before Apache tries to find a
    # matching resource.
    UrsRedirectUrl     https://localhost/opendap/login
 
    ##########################################################
    # UrsAccessErrorUrl  If the users authentication at the URS service fails,
    # this is the page on your server to which they will redirected. If it does not
    # exist they'll get a 404 error instead of the 403.
    UrsAccessErrorUrl  /urs403.html
 
 
    UrsIdleTimeout     600
    UrsActiveTimeout   36000
    UrsIPCheckOctets   2
    UrsUserProfileEnv  uid              URS_USER
    UrsUserProfileEnv  email_address    URS_EMAIL
    UrsUserProfileEnv  first_name       URS_FIRST
    UrsUserProfileEnv  last_name        URS_LAST
 
 
</Location>

Assuming that you have also:

  • Completed configuring AJP proxy for Tomcat

  • Authorized your server (aka Application) to access your Earthdata Login profile.

Simply restart Apache and Hyrax is ready to be accessed with your Earthdata Login credentials.

Standalone Earthdata Login without Apache webserver

If you do not need Apache webserver but would still like to take advantage of NASA’s OAuth2 Earthdata login services, also known as the User Registration System (URS), Hyrax offers a standalone implementation of the Earthdata Login Client that can deployed using only Tomcat or a preferred servlet engine.

If you require a robust security solution that has undergone thorough testing, you should implement mod_auth_urs.

Important
 To take advantage of this feature, you must create an Earthdata Login Application. If you have not yet done this, see the Nasa’s Earthdata Login - OAuth2 (mod_auth_urs) section of this manual.
Enabling Hyrax’s Standalone Earthdata Login Client Implementation

To enable Hyrax’s standalone implementation of the Earthdata login, you need to first modify a few lines of code in web.xml. If you installed Tomcat using the instructions in this manual (via YUM), you can locate web.xml at the following location: /usr/share/tomcat/webapps/opendap/WEB-INF/.

Note
 You should generally avoid editing web.xml, since the file is overwritten whenever you upgrade to a new version of Hyrax; however, in the software’s current iteration, the only way to enable Hyrax’s standalone implementation of the Earthdata login client is by modifying web.xml.

After navigating to /usr/share/tomcat/webapps/opendap/WEB-INF/…​

  1. Open web.xml.

  2. Scroll down until you locate the Identity Provider (IdP) filter and the Policy Enforcement Point (PEP) filter, both of which are commented.

  3. Remove the comments around these filters:

        <!-- Uncomment These two filters to enable access control.
    <filter>
        <filter-name>IdP</filter-name>
        <filter-class>opendap.auth.IdFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>IdP</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>


    <filter>
        <filter-name>PEP</filter-name>
        <filter-class>opendap.auth.PEPFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>PEP</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    -->
Tip
 The IdP filter is responsible for figuring out who users are, and the PEP filter determines what users can or cannot do.
Configuring the Identification Provider

After uncommenting the IdP and PEP filters in web.xml, you must link your server to your Earthdata Login Application by configuring the identification provider.

You must first modify a few lines of code in user-access.xml. If you installed Tomcat via YUM, user-access.xml can be found in one of the following locations:

After accessing the file, scroll down until you locate the IdProvider element:

<IdProvider class="opendap.auth.UrsIdP">
        <authContext>urs</authContext>
        <isDefault />
        <UrsClientId>iPlEjZjMvrdwLUlnbaKxWQ</UrsClientId>
        <UrsClientAuthCode>aVBsRWpaak12cmR3TFVsbmJhS3hXUTpKSEdqa2hmZzY3OA==</UrsClientAuthCode>
        <UrsUrl>https://uat.urs.earthdata.nasa.gov</UrsUrl>
</IdProvider>

Configure your identification provider by updating the following child elements:

  • authContex: Determines whether you are using the production (urs) or test (uat) service. Only NASA-authorized applications can use the production service.

  • UrsClientID: The Client ID can be located on your application’s Application Administration page.

  • UrsClientAuthCode: You must generate the authorization code using your Earthdata Login Application’s Client ID and password. See the following section for more information.

  • UrsUrl: Depending on the authContext, should be one of the following:

    • https://uat.urs.earthdata.nasa.gov

    • https://urs.earthdata.nasa.gov

Compute <URSClientAuthCode>

You can compute the URS client authorization code with one of the following methods:

  1. Shell Script:

    echo -n "<cid>:<pw>" | base64

  2. Perl Script:

    perl -e 'use MIME::Base64; print encode_base64("<cid>:<pw>");'

  3. PHP Script:

    php -r 'echo base64_encode("<cid>:<pw>");'

In the above examples, <cid> is the Client ID (found on your application’s Application Administration page), and <pw> is your application’s password.

3.2.4. Logging Earthdata Login information

It is possible to get the Apache module to pull user profile information into the request environment using the UrsUserProfileEnv configuration directive:

UrsUserProfileEnv email_address URS_EMAIL
UrsUserProfileEnv user_type URS_TYPE

This can be added to a custom log format by including:

LogFormat ... %{URS_EMAIL}e ... \"%{URS_TYPE}e\" ...'''

Where we show the URS_TYPE environment variable in double quotes because their values often contain spaces. Thanks to Peter Smith for this information.

See the full Apache LogFormat documentation for more information.

3.3. Common Problems

3.3.1. Clients keep getting Internal Server Error

Problem

Everything seems to work fine but when the browser client is redirected back to the originally requested resource it receives an Internal Server Error from Apache httpd. In /var/log/httpd/ssl_error.log you see this type of thing:

[Sun Mar 22 20:05:47 2015] [notice] [client 71.56.150.130] UrsAuth: Redirecting to URS for authentication, referer: https://52.1.74.222/opendap/data/contents.html
[Sun Mar 22 20:05:47 2015] [error] [client 71.56.150.130] UrsAuth: Redirection URL: https://uat.urs.earthdata.nasa.gov/oauth/authorize?app_type=401&client_id=tNxluRHmczrTN1iSjXCMiA&response_type=code&redirect_uri=https%3A%2F%2F52.1.74.222%2FOPeNDAP%2Flogin&state=aHR0cHM6Ly81Mi4xLjc0LjIyMi9vcGVuZGFwL2RhdGEvaGRmNC9jb250ZW50cy5odG1s, referer: https://52.1.74.222/opendap/data/contents.html
[Sun Mar 22 20:05:53 2015] [error] [client 71.56.150.130] UrsAuth: Failed to create new cookie, referer: https://uat.urs.earthdata.nasa.gov/oauth/authorize?app_type=401&client_id=tNxluRHmczrTN1iSjXCMiA&response_type=code&redirect_uri=https%3A%2F%2F52.1.74.222%2FOPeNDAP%2Flogin&state=aHR0cHM6Ly81Mi4xLjc0LjIyMi9vcGVuZGFwL2RhdGEvaGRmNC9jb250ZW50cy5odG1s

This is often caused by the Apache httpd user not having read/write permission on the directory specified by UrsSessionStorePath in the httpd configuration:

UrsSessionStorePath /var/tmp/urs/session
Solution

Check and repair the permissions of the directory specified by UrsSessionStorePath as needed.

4. Tomcat Authentication Services Configuration

Tomcat provides a number of authentication Realm implementations including the JNDIRealm which provides LDAP SP services for Tomcat. There is currently no Shibboleth realm implementation for Tomcat, and it’s an open question for the author if there could be one for Shibboleth or OAuth2 given the way that these protocols utilize 302 redirects away from the origin service.

4.1. LDAP

The instructions for configuring Tomcat to perform LDAP authentication are located here. It is clearly a benefit if you understand a fair bit about LDAP before you undertake this.

Here is an example of how to configure Tomcat to use LDAP authentication.

In this example we configure a Tomcat JNDI realm to use the public LDAP service provided by ForumSys.

In the server.xml file we added a JNDI Realm element:

<Realm
    className="org.apache.catalina.realm.JNDIRealm"
    connectionURL="ldap://ldap.forumsys.com:389"
    connectionName="cn=read-only-admin,dc=example,dc=com"
    connectionPassword="password"
    userPattern="uid={0},dc=example,dc=com"
    roleBase="dc=example,dc=com"
    roleName="ou"
    roleSearch="(uniqueMember={0})"
/>

Configured to work with the Forum Systems test LDAP server.

Then in the opendap web application we added the following security constraint to the WEB-INF/web.xml file:

<security-constraint>
    <web-resource-collection>
         <web-resource-name>Hyrax Server</web-resource-name>
         <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
         <role-name>user</role-name>
    </auth-constraint>
 
    <user-data-constraint>
         <!-- this ensures that all efforts to access the admin interface nd resources must use HTTPS -->
         <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
</security-constraint>
 No changes were made to the _$CATALINA_HOME/conf/tomcat_users.xml_
file.

4.2. Shibboleth

There is no actual Shibboleth integration with Tomcat beyond what is provided by running the Apache httpd module mod_shib and connecting Tomcat to httpd using AJP as described in the Apache/Shibboleth section on this page.

4.3. Earthdata Login OAuth2

There is no actual Earthdata Login integration with Tomcat beyond what is provided by running the Apache httpd module mod_auth_urs and connecting Tomcat to httpd using AJP as described in the Apache/URS section on this page.