cosign wiki:CosignInstallation

From cosign wiki

Revision as of 17:22, 24 March 2010 by Ashsc (Talk | contribs)
Jump to: navigation, search

Contents

Building and Installing the Cosign Apache Filter

Requirements

The Cosign Apache filter requires:

  • Apache v1.3.x or v2.x
  • OpenSSL v0.9.7a or newer
  • A source of entropy for the OpenSSL libraries.
    If your system already has /dev/*random, then you're all set; otherwise, look into installing prngd or egd.
    Solaris users should refer to Sun document 27606, "Differing /dev/random support requirements within Solaris [TM] Operating Environments", at http://sunsolve.sun.com. Users of operating systems lacking a built-in source of entropy, such as AIX, will wneed prngd.
  • MIT Kerberos krb5-1.2.7 or later (optional, for protected services that require Kerberos credentials)
    Kerberos libraries are not required if you do not need access to Kerberos credentials.
    If you are building a central weblogin server, see the Cosign weblogin README.
  • mod_ssl (more information is needed here)
  • GNU libtool

Build Configuration Options

./configure may take the following options: 

--enable-krb=path_to_krb                enables Kerberos V
--enable-apache1=path_to_apxs_1.3       enables Apache 1.3 filter
--enable-apache2=path_to_apxs_2         enables Apache 2 filter
--with-GSS                              enables GSSAPI
--with-filterdb=DIR                     overrides default of /var/cosign/filter

Building for Red Hat 9 or RHAS 3

required packages:

  • httpd-devel
  • openssl
  • openssl-devel
  • libtool

In Red Hat Linux 9, Kerberos is in a non-standard place. configure may not find it by default. Before before running configure, prepend env CPPFLAGS=-I/usr/kerberos/include to the command.

In csh, configure should resemble the following: 

env CPPFLAGS="-I/usr/kerberos/include" ./configure

In bash or sh, configure should resemble the following: 

CPPFLAGS="-I/usr/kerberos/include" ./configure

Including APR Flags

In some cases, a configure attempt may fail with "file not found" errors related to Apache Portable Runtime (APR) headers, such as the following: 

/usr/include/httpd/ap_config.h:19:17: apr.h: No such file or directory

To remedy this error, prepend a CPPFLAGS parameter to locate the APR headers for apxs.

In csh: 

env CPPFLAGS="-I/usr/include/apr-0/" ./configure

In bash or sh: 

CPPFLAGS="-I/usr/include/apr-0/" ./configure

RedHat Enterprise Linux 5 requires different flags. The appropriate flags for your system can be found by using apr-1-config: 

/usr/bin/apr-1-config --cppflags
/usr/bin/apr-1-config --cflags

Use the values returned for CFLAGS and CPPFLAGS when running configure.

Building and Installing the Filter

1) Configure the build with any required flags and options: 

./configure [options]

2) Make the build: 

make

3) Install the the filter (using your copy of apxs): 

make install

4) Create a Cosign filter directory: 

mkdir -p /var/cosign/filter

5) Set ownership for the a Cosign filter directory. Be sure to change APACHE_USER to the username defined in your httpd.conf file. 

chown APACHE_USER /var/cosign/filter

6) Create a CA directory to store your CA certificates. 

mkdir -p /usr/local/etc/apache/certs

7) Copy the CAs from the Cosign source distribution CAcerts directory to your CA dir: 

cp CAcerts/* /usr/local/etc/apache/certs

Download the latest umwebCA.pem file (http://www.umich.edu/~umweb/umwebCA.pem). cd to the directory containing the downloaded umwebCA.pem file and issue this command: 

cp umwebCA.pem /usr/local/etc/apache/certs/umwebCA.pem

8) Issue the c_rehash command, which is a perl script that ships with OpenSSL. Assuming a CA directory of /usr/local/etc/apache/certs, the command would be: 

c_rehash /usr/local/etc/apache/certs

The output should resemble the following: 

Doing /usr/local/etc/apache/certs
    umwebCA.pem => 4700e8dd.0
   RSA-SSCA.pem => f73e89fd.0
   entrust.pem => ed524cf5.0

Mac OS X

Building and Installing on Mac OS X

Here's some Mac OS X Installation Notes

Notes from a Leopard Server Install

Configuring Apache

Apache Configuration Options

mod_cosign recognizes the following Apache configuration directives:

CosignHostname

The name of the host running cosignd.

Syntax
CosignHostname fully-qualified-domain-name
Default
cosign.example.edu
Server configuration context
VirtualHost, Location, Directory

CosignPort

The port on which Cosign listens for authentication requests.

Syntax
CosignService integer
Default
6663
Server configuration context
VirtualHost, Location, Directory

CosignService

The name of the Cosign service cookie.

Syntax
CosignService service-name
Default
None
Server configuration context
VirtualHost, Location, Directory

CosignRedirect

The URL of the Cosign login CGI.

Syntax
CosignRedirect URL
Default
None
Server configuration context
VirtualHost, Location, Directory

CosignPostErrorRedirect

The URL to which a user is redirected to if an error is encountered during a POST to the login CGI. This screen informs the user that their data has been dropped.

Syntax
CosignPostErrorRedirect URL
Default
None
Server configuration context
VirtualHost, Location, Directory

CosignValidReference

A regular expression matching valid service URLs. The administrator uses this directive to ensure users will be redirected to a safe URL following cookie validation.

Syntax
CosignValidReference regex
Default
None
Server configuration context
VirtualHost, Location
Availability
Cosign 3.0+

CosignValidationErrorRedirect

The URL to which a user is redirected if the service URL does not match the regular expression from CosignValidReference, or if mod_cosign cannot validate the service cookie passed from the CGI.

Syntax
CosignValidationErrorRedirect URL
Default
None
Server configuration context
VirtualHost, Location
Availability
Cosign 3.0+

CosignRequireFactor

A list of the factors that must be satisfied by the user.

Syntax
CosignRequireFactor Factor1[Factor2...FactorN]
Default
None
Server configuration context
VirtualHost, Location, Directory

CosignFactorSuffix

An optional factor suffix to be used when testing for compliance.

Syntax
CosignFactorSuffix FactorSuffix
Default
None
Server configuration context
VirtualHost, Location, Directory

CosignFactorSuffixIgnore

Toggle whether the value of CosignFactorSuffix is ignored.

Syntax
CosignFactorSuffixIgnore On|Off
Default
Off
Server configuration context
VirtualHost, Location, Directory

CosignFilterDB

The path to the Cosign filter database.

Syntax
CosignFilterDB Path
Default
/var/cosign/filter
Server configuration context
VirtualHost

CosignProxyDB

The path to the Cosign proxy database.

Syntax
CosignProxyDB Path
Default
/var/cosign/proxy
Server configuration context
VirtualHost

CosignFilterHashLength

The subdirectory hash length for the Cosign filter database.

Syntax
CosignFilterHashLength 0|1|2
Default
0
Server configuration context
VirtualHost

CosignTicketPrefix

The path to the Kerberos ticket store.

Syntax
CosignTicketPrefix Path
Default
/ticket
Server configuration context
VirtualHost

CosignProtected

Toggles whether Cosign will protect the directory or location.

Syntax
CosignProtected On|Off
Default
On
Server configuration context
VirtualHost, Location, Directory, .htaccess

CosignSiteEntry

The URL to which the user is redirected after login.

Syntax
CosignSiteEntry URL
Default
None
Server configuration context
VirtualHost, Location, Directory

CosignAllowPublicAccess

Toggles whether authentication is optional for protected sites.

Syntax
CosignAllowPublicAccess On|Off
Default
Off
Server configuration context
VirtualHost, Location, Directory

CosignHttpOnly

Toggles whether the module can be used without SSL. Enabling this directive is not recommended.

Syntax
CosignHttpOnly On|Off
Default
Off
Server configuration context
VirtualHost, Location, Directory

CosignCrypto

Paths to the SSL key file, certificate file, and CA directory.

Syntax
CosignCrypto <key file> <cert file> <ca directory>
Default
/var/cosign/certs/key.pem /var/cosign/certs/cert.pem /var/cosign/certs/CA
Server configuration context
VirtualHost, Location, Directory

CosignCookieExpireTime

Assigns the expiration time, in seconds, for authentication cookies.

Syntax
CosignCookieExpireTime time-in-seconds
Default
86400 (24 hours)
Server configuration context
VirtualHost

CosignGetProxyCookies

Toggles whether module proxy cookies will be requested from cosignd.

Syntax
CosignGetProxyCookies On|Off
Default
Off
Server configuration context
VirtualHost, Location, Directory

CosignGetProxyKerberosTickets

Toggles whether the value of "tgt" will be requested from cosignd.

Syntax
CosignGetKerberosTickets On|Off
Default
Off
Server configuration context
VirtualHost, Location, Directory

CosignGetProxyKerberosSetupGSS

Toggles whether the enviornment will be set up such that other Apache modules that require GSSAPI or Kerberos will work, such as IMP running under mod_php.

Syntax
CosignGetKerberosSetupGSSOn|Off
Default
Off
Server configuration context
VirtualHost, Location, Directory

CosignCheckIP

Toggles whether the browser's IP is verified against cosignd's IP information.

Syntax
CosignCheckIP never|initial|always
Default
initial
Server configuration context
VirtualHost

Note: The certificate CN of the weblogin server must match the value of CosignHostname.


Configuration Example

Configure your Apache Virtual Host directives to include the following:

On the http side (port 80), and any dirs or locations that you want to exempt from Cosign protection: 

    CosignProtected Off

On port 443 or other https ports, Virtual Host directives should include: 

    CosignProtected		On
    CosignHostname		weblogin.example.com
    CosignRedirect		https://weblogin.example.com/
    CosignPostErrorRedirect https://weblogin.example.com/post_error.html
    CosignService		[contact the group that runs your institution's weblogin server to get one assigned]
    CosignCrypto		/path/to/file.key /path/to/file.cert /path/to/CAdir

    # Cosign 3.0+
    CosignValidReference    https://secure-service\.example\.edu/.*

    # Cosign 3.0+ additionally requires the administrator to designate mod_cosign as the
    # handler for a special URI, usually /cosign/valid, where validation of the service URL
    # and the service cookie takes place before granting the user access to the service.
    <Location /cosign/valid>
         SetHandler                cosign
         CosignProtected        Off
         Allow from all
         Satisfy any
     </Location>

Note: A trailing slash (/) is required on CosignRedirect! The redirects won't work correctly without it.

Restart Apache: 

apachectl graceful

For a cron job that prunes old cookies from the filter's database, and for scripts for local logout, see the Cosign support scripts README.


Institution-specific information:


--John DeStefano 11:38, 16 November 2006 (EST)

Retrieved from "http://webservices.itcs.umich.edu/mediawiki/cosign/index.php/cosign_wiki:CosignInstallation"
Personal tools