VAM Java SAML Consumer Value- Added Module (VAM) Deployment Guide
Copyright Information 2018. SecureAuth is a registered trademark of SecureAuth Corporation. SecureAuth s IdP software, appliances, and other products and solutions are copyrighted products of SecureAuth Corporation. For information on support for this module, contact your SecureAuth support or sales representative: Email: support@secureauth.com inside-sales@secureauth.com Phone: +1.949.777.6959 or +1-866- 859-1526 Website: https://www.secureauth.com/support https://www.secureauth.com/contact 2
Table of Contents Overview... 4 Deployment Environment... 5 Deployment Steps... 6 Testing SAML Handler Admin Web Application... 8 Testing Tomcat Authenticator and SAML Handler... 12 Update Warning... 14 3
Overview This document details the method used for deploying the Java version of the SAML consumer valueadded module (VAM) 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. 4
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) 5
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 doubleclick 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 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" direc- tory="logs" prefix="localhost_access_log." suffix=".txt" pattern="%h %l %u %t "%r" %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 6
# 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. 7
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/adminsamlhandler/ 8
You should see the SAML Admin Configuration screen like Figure 2: Click this link as described in Step 5 on page 10. 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 meta- file 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 Validate SAML Assertion 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. 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. 9
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 9) 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. 10
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 10. All Applications Check this box if all applications defined in Step 6 on page 10 should be protected. Single Sign-On Check this box to enable SSO between the protected applications. 9. When you are finished, click Save. 11
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 12
This application references the Application URL defined for it in the Application-IdP Mapping screen (see Step 6 on page 10). 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 13
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 tailoringfrontline@secureauth.com before making any updates. 14