Hyrax - User Identification (Authentication): Difference between revisions
Line 239: | Line 239: | ||
'''NB: ''Sections [[#Configure_Apache_to_Proxy_Tomcat | Configure Apache To Proxy Tomcat]] and [[#Configure_Tomcat_.28Hyrax.29 | Configure Tomcat (Hyrax) ]] must be completed prior to completion of this section''''' | '''NB: ''Sections [[#Configure_Apache_to_Proxy_Tomcat | Configure Apache To Proxy Tomcat]] and [[#Configure_Tomcat_.28Hyrax.29 | Configure Tomcat (Hyrax) ]] must be completed prior to completion of this section''''' | ||
'''NB: ''You will need to know the public facing domain name or IP address of your server to complete this section.''''' | |||
URS/OAuth2 is a redirect authentication flow where client applications requesting an authenticated resource are redirected to a central URS authentication point, authenticated, and redirected back to their requested resource. This way user credentials, however they may be exchanged, are only ever exchanged with a single trusted service. | |||
In order to get a new instance of ''mod_auth_urs'' running you will need application credentials for the instance from the URS 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. | |||
===== Obtaining URS Application Credentials ===== | |||
'''Assumption: You are registered URS user and you can find your URS profile page.''' | |||
; Hint | |||
: [https://uat.urs.earthdata.nasa.gov/profile Test URS system] | |||
: [https://urs.earthdata.nasa.gov/profile Main URS System] | |||
* With your browser, goto your URS profile page. | |||
* Click the '''My Applications'' tab. | |||
On the '''My Applications''' page: | |||
* Click the ''Create A New Application'' button. | |||
* Fill out the form and save your the information you enter into the form for later. | |||
* Once you have registered the application you'll be able to see it in you profile's ''My Applications'' tab. Its status will show pending a while: | |||
** Make note of your password and the ''Client ID'' generated by the URS system. | |||
IMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGE | |||
IMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGE | |||
IMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGE | |||
IMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGE | |||
Once it passes through the approval process in URS land its status will be changed to '''Active''' and your instance of ''mod_auth_urs'' will be permitted to interact with the URS system. | |||
The last thing to do before configuring ''mod_auth_urs'' is to compute the authorization code for your freshly registered application. | |||
Use a simple perl script: | |||
<source lang="perl"> | |||
perl -e 'use MIME::Base64; print encode_base64("<uid>:<pw>");' | |||
</source> | |||
Or php script: | |||
<source lang="php"> | |||
php -r 'echo base64_encode("<uid>:<pw>");' | |||
</source> | |||
Or shell script: | |||
<source lang="bash"> | |||
echo -n "<uid>:<pw>" | base64 | |||
</source> | |||
Where ''<uid>'' is the ''Client ID'' for your application that was generated by the URS system and ''<pw>'' is the password associated with your freshly registered application. | |||
The resulting string of base64 encoded stuff is your application's URS authorization code, aka UrsAuthCode in ''mod_auth_urs''. | |||
===== Configuration ===== | |||
The instructions for configuring the Apache module '''mod_auth_urs''' can be found here: | The instructions for configuring the Apache module '''mod_auth_urs''' can be found here: |
Revision as of 14:33, 6 December 2014
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 httpd Authentication Services Configuration
There are many authentication methods available for use with our friend httpd. Each of them may have 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 the examine LDAP, Shibboleth, and NASA URS IdP configurations for Apache httpd.
- NB
- 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.
First: 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.
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
This will expose the web application "opendap" (aka Hyrax) through Apache. Make sure that the AJP URLs both point to your deployment of Hyrax.
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.
- 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 for Tomcat. This means that web applications (like Hyrax) that 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.)
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:
<Location /opendap>
AuthType YourFavoriteAuthTypeHere
require valid-user
</Location>
Where the require valid-user
attribute makes the requirement that all accessors be authenticated and YourFavoriteAuthTypeHere would be something like Basic, UrsOAuth2 or shibboteth.
Complete examples for LDAP, URS/OAuth2, and Shibboleth IdPs are presented in the following sections.
LDAP (mod_ldap, mod_authnz_ldap)
NB: Sections Configure Apache To Proxy Tomcat and Configure Tomcat (Hyrax) must be completed 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
- mathematicians
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
Shibboleth (mod_shib)
NB: Sections Configure Apache To Proxy Tomcat and Configure Tomcat (Hyrax) must be completed 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 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:
- https://wiki.shibboleth.net/confluence/display/SHIB2/Installation
- Install a Native Service Provider on your target system.
- In the initial testing section for Linux they suggest accessing the Status page https://localhost/Shibboleth.sso/Status, but you may have to use the loopback address to be able to do so: https://127.0.0.1/Shibboleth.sso/Status
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.
- Do not be confused by the section Making URLs Used by mod_shib Get Properly Routed. While you must add this Location directive to "reveal" the shibboleth module to the world don't think the URL https://yourhost/Shibboleth.sso is a valid access point to the module. That URL may always return a Shibboleth error page even if mod_shib and shibd are configured and working correctly.
- Read and understand the section Enabling the Module for Authentication
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 toshibboleth
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.
URS OAuth2 (mod_auth_urs)
NB: Sections Configure Apache To Proxy Tomcat and Configure Tomcat (Hyrax) must be completed prior to completion of this section
NB: You will need to know the public facing domain name or IP address of your server to complete this section.
URS/OAuth2 is a redirect authentication flow where client applications requesting an authenticated resource are redirected to a central URS authentication point, authenticated, and redirected back to their requested resource. This way user credentials, however they may be exchanged, are only ever exchanged with a single trusted service.
In order to get a new instance of mod_auth_urs running you will need application credentials for the instance from the URS 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.
Obtaining URS Application Credentials
Assumption: You are registered URS user and you can find your URS profile page.
- With your browser, goto your URS profile page.
- Click the 'My Applications tab.
On the My Applications page:
- Click the Create A New Application button.
- Fill out the form and save your the information you enter into the form for later.
- Once you have registered the application you'll be able to see it in you profile's My Applications tab. Its status will show pending a while:
- Make note of your password and the Client ID generated by the URS system.
IMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGE
IMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGE
IMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGE
IMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGEIMAGE
Once it passes through the approval process in URS land its status will be changed to Active and your instance of mod_auth_urs will be permitted to interact with the URS system.
The last thing to do before configuring mod_auth_urs is to compute the authorization code for your freshly registered application.
Use a simple perl script:
perl -e 'use MIME::Base64; print encode_base64("<uid>:<pw>");'
Or php script:
php -r 'echo base64_encode("<uid>:<pw>");'
Or shell script:
echo -n "<uid>:<pw>" | base64
Where <uid> is the Client ID for your application that was generated by the URS system and <pw> is the password associated with your freshly registered application. The resulting string of base64 encoded stuff is your application's URS authorization code, aka UrsAuthCode in mod_auth_urs.
Configuration
The instructions for configuring the Apache module mod_auth_urs can be found here:
https://wiki.earthdata.nasa.gov/display/URSFOUR/Apache+URS+Authentication+Module
Notes:
- The instructions are clear and complete but you have to be a registered URS 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 need was to create the file /etc/httpd/conf.d/urs.conf and add the following content:
# 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
#
UrsSessionStorePath /var/tmp/urs/session
# The address of the authentication server
#
UrsAuthServer https://uat.urs.earthdata.nasa.gov
# The authentication endpoint
#
UrsAuthPath /oauth/authorize
# The token exchange endpoint
#
UrsTokenPath /oauth/token
#
#
# END - URS module configuration
# Place a URS security constraint on the Hyrax service
<Location /opendap >
AuthType UrsOAuth2 # Tells Apache to use URS/OAuth2 authentication in mod_auth_urs
AuthName "URS_AuthTest" # This is a localization field and I think it shows up in
# browser and GUI client generated authentication dialog boxes.
Require valid-user # To access, a user must login.
############################################
UrsAuthGroup HyraxDataServer
UrsClientId ****** # Get this by registering your server (aka application) with URS
UrsAuthCode ****** # Compute this from UrsClientId and password
UrsRedirectUrl https://54.172.97.47/opendap/login # This MUST point back to your server. The actual resource need not exist as the mod_auth_urs module will handle the request.
############################################
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
UrsAccessErrorUrl /urs403.html
</Location>
Assuming that the AJP proxy for Tomcat is already done simply restart Tomcat and access Hyrax with your URS credentials.
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.
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.
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.
URS OAuth2
There is no actual URS 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.