Configuring Servers for cosign v3

---

Apache 1 and 2

Find your server's SSL certificate common name by running the command line
    openssl x509 -subject -in /path/to/server.cert | head -n 1 | awk -F '/' '{ gsub(/CN=/, ""); print $7 }'

The common name should be in the form www.example.umich.edu. The cosign service name should be the website's host name without the domain umich.edu — www.example.

1. Download cosign-3.2.0.tar.gz and decompress the file. The file is also available at http://weblogin.org/download.shtml.

2. Stop the service that you're updating.

3. Backup

   • your httpd configurations.
   • mod_cosign.so.

4. Build the filter.
   Note Need ticket retrieval? Add --enable-krb and --with-gss.
   MAC OS X: Add --enable-universal-binaries. This option builds a universal binary for supported PowerPC and Intel Macintosh computers. If you would like assistance, please contact [email protected].

   • Apache 1

     ./configure --enable-apache1=/path/to/apache1/apxs
     make
     make install

   • Apache 2

     ./configure --enable-apache2=/path/to/apache2/apxs
     make
     make install

5. Using an editor that does not hard-wrap lines or convert text to RTF:

   1. Open the Apache configuration file that contains your CosignHostname definition. Your httpd setup determines the location of this file; for example, /etc/apache2/httpd.conf, /etc/apache2/site_conf, or /etc/httpd/httpd.conf.
      Note Using multiple virtual hosts? Edit each configuration that defines a CosignHostname directive.

   2. Directly below the CosignHostname directive line, add the following 6 lines:

      CosignValidReference              ^https?:\/\/.*\.umich\.edu(\/.*)?
      CosignValidationErrorRedirect      http://weblogin.umich.edu/cosign/validation_error.html
      <Location /cosign/valid>
           SetHandler          cosign
           CosignProtected     Off
           Allow from all
           Satisfy any
      </Location>

      Note

      • Because CosignValidReference is a regular expression (regex), you can be as specific as you like. The expression above redirects to any web page within umich.edu. To redirect only to your service, use an expression such as

        ^https?:\/\/www\.example\.umich\.edu(\/.*)?

      • the CosignValidationErrorRedirect provides a page alerting a user that validation has failed.

6. Using the following string, delete all service cookies from the cookies database to invalidate existing service cookies.
   Note No effect on those already connected: These individuals will automatically be issued v3 service cookies and not experience any difficulties.

   find /var/cosign/filter -type f -print0 | xargs -0 rm -f

7. Restart your service.

8. Access a cosign-protected page on your service to validate that it is properly redirected to weblogin or weblogin-test.

9. After completing the upgrade to a v3 filter, please confirm with with the cosign team at [email protected]. We will remove any v2 exceptions in order to make your service even more secure.

 

---

Microsoft IIS

Find your server's:

• cosign service name in the cosign.dll.config file.

  <Service>

  <Name>cosign-www.example</Name>

  </Service>

• SSL certificate common name by running the command line
      openssl x509 -subject -in /path/to/server.cert
  The common name will be displayed after CN=, as in CN=www.example.umich.edu

If these two entities don't match, please refer to Correcting a Mismatch.

CONFIGURATION

1. Create a backup of your service by:

   1. creating a new folder, such as C:\iiscosign.backup.

   2. copying the contents of the IISCosign installation folder — the default location is C:\program files\iiscosign — to the new folder.

2. If you are using Windows 2008/IIS7, download Cosign module 3.1.0 and decompress the file. If you are using Windows 2003/IIS6, download IISCosign 3.0.0 and decompress the file. Also available from http://weblogin.org/download.shtml.

3. Terminate the IIS service. You can use the command

   iisreset /stop

4. Move the files to the IISCosign directory.

5. Open cosign.dll.config.

   1. Insert these two XML lines between a </Cookies> (if it exists) and the <ConnectionPoolSize> tags:

      <ValidReference>^https?:\/\/.*\.umich\.edu(\/.*)?</ValidReference>
      <ValidationErrorRedirect>http://weblogin.umich.edu/cosign/validation_error.html</ValidationErrorRedirect>

      

      Note Because ValidReference is a Perl-style regular expression, you can be as specific as you like. The above example will match any URL containing umich.edu. A more specific entry for www.example.umich.edu is:

      <ValidReference>^https?:\/\/www\.example\.umich\.edu(\/.*)?</ValidReference>

   2. To be able to test this configuration against weblogin.umich.edu, alter <LoginServer>:

      <LoginServer>
      <DNSName>weblogin.umich.edu</DNSName>
      <LoginURL>https://weblogin.umich.edu/?</LoginUrl>
      <LoginPostErrorUrl>https://weblogin.umich.edu/cosign/post_error.html</LoginPostErrorUrl>
      <Port>6663</Port>
      </LoginServer>
      ....
      <ValidationErrorRedirect>https://weblogin.umich.edu/cosign/validation_error.html</ValidationErrorRedirect>

6. Delete all files from the IISCosign/CookieDB directory in order to invalidate existing service cookies.
   Note No effect on those currently connected: These individuals will automatically be issued v3 service cookies and not experience any difficulties.

7. Restart the IIS service. You can use the command

   iisreset /start.

8. Access a cosign-protected page on your service to validate that it is properly redirected to weblogin or weblogin-test.

9. After completing the upgrade to a v3 filter, please confirm with with the cosign team at [email protected]. We will remove any v2 exceptions in order to make your service even more secure.

 

---

Configuring Java

To check the common name of the certificate used by a cosign filter:
Tip Corrupt keystore? Keystores created with java runtime versions other than what you are currently running may appear corrupt but will still work.

• Stand-alone certificate

  keytool -printcert -v -file mydomain.crt

• Certificates in a java keystore

  keytool -list -v -keystore keystore.jks

• Particular keystore entry using an alias

  keytool -list -v -keystore keystore.jks -alias mydomain

Note We recommend you save your current cosign jar and configuration files in case you need to restore them in the event of an error.

CONFIGURATION

1. Download JavaCosign 3.0.0. Also available from http://weblogin.org/download.shtml.

2. Also download these two example files to help you configure the filter and your Web application.

   • http://cosign.cvs.sourceforge.net/viewvc/cosign/javacosign/etc/cosignConfig-example.xml

   • http://cosign.cvs.sourceforge.net/viewvc/cosign/javacosign/etc/web-xml-example.xml

3. From http://cosign.cvs.sourceforge.net/viewvc/cosign/javacosign/libs/, download the three supporting jar files.

4. Copy the files from JavaCosign 3.0.0 and the supporting jar files to either your:

   • web application lib dir
   • servlet container lib dir

5. Using the downloaded example files and the following information, configure the cosign v3 filter and your web.xml file.

6. Access a cosign-protected page on your service to validate that it is properly redirected to weblogin or weblogin-test.

7. After completing the upgrade to a v3 filter, please confirm with with the cosign team at [email protected]. We will remove any v2 exceptions in order to make your service even more secure.

cosign config file

• <services><service> nodes

  <services>
  <service name = "cosign-www.xyz">
  <!-- this will defalt back to www.xyz.umich.edu -->
  <reqfactor>
  <factor>UMICH.EDU</factor>
  </reqfactor>
  <protected>/cosign-secure/protected/</protected>
  <service>
  <services>

  Each service node has a name attribute that begins with cosign-. The cosign v3 filter defines the service by the site path found in <protected></protected> node, which has three optional attributes:

  • allowpublicaccess — the filter allows access without passing on user information

  • qs — the query string path the filter users for the protected rule

  • rs — the resource within the path; for example, test.jsp.

  • Location Handler: You may need to add this directory to your application in order for the web container to recognize the request.

• <LocationHandlerRef>/cosign/valid</LocationHandlerRef>

  By default, the cosign server returns the browser to
  <host>/cosign/valid/ as in www.example.umich.edu/cosign/valid/
  allowing the host to determine the legitimacy of the request.

web.xml file

<filter-mapping>
<filter-name>Cosign Authentication Filter</filter-name>
<url-pattern>/cosign/valid/*</url-pattern>
</filter-mapping>

This activates the filter for this path, and it defines the Location Handler url path in the cosign v3 configuration file.

New Java cosign v3 Configuration Settings

Setting	Default	Description
KerberosKrb5Debug true/false	false	Put Kerberos debug information to system out when true and KerberosGetTickets is true
KerberosGetTickets true/false	none	Places Kerberos ticket(s) in the subject object for the specific user
CosignGetProxies true/false	false	Retrieves proxy cookie and places it in the Cosign Principle object Note Not yet complete
KerberosTicketCachDirectory	none	Temporary cache area for Kerberos tickets returned from the Kerberos libraries
KerberosKrb5Conf	none	Path to the Kerberos configuration file
LocationHandlerRef	/cosign/valid	Url path to the filters location handler
RedirectRegex	none	Regular expression the filter uses to verify the returned url from the cosign server
CosignServerHostIpCheck	none (internally set to 60	Number of minutes the filter will wait before refreshing its cache of IP numbers for the cosign servers