From cosign wiki

Current revision

[edit] Building and Installing the Cosign Apache Filter

[edit] 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

[edit] 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

[edit] 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

[edit] 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.

[edit] 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 copy the CA to you CA dir:

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

[edit] Mac OS X

Building and Installing on Mac OS X

Here's some Mac OS X Installation Notes

Notes from a Leopard Server Install

[edit] Configuring Apache

[edit] Apache Configuration Options

mod_cosign recognizes the following Apache configuration directives:

[edit] CosignHostname

The name of the host running cosignd.

Syntax

CosignHostname fully-qualified-domain-name

Default

cosign.example.edu

Server configuration context

VirtualHost, Location, Directory

[edit] CosignPort

The port on which Cosign listens for authentication requests.

Syntax

CosignService integer

Default

6663

Server configuration context

VirtualHost, Location, Directory

[edit] CosignService

The name of the Cosign service cookie.

Syntax

CosignService service-name

Default

None

Server configuration context

VirtualHost, Location, Directory

[edit] CosignRedirect

The URL of the Cosign login CGI.

Syntax

CosignRedirect URL

Default

None

Server configuration context

VirtualHost, Location, Directory

[edit] 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

[edit] 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+

[edit] 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+

[edit] 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

[edit] CosignFactorSuffix

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

Syntax

CosignFactorSuffix FactorSuffix

Default

None

Server configuration context

VirtualHost, Location, Directory

[edit] CosignFactorSuffixIgnore

Toggle whether the value of CosignFactorSuffix is ignored.

Syntax

CosignFactorSuffixIgnore On|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

[edit] CosignFilterDB

The path to the Cosign filter database.

Syntax

CosignFilterDB Path

Default

/var/cosign/filter

Server configuration context

VirtualHost

[edit] CosignProxyDB

The path to the Cosign proxy database.

Syntax

CosignProxyDB Path

Default

/var/cosign/proxy

Server configuration context

VirtualHost

[edit] CosignFilterHashLength

The subdirectory hash length for the Cosign filter database.

Syntax

CosignFilterHashLength 0|1|2

Default

0

Server configuration context

VirtualHost

[edit] CosignTicketPrefix

The path to the Kerberos ticket store.

Syntax

CosignTicketPrefix Path

Default

/ticket

Server configuration context

VirtualHost

[edit] CosignProtected

Toggles whether Cosign will protect the directory or location.

Syntax

CosignProtected On|Off

Default

On

Server configuration context

VirtualHost, Location, Directory, .htaccess

[edit] CosignSiteEntry

The URL to which the user is redirected after login.

Syntax

CosignSiteEntry URL

Default

None

Server configuration context

VirtualHost, Location, Directory

[edit] CosignAllowPublicAccess

Toggles whether authentication is optional for protected sites.

Syntax

CosignAllowPublicAccess On|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

[edit] 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

[edit] 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

[edit] CosignCookieExpireTime

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

Syntax

CosignCookieExpireTime time-in-seconds

Default

86400 (24 hours)

Server configuration context

VirtualHost

[edit] CosignGetProxyCookies

Toggles whether module proxy cookies will be requested from cosignd.

Syntax

CosignGetProxyCookies On|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

[edit] CosignGetProxyKerberosTickets

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

Syntax

CosignGetKerberosTickets On|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

[edit] 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

[edit] 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.

[edit] 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.
    #
    # Note: this Location syntax will fail with a 404 if Options Multiviews is set
    # in the Directory entry
    <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:

• University of Michigan

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