Java SAML Consumer
Deployment Guide
Copyright Information
SecureAuth© is a copyright of SecureAuth Corporation. SecureAuth’s IdP software, appliances, and other products and solutions, are copyrighted
products of SecureAuth Corporation.
Contents
Overview
1
Deployment Environment
2
Deployment Steps
3
Testing SAML Handler Admin Web Application
5
Testing Tomcat Authenticator and SAML Handler
9
Update Warning
11
Overview
This document details the method used for deploying the Java version of the SAML consumer
using the Java-compliant open source web environment Tomcat.
The SAML Consumer Java version consists of three components:
+ SecureAuth Authenticator (Tomcat valve – JAR file)
+ SAML Handler (Tomcat plugin – JAR file)
+ SAML Admin (Web application – WAR file)
SecureAuth Authenticator can be used to authenticate users accessing protected web applications deployed in a Tomcat instance using a Tomcat valve. If the user is not authenticated, it
sends a request to the SAML Handler to authenticate the user. The Authenticator also manages
Single Sign On (SSO) between protected web applications.
SAML Handler passes SAML requests to an IdP (SA appliance) for authentication, receives
responses from the IdP, and sends these responses to the SecureAuth Authenticator.
SAML Admin is a web application for configuring IdPs, application-IdP mapping, and the Tomcat Valve.
The remainder of this document describes the configuration required to deploy the SecureAuth Authenticator, SAML Handler, and SAML Admin web application to a Tomcat server.
Overview
1
Java SAML Consumer Deployment Guide
Deployment Environment
This document assumes Apache Tomcat server has been installed with the default settings and
is running at http://localhost:8080/.
The list of files that must be deployed include:
TABLE 1. Deployment
Files
File
Deployed location
Description
sa-tomcat-authenticator.jar
[CATALINA_HOME]/libs
Tomcat Valve that passes requests to
SamlHandler for protected applications
sa-samlhandler.jar
[CATALINA_HOME]/libs
Sends SAML requests to an IdP, retrieves
responses from the IdP, and authenticates
the user
admin-samlhandler.war
[CATALINA_HOME]/webapps
SAML admin web application for configuring IdPs and application-IdP mapping
valve.properties
[CATALINA_HOME]/conf
Tomcat valve configuration file
server.xml
[CATALINA_HOME]/conf
Sample of Tomcat’s server configuration
file (updated with Valve)
Deployment Environment
2
Java SAML Consumer Deployment Guide
Deployment Steps
1. Stop Tomcat server, if it is running.
2. Copy valve.properties to Tomcat’s conf directory.
3. Copy sa-tomcat-authenticator.jar and sa-samlhandler.jar to Tomcat’s libs directory then
double-click these two JAR files to extract all the compressed files from both.
4. Copy admin-samlhandler.war to Tomcat’s webapps directory then double-click this WAR file
to extract all the compressed files from it.
5. Configure the Tomcat Valve settings in this manner:
a. From the Tomcat’s conf directory, double-click to open server.xml.
b. Add the following under the Host section (below SingleSignOn valve) of the XML file:
<Valve className="org.apache.catalina.authenticator.SingleSignOn" />
<Valve className="org.apache.catalina.authenticator.SecureauthAuthenticator"
valvePropertyLoc="conf/valve.properties" />
For example, the server.xml file should look like this:
<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="true">
<!-- SingleSignOn valve, share authentication between web applications
Documentation at: /docs/config/valve.html -->
<Valve className="org.apache.catalina.authenticator.SingleSignOn" />
<Valve className="org.apache.catalina.authenticator.SecureauthAuthenticator"
valvePropertyLoc="conf/valve.properties" />
<!-- Access log processes all example.
Documentation at: /docs/config/valve.html
Note: The pattern used is equivalent to using pattern="common" -->
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
prefix="localhost_access_log." suffix=".txt"
pattern="%h %l %u %t &quot;%r&quot; %s %b" />
</Host>
c. Open valve.properties in Tomcat’s conf directory.
d. Make necessary adjustments according to your application requirements.
For example, in place of the generic /examples/docs value for protected.context in the
following example, specify the name of your own doc name (highlighted in yellow). Also
indicate whether SSO is enabled or disabled.
# Set protected applications
# Use semicolon(;) separated list of protected apps (Use * if you want protect all
apps)
# Example: protected.contexts=/app1;/app2;/app3
protected.contexts=/examples/docs
# Specify whether the SAMLHandler is placed in the same Tomcat instance which is
protected by Valve
samlhandler.in.same.instance=false
Deployment Steps
3
Java SAML Consumer Deployment Guide
# Set this property to true if you want SingleSignOn between the protected apps
single.sign.on.enabled=false
NOTE: If you set single.sign.on.enabled=false, it specifies that each protected
application in your tomcat server can have a different IdP (based on app-IdP mapping) for authentication.
If you set this argument to single.sign.on.enabled=true, it indicates that you only
need to authenticate once for all protect applications.
Deployment Steps
4
Java SAML Consumer Deployment Guide
Testing SAML Handler Admin Web
Application
1. Start Tomcat server.
2. Verify that the deployed admin-samlhandler.war has created an admin-samlhandler folder
under Tomcat’s webapps directory with two pre-configured property files as shown in the
example in Figure 1:
•
samlhandler -- an IdP configuration file
•
app-idp-mapping – an Application-IdP mapping file
FIGURE 1.
Application - IdP Mapping File Example
3. Using a browser, open the local SAML admin site:
http://localhost:8080/admin-samlhandler/
Testing SAML Handler Admin Web Application
5
Java SAML Consumer Deployment Guide
You should see the SAML Admin Configuration screen like Figure 2:
Click this link as described
in Step 5 on page 7.
FIGURE 2.
SAML Admin Configuration Screen Example
The preconfigured sample IdPs are displayed. Each IdP has a separate tab and fields, indicating the IdP name, the Identity Service URL, the name of the issuer, the SAML meta-data
file (if one has been uploaded) and the certificate.
4. Modify, delete, or add new IdPs as required.
To add a new IdP:
a. From the SAML Admin Configuration screen, click the Add New IdP button.
A new IdP page appears with all the fields blank.
b. Enter a value for each field.
c. If a SAML metadata file is required, click Upload and navigate to the location of the metafile then click OK.
d. If required, edit the certificate that appears in the Certificate field. Otherwise, leave it as it
was populated.
e. Check the available boxes as required.
Set as Default IdP
Check to indicate the selected IdP is the default IdP.
Validate SAML
Message
Check to indicate that this IdP’s SAML message is automatically
validated. If you check this box, a certificate field like the one shown in
the previous example appears.
Validate SAML
Assertion
Check to indicate that this IdP’s SAML assertion is automatically
validated. If you check this box, a new certificate field appears that is
used for the assertion of the SAML request.
Testing SAML Handler Admin Web Application
6
Java SAML Consumer Deployment Guide
f. When you’ve entered all the required information, click the Save button.
5. With the selected IdP page displayed, click on the Application – IdP Mapping link at the top
of the page (see the call-out in Figure 2 on page 6) to open the Application-IdP Mapping
screen as shown in Figure 3.
FIGURE 3.
Application-IdP Mapping Link Example Screen
6. Update, delete, or add new applications as required for this configuration.
To add a new application:
a. Click the Add New Application button.
A new row in the application matrix appears.
b. At the Application Name column, enter a name for the selected application.
c. At the Application URL column, enter the URL where this selected application resides.
d. At the IdP column, select from the drop-down list the IdP to which this application is
linked.
e. Click the Update button.
The specified application is linked to the designated IdP. Any subsequent requests for the
opening of the application will be handled by the designated IdP.
Testing SAML Handler Admin Web Application
7
Java SAML Consumer Deployment Guide
7. Click on the Tomcat Valve Configuration link and the Tomcat Valve Configuration screen like
the example in Figure 4.
FIGURE 4.
Tomcat Valve Configuration Screen
8. Make changes to this screen as required by entering information in the following fields:
Protected Applications
Enter each protected application separated by a semicolon.
The name of the application is specified in the Application
Name column in Step 6 on page 7.
All Applications
Check this box if all applications defined in Step 6 on page 7
should be protected.
Single Sign-On
Check this box to enable SSO between the protected applications.
9. When you are finished, click Save.
Testing SAML Handler Admin Web Application
8
Java SAML Consumer Deployment Guide
Testing Tomcat Authenticator and
SAML Handler
To test the Tomcat Authenticator and the SAML Handler, follow these steps.
1. Open a protected web application, for example: http://localhost:8080/examples/.
The Tomcat authenticator redirects you to the IdP for authentication as shown in Figure 5.
FIGURE 5.
Tomcat Valve IdP Authentication Screen
After successful authentication, you are redirected to the protected application as shown in
Figure 6.
FIGURE 6.
Protected Application Example
Testing Tomcat Authenticator and SAML Handler
9
Java SAML Consumer Deployment Guide
This application references the Application URL defined for it in the Application-IdP Mapping screen (see Step 6 on page 7).
2. Open another protected web application, for example: http://localhost:8080/docs/.
The Tomcat authenticator redirects you to another IdP (based on application-IdP mapping)
for authentication as shown in Figure 7.
FIGURE 7.
IdP Authentication Example
3. Similarly, after a successful authentication, you are redirected to the selected application as
shown in Figure 8:
FIGURE 8.
Application Redirection Example
Testing Tomcat Authenticator and SAML Handler
10
Java SAML Consumer Deployment Guide
Update Warning
The process of updating SecureAuth software to a newer version may cause these SecureAuth
adapter changes to become invalid and the adapter itself to stop working. Until this feature is
included in the main product, these customizations will need to be merged into any future
updates.
Please contact [email protected] before making any updates.
Update Warning
11