Configuring Servers for cosign v3

Cosign v3 provides enhanced security architecture. It is incompatible with previous versions, so you cannot use a legacy cosign filter. This document explains how to configure a server for cosign v3 authentication.

Conform Your Web Server to cosign v3 Standards

The strict cosign v3 namespace requirements mandate that the following entities match. Examples are based on a cosign-protected website with the URL www.example.umich.edu.

  1. cosign service name: cosign-<web address minus .umich.edu>
    cosign-www.example

  2. fully qualified domain name (FQDN) of your web site: the host name part of the URL a user enters to access your website
    www.example.umich.edu

  3. common name of the SSL certificate used with cosign
    www.example.umich.edu

We recommend you validate this even before you upgrade to v3. Information for determining the cosign service name and the SSL certificate's common name is available in the Configuring Servers section.

Correcting a Mismatch
Note Exception: If you prefer, you can request an exception from cosign@umich.edu. Include your server's 1) cosign service name, 2) FQDN, and 3) SSL certificate common name.

  1. Change the cosign service name. You do not need to contact the cosign team.

  2. Change your web server's FQDN, although this method is rather drastic for an active website.

  3. Request a new SSL certificate with an appropriate common name. Please refer to SSL Server Certificates.

After Correcting a Mismatch

  1. Reset your server so that cosign reads the updated information.

  2. Visit your site to verify that it functions properly.

Validate on the Test Server First

We highly recommended you validate your test configuration against either the cosign test — weblogin-test.itcs.umich.edu — or the production — weblogin.umich.edu — servers. If you are upgrading to version 3, also create a rollback plan in case your configuration generates an error. We provide specifics for each server in the Configuring Servers section.

Configuring Servers


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 cosign@umich.edu.

    • 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 cosign@umich.edu. 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>

      Inserting text between a </Cookies> (if it exists) and the <ConnectionPoolSize> tags

      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 cosign@umich.edu. 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.

  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 cosign@umich.edu. 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
Tags: 
Last Updated: 
Wednesday, May 6, 2015