Penn Computing

Penn Computing

Computing Menu Computing A-Z
Computing Home Information Systems & Computing Penn
ISC Networking & Telecommunications

Penn WebLogin
Help
Application Development
WebLogin Management Console
Screen Guidance
Documentation
Sign up for Announcements
Quick Links
Initiate a session
Terminate a session
Related topics
WebLogin vs Shibboleth

User Guide
About WebLogin
WebLogin screens
Logout posters
Verify WebLogin Page

Two-Step Verification
Two-Step Home
FAQ
Authenticator Apps
Video Guides
Information for LSPs

Tomcat Installation

Contents

Introduction

This documentation will walk you through setting up CoSign with the Windows Tomcat server.

Be Aware of Actual Tomcat Directory Name
For the remainder of this file we will refer to the tomcat directory as:

C:\Program Files\apache-tomcat\

While the actual directory may be something like:

C:\Program Files\apache-tomcat-7.0.27\

Make Sure You Have Administrator Privileges
Several steps in this documentation will require you to edit/create files and directories. You can do this via the command prompt or through the windows user interface. In either case, you will need administrative privileges to make many of these changes.

Prerequisites

  1. Download a Java release for Windows if you do not already have one. You can check your java installations by looking in C:\Program Files\ and C:\Program Files (x86)\. Look for a Java folder to see if you already have any versions of Java installed. Java can be obtained from http://www.java.com.
  2. Download the latest release of tomcat from http://tomcat.apache.org/. Ensure that the tomcat release is appropriate for your operating system and version of java which you are installing (32-bit versus 64-bit). If your java and tomcat versions are not consistent the server will not work.
  3. Download the latest JavaCosign filter from http://weblogin.org/download.shtml
  4. Download the configuration bundle from WMC (http://www.upenn.edu/computing/weblogin/). If you have not registered your service with WMC you can do so now, this is required for your web application. You will only need the certificate files from the bundle.
  5. Download the supporting jar files for cosign from http://cosign.cvs.sourceforge.net/viewvc/cosign/javacosign/libs/
    You can also obtain the supporting jar files from the Apache Commons:
    Apache Commons Pool
    Apache Commons Collections
    Apache Commons Logging
  6. All installations will be required to make TCP connections to weblogin.pennkey.upenn.edu port 6663.

Install The Necessary Applications

  1. Install the java release which has been downloaded.
  2. Extract the tomcat zip file to the C:\Program Files\ directory.
  3. Place the JavaCosign.jar file into the lib directory of the apache-tomcat folder (C:\Program Files\apache-tomcat\lib).
  4. From the WMC bundle copy the file <Your Service Name>.jks to the C:\Program Files\apache-tomcat\conf\ directory.
  5. Place the supporting jar files (commons-pool-1.4.jar, commons-logging-1.1.1.jar, and commons-collections-3.2.1.jar) into the C:\Program Files\apache-tomcat\lib\ directory.

Configure SSL for Tomcat

You can review the full SSL directions for Tomcat at http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html. Please reference those directions for background and any specific requirements which you may have for SSL. Abbreviated instructions for Tomcat version 7 are below:

  1. Navigate to and open the file C:\Program Files\apache-tomcat\conf\server.xml
  2. Locate the commented field which begins with: <!-- Define a SSL HTTP/1.1 Connector on port 8443
  3. Do not uncomment this field, instead add the following directly below where the commented field ends (below both the commented field and the addition are displayed. You should only need to add the second part):
Check Your Site Specific Configuration
When doing a copy and paste from this documentation be aware there are items such as YOUR_WMC_SERVICE_NAME and PASSWORD_SET_IN_WMC that should be replaced with your site specific configuration. This applies below as well as other areas where templates are provided for you in this documentation. Note: The port configured below is 443 - this may be changed based on your desired configuration.
    <!--Define a SSL HTTP/1.1 Connector on port 8443
         This connector uses the JSSE configuration, when using APR, the
         connector should be using the OpenSSL style configuration
         described in the APR documentation -->


    <Connector protocol="org.apache.coyote.http11.Http11Protocol"
           port="443" maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="\conf\YOUR_WMC_SERVICE_NAME.jks" keystorePass="PASSWORD_SET_IN_WMC"
           clientAuth="false" sslProtocol="TLS"/>

Configure CoSign for Tomcat

Create cosignConfig.xml

  1. Create a file named cosignConfig.xml in the directory C:\Program Files\apache-tomcat\conf\.
  2. Paste the following content into the cosignConfig.xml file (*Note: Update the PORT, SERVICE NAME, and SERVER REGULAR EXPRESSION from this content to match your application. Also, add protected nodes as required):
<?xml version="1.0" encoding="UTF-8"?>
<CosignConfig>
    <!-- where to find the certificates -->
    <KeyStorePath>conf/YOUR_WMC_SERVICE_NAME.jks</KeyStorePath>
    <KeyStorePassword>PASSWORD_SET_IN_WMC</KeyStorePassword>
    <CosignServerHost>weblogin.pennkey.upenn.edu</CosignServerHost>
    <CosignServerPort>6663</CosignServerPort>
    <ConnectionPoolSize>30</ConnectionPoolSize>
    <LoginRedirectUrl>https://weblogin.pennkey.upenn.edu/login</LoginRedirectUrl>
    <LoginPostErrorUrl>https://weblogin.pennkey.upenn.edu/cosign/post_error.html</LoginPostErrorUrl>
    <CheckClientIP>false</CheckClientIP>
    <HttpsOnly>true</HttpsOnly>
    <HttpsPort>443</HttpsPort>
    <ClearSessionOnLogin>true</ClearSessionOnLogin>
    <ConfigFileMonitoringIntervalSecs>5</ConfigFileMonitoringIntervalSecs>
    <CosignServerHostIpCheck>2</CosignServerHostIpCheck>

    <!-- which URL is used for handling URL validation -->
    <LocationHandlerRef>/cosign/valid/</LocationHandlerRef>

    <!-- where to redirect users if the target URL is bad -->
    <ValidationErrorRedirect>https://weblogin.pennkey.upenn.edu/cosign/validation_error.html</ValidationErrorRedirect>

    <!-- pattern matching valid target protected URLs -->
    <RedirectRegex>https://<SERVER REGEX GOES HERE>/.*</RedirectRegex>

    <!-- protected URIs -->
    <services>
        <service name="cosign-YOUR_WMC_SERVICE_NAME">
            <protected>/protected/*</protected>
        </service>
    </services>
</CosignConfig>
Redirect Regular Expression
The field <RedirectRegex> requires a regular expression that represents the site which your users will be redirected to once they have authenticated. This is an important component as it prevents phishing of your user's passwords.

If the top-level domain of the web-site which is being authenticated is: https://cosigndev-w2k8.kite-dev.upenn.edu
Then I would put in the following regular expression within this field: ^https:\/\/cosigndev-w2k8\.kite-dev\.upenn\.edu\/.*$

This is a suggestion, your site requirements may dictate a different regular expression.

Modify the Web.xml to include CoSign required parameters

  1. Append the following code into the file C:\Program Files\apache-tomcat\conf\web.xml. Note: this can be pasted to the end of the file but just BEFORE the closing </web-app> configuration file.
    <filter>
      <filter-name>Cosign Authentication Filter</filter-name>
      <filter-class>edu.umich.auth.cosign.CosignAuthenticationFilterIII</filter-class>
      <init-param>
        <param-name>Cosign.ConfigurationFile</param-name>
        <param-value>conf\cosignConfig.xml</param-value>
      </init-param>
      <init-param>
        <param-name>Auth.JAASConfigurationFile</param-name>
        <param-value>conf\jaas.conf</param-value>
      </init-param>
    </filter>

    <!-- the following entry is required for URL validation. -->
    <!-- it should not be modified.                       -->
    <filter-mapping>
      <filter-name>Cosign Authentication Filter</filter-name>
      <url-pattern>/cosign/valid/*</url-pattern>
    </filter-mapping>
    <filter-mapping>
      <filter-name>Cosign Authentication Filter</filter-name>
      <url-pattern>/protected/*</url-pattern>
    </filter-mapping>

Create the jaas.conf file

  1. Create the file C:\Program Files\apache-tomcat\conf\jaas.conf. Paste the following into that file and save it:
CosignAuthentication
{
    edu.umich.auth.cosign.CosignLoginModule required;
};

Create necessary batch files, directories, and a test application

Create Batch Files

  1. Create the file C:\Program Files\apache-tomcat\bin\setenv.bat. Paste the content below into that file and save it. Note that your configuration may slightly differ from what is below. You will at least need to modify the VERSION tag below to your specific tomcat version and location.
set "CATALINA_HOME=%ProgramFiles%\apache-tomcat-VERSION"
set "JRE_HOME=%ProgramFiles%\Java\jre7"
set "CLASSPATH=%CLASSPATH%;%ProgramFiles%\apache-tomcat-VERSION\lib\"
exit /b 0

Create Directories

  1. Create the directory structure \cosign\valid\ under C:\Program Files\apache-tomcat\webapps\ROOT\.
  2. Create the directory \protected\ under C:\Program Files\apache-tomcat\webapps\Root\.

Create Test Application

  1. Create a simple index.jsp file at the following location: C:\Program Files\apache-tomcat\webapps\ROOT\protected\
  2. Paste the following into the index.jsp file:
<html>
  <head>
    <title>CoSign Test Application</title>
  </head>
  <body>
    Hello <%= request.getRemoteUser() %> !
  </body>
</html>

Start Tomcat

  1. Open a command prompt as an administrator and change to the C:\Program Files\apache-tomcat\ directory.
  2. Execute the following batch file C:\Program Files\apache-tomcat\bin\setenv.bat
  3. Start the tomcat server by executing C:\Program Files\apache-tomcat\bin\startup.bat
  4. Test your new web application. Connect to the secure port Tomcat's listening on:
    https://server.example.edu/protected/
    OR
    https://server.example.edu:8443/protected/
    if you haven't modified server.xml to change the default secure port
Warning
When executing setenv.bat you must be at the C:\Program Files\apache-tomcat\ directory and execute it as bin\setenv.bat. If this is not done you will receive an error that jaas.conf can not be found.
top

Information Systems and Computing
University of Pennsylvania
Comments & Questions


Penn Computing University of Pennsylvania
Information Systems and Computing, University of Pennsylvania