From cosign wiki

Contents 1 Building and Installing the Cosign Apache Filter 1.1 Requirements 1.2 Build Configuration Options 1.2.1 Building for Red Hat 9 1.2.2 Including APR Flags 1.3 Building and Installing the Filter 1.4 Configuring Apache 1.4.1 Apache Configuration Options 1.4.1.1 CosignHostname 1.4.1.2 CosignPort 1.4.1.3 CosignService 1.4.1.4 CosignRedirect 1.4.1.5 CosignPostErrorRedirect 1.4.1.6 CosignRequireFactor 1.4.1.7 CosignFactorSuffix 1.4.1.8 CosignFactorSuffixIgnore 1.4.1.9 CosignFilterDB 1.4.1.10 CosignProxyDB 1.4.1.11 CosignFilterHashLength 1.4.1.12 CosignTicketPrefix 1.4.1.13 CosignProtected 1.4.1.14 CosignSiteEntry 1.4.1.15 CosignAllowPublicAccess 1.4.1.16 CosignHttpOnly 1.4.1.17 CosignCrypto 1.4.1.18 CosignCookieExpireTime 1.4.1.19 CosignGetProxyCookies 1.4.1.20 CosignGetProxyKerberosTickets 1.4.1.21 CosignGetProxyKerberosSetupGSS 1.4.1.22 CosignCheckIP 1.4.2 Configuration Example (University of Michigan specific)

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 want to get 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)

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

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 

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

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

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

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

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

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 (University of Michigan specific)

In the U of M environment, 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.umich.edu
    CosignRedirect		https://weblogin.umich.edu/
    CosignPostErrorRedirect https://weblogin.umich.edu/post_error.html
    CosignService		[e-mail to cosign@umich.edu and we will assign]
    CosignCrypto		/path/to/key /path/to/cert /path/to/CAdir

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.

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