Java SAML Consumer VAM Deployment Guide SA… · Java SAML Consumer is unique in its ability to a...

Value-Added Module (VAM)

Java SAML Consumer VAM Deployment Guide


SecureAuth www.secureauth.com 2

Copyright information

©2020. SecureAuth® is a registered trademark of SecureAuth Corporation. SecureAuth’s Identity Platform software, appliances, and other products and solutions are copyrighted products of SecureAuth Corporation.

Document revision history

Version Date Notes 1.0 July 2016 First release 2.0 January 2018 Second release 2.1 February 2020 Point release to add explanatory information and reformat doc.

For information on support for this module, contact your SecureAuth support or sales representative:

Email: [email protected] [email protected]

Phone: +1-949-777-6959 +1-866- 859-1526

Website: https://www.secureauth.com/support https://www.secureauth.com/contact

http://www.secureauth.com/

mailto:[email protected]

mailto:[email protected]

https://www.secureauth.com/Contact-Us.aspx

https://www.secureauth.com/support

https://www.secureauth.com/contact



Contents Introduction ............................................................................................................................................................. 4

Versions supported .................................................................................................................................................. 4

Deployment environment ........................................................................................................................................ 5

Deployment steps .................................................................................................................................................... 5

Testing SAML Handler Admin Web application ........................................................................................................ 7

Testing Tomcat Authenticator and SAML Handler ................................................................................................. 11

Upgrade information.......................................................................................................................................... 12




Introduction The Java SAML Consumer VAM enables customer-owned and custom-built applications running on a Tomcat server to be converted quickly and easily to a form that supports SAML certificate validation, even if the apps currently do not support SAML or another WS-Federated-compliant security token architecture. Java SAML Consumer acts as an application broker, enabling and disabling apps at the server level by using URL path parameters.

This provides customers with SecureAuth single sign-on (SSO) access to applications that do not currently support such access and provides increased security and better user experience. Java SAML Consumer is a collaboration tool enabling non-employees, such as external partners, access to internal applications.

Java SAML Consumer is unique in its ability to activate applications at the server level, avoiding the Spring Security authentication framework or standard API calls. By integrating at the server level, group information is passed via SAML from the identity provider to the Java SAML Consumer, which efficiently processes authentication data for SecureAuth IdPs. This allows for a standardized authentication process from external identity providers to internal applications and enables customers to standardize on a specific authentication protocol.

This document shows administrators how to use the Java SAML Consumer to do the following:

Enable apps at the server level, not the application level Integrate at the valve level, enabling group information to be passed via SAML Allow customers to standardize on a single authentication protocol for all applications Java SAML Consumer features include the following:

Contains a full administrator user interface Support identity provider metadata Supports multiple identity providers Supports SecureAuth realm structure Supports load balancer and reverse proxy with force SSL functions Supports RelayState and creation of JSESSION Supports service provider-initiated signing of a SAML request Supports different federation URLs based on different identity provider selections

Versions supported SecureAuth IdP version 9.2 and later; SecureAuth® Identity Platform version 19.07 and later Apache Tomcat version 7.0 and later Java version 6 or 7




Deployment environment These instructions detail the method used for deploying the Java version of the SAML consumer VAM using the Java-compliant open source web environment Tomcat. Also discussed is the configuration required to deploy the following three components to a Tomcat server:

SecureAuth Authenticator (Tomcat valve – JAR file) Use SecureAuth Authenticator 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 (Tomcat plugin – JAR file) SAML Handler passes SAML requests to a SecureAuth IdP appliance for authentication, receives responses from the SecureAuth IdP, and sends the responses to the SecureAuth Authenticator.

SAML Admin (Web application – WAR file) SAML Admin is a web application for configuring IdPs, application-IdP mapping, and the Tomcat Valve.

The instructions assume Apache Tomcat server is installed with the default settings and is running at http://localhost:8080/

The list of files that must be deployed are included in the following table.

File to deploy Deploy to 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 steps 1. Stop the Tomcat server.

2. Open the Tomcat conf directory and copy valve.properties to the conf directory.

3. Open the Tomcat libs directory.

4. Copy sa-tomcat-authenticator.jar and sa-samlhandler.jar to the libs directory. Double-click each JAR file and extract the compressed files in both.


5. Open the Tomcat webapps directory.

6. Copy admin-samlhandler.war to the webapps directory then open the WAR file and configure the Tomcat Valve settings as follows:

a. Open the Tomcat conf directory and open server.xml. b. In server.xml, find the Host section, located below the SingleSignOn valve and add the following lines:

<Valve className="org.apache.catalina.authenticator.SingleSignOn" /> <Valve className="org.apache.catalina.authenticator.SecureauthAuthenticator" valvePropertyLoc="conf/valve.properties" />

The server.xml file should look like the following example:

<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">  <Valve className="org.apache.catalina.authenticator.SingleSignOn" /> <Valve className="org.apache.catalina.authenticator.SecureauthAuthenticator" valvePropertyLoc="conf/valve.properties" />  <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." suffix=".txt" pattern="%h %l %u %t "%r" %s %b" /> </Host>

c. Open the Tomcat conf directory and open valve.properties. d. Make necessary adjustments according to your application requirements.

For example, change the generic /examples/docs value highlighted in yellow in the following example with the name of your own document folder. Also indicate if SSO is enabled or disabled.

# Set protected applications # Use semicolon(;) separated list of protected apps (Use * if you want to 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 # 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, each protected application in your Tomcat server can have a different IdP, based on the app-IdP mapping, for authentication. If you set single.sign.on.enabled=true, you only need to authenticate once for all protected applications.



Testing SAML Handler Admin Web application 1. Start Tomcat server.

2. Open the Tomcat webapps directory.

3. Verify that the deployed admin-samlhandler.war has created an admin-samlhandler folder in the webapps directory. The folder should contain the following two pre-configured property files:

• samlhandler is an IdP configuration file. • app-idp-mapping is an application-IdP mapping file. The following image shows the two preconfigured property files, highlighted in yellow, in the context of the Tomcat directory.

4. Open the local SAML admin site in a web browser: http://localhost:8080/admin-samlhandler/

The SAML Admin Configuration screen is displayed.




The preconfigured sample IdPs are displayed in the image above. Each IdP has a separate tab and fields, indicating the IdP name, the Identity Service URL, the name of the issuer, the SAML metadata file (if one has been uploaded), and the certificate.

5. Modify, delete, or add new IdPs.

Complete the following steps to add a new IdP:

a. On the SAML Admin Configuration screen, click the Add New IdP button. b. A new IdP page is displayed with all the fields blank. c. Enter a value for each field. d. If a SAML metadata file is required, click Upload and navigate to the location of the meta- file then click

OK. e. Edit the certificate in the Certificate field, if necessary. f. Check the available boxes as required. Set as Default IdP Check 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.

g. When you’ve entered all the required information, click the Save button.




6. With the selected IdP page displayed, click the Application – IdP Mapping link at the top of the page.

The Application- IdP Mapping screen is displayed.

7. Update, delete, or add new applications as required for this configuration.

Complete the following steps to add a new IdP:

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, click the dropdown list to select the IdP this application is linked to.




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.

8. Click the Tomcat Valve Configuration link.

The Tomcat Valve Configuration screen is displayed.

9. Enter the following information in the appropriate fields, as needed.

Protected Applications Enter each protected application separated by a semicolon. The application name is specified in the Application Name column in step 7 on page 9.

All Applications Check this box to protect all applications defined in step 7 on page 9. Single Sign-On Check this box to enable SSO between the protected applications.

10. Save your changes.




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. Sign in using the Tomcat Valve IdP Authentication screen.

After successful authentication, you are redirected to the protected application shown below, which references the Application URL you defined in the Application-IdP Mapping screen.

2. Open another protected web application, for example: http://localhost:8080/docs/

The Tomcat authenticator redirects you to another IdP, based on the application-IdP mapping, for authentication. Sign in using the authentication screen.




3. After a successful authentication, you are redirected to the selected application.

Upgrade information Before upgrading SecureAuth Identity Platform appliances, open a Support ticket. When your site is ready to upgrade, get started by creating a support ticket and selecting I have a question or issue regarding SecureAuth Value-Added Modules (VAMs) from the "Submit a request" dropdown. A SecureAuth Tailoring engineer will contact you and evaluate and ensure that the VAM can be upgraded.


https://support.secureauth.com/hc/en-us/requests/new

Java SAML Consumer VAM Deployment Guide SA… · Java SAML Consumer is unique in its ability to a...

Documents

Transcript of Java SAML Consumer VAM Deployment Guide SA… · Java SAML Consumer is unique in its ability to a...