Table of Contents

Conform Your Web Server to cosign v3 Standards

• cosign service name: cosign-<web address minus .umich.edu>
  
  cosign-www.example
• fully qualifed 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
• common name of the SSL certificate used with cosign
  www.example.umich.edu

Correcting a Mismatch
EXCEPTION NOTE: 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.

• Change the cosign service name. You do not need to contact the cosign team.
• Change your web server's FQDN, although this method is rather drastic for an active website.
• Request a new SSL certificate with an appropriate common name. Please refer to SSL Server Certificates.

1. Reset your server so that cosign reads the updated information.
2. Visit your site to very that it functions properly.

Table of Contents

Validate on the Test Server First!

Table of Contents

Configuring Servers

Table of Contents

Additional Resources

For further help with cosign, send a message to cosign@umich.edu.

Table of Contents

Apache 1 and 2

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

1. Download cosign-3.0.1.tar.gz and decompress the file. Also available at weblogin.org/download.html.
2. Stop the service you're updating.
3. Backup
   • your httpd configurations.
   • mod_cosign.so.

4. Build the filter.
   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.
      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>

      NOTES:
      • 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.
   NO EFFECT ON THOSE CURRENTLY CONNECTED: They 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.

Configuring Servers

Microsoft IIS

• 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

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. Download IIScosign-3 and decompress the file. Also available from weblogin.org/download.html.
3. Stop 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.
   NO EFFECT ON THOSE CURRENTLY CONNECTED: They 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 Servers

Configuring Java

• 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

CONFIGURATION

1. Download JavaCosign 3.0.0 RC0. Also available from weblogin.org/download.html.
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 RC0 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.

• <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.

<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

	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

Configuring Servers

Information and Technology Services