dmcnicks-cas

Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with dmcnicks-cas
   • What dmcnicks-cas affects
   • Beginning with dmcnicks-cas
4. Usage - Configuration options and additional functionality
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Overview

Puppet module that manages configuration for Central Authentication Service (CAS).

Module Description

CAS is a single sign-on protocol for the web that supports multiple backends for authentication and authorisation. This puppet module manages CAS configuration files that support an LDAP backend.

CAS is deployed as a war file that is built using a separate Maven overlay build process. The cas::server class expects to be told the location of a pre-built war file to deploy. If you are unfamiliar with Maven overlays or CAS you can use the cas::war class to create a Maven project that is configured to support connecting to an LDAP backend.

Do not use the cas::war class to build war files in a production context. Maven can take a long time to download dependancies that can lead to a puppet timeout and an inconsistent node. For production use, create a separate Maven project under its own version control and distribute a pre-built war file to nodes using a separate mechanism.

Setup

What dmcnicks-cas affects

• Copies a given war file into a given web application container for deployment.
• Creates configuration files in /etc/cas.
• Creates CAS log files in /var/log/cas.

Beginning with dmcnicks-cas

To create a Maven project and build the war, create a temporary build.pp on the node you are working with, containing:

class build () {
    class { "cas::war":
        maven_dir => "/srv/cas-maven",
        build => true
    }
}

Then call the manifest using puppet apply:

$ puppet apply build.pp

Maven will take some time to download all of the required dependancies. Eventually it will create a customised war file located in /srv/cas-maven/target/cas.war.

Next, you will need to configure Apache and a web application container such as Tomcat on the node using your puppet infrastructure. As an example, the following manifest will use puppetlabs-apache, camptocamp-openssl and camptocamp-tomcat to configure Apache and Tomcat:

class { "tomcat":
    version => "7"
} ->

tomcat::instance { "cas":
    ensure => present,
    server_port => "8006",
    http_port => "8081",
    ajp_port => "8010"
} 

include apache
include apache::mod::ssl
include apache::mod::proxy
include apache::mod::proxy_ajp

openssl::certificate::x509 { $::fqdn:
    ensure => present,
    country => "UK",
    organization => "My Organization",
    commonname => $::fqdn,
    days => "3650",
    force => false,
    cnf_tpl => "openssl/cert.cnf.erb",
    base_dir => "/etc/ssl/certs"
} ->

apache::vhost { $::fqdn:
    port => "443",
    ssl => true,
    ssl_key => "/etc/ssl/certs/${::fqdn}.key",
    ssl_cert => "/etc/ssl/certs/${::fqdn}.crt",
    docroot => "/var/www",
    proxy_pass => [
        { path => "/cas", url => "ajp://localhost:8010/cas" }
    ]
}

Finally, declare the cas::server class:

class { "cas::server":
    war => "/srv/cas-maven/target/cas.war",
    deploy_to => "$tomcat::instance_basedir/cas/webapps/cas.war",
    ldap_url => "ldaps://your.ldap.server",
    ldap_trustedcert => "/path/to/your.ldap.crt",
    ldap_basedn => "dc=your,dc=base,dc=dn",
    ldap_managerdn => "cn=youradmin,dc=your,dc=base,dc=dn",
    ldap_managerpassword => "youradminpassword",
    ldap_searchfilter => "(uid={user})",
    require => Tomcat::Instance["cas"]
}

Usage

Class cas::server

Manages CAS configuration files on the node and is responsible for deploying the CAS war file.

Parameters

group

(Required) The group that the web application container (e.g. Tomcat) runs as. This is used to set group permissions on the configuration files and log directory, to ensure that they are accessible by the container.

war

(Required) The location of the pre-build CAS war file. This will be copied into the deploy_to location.

deploy_to

(Required) The final location of the war file. This should be a file name rather than a directory and, in order for CAS to work, the file itself should usually be cas.war.

ldap_url

(Required) The URL of the LDAP server.

ldap_basedn

(Required) The base DN of the LDAP server.

ldap_managerdn

(Required) The DN of the manager account used to bind to the LDAP server.

ldap_managerpassword

(Required) The password of the manager account used to bind to the LDAP server.

ldap_searchfilter

(Required) Search filter used to locate user objects in LDAP. CAS populates the variable {user} with the name of the currently authenticating user so this search filter should look something like (uid={user}).

vhost_name

(Optional) The name of the virtual host that CAS is running on. This is mainly required for when CAS is running behind a load balancer. Defaults to the node FQDN.

ldap_trustedcert

(Optional) If the LDAP server is using LDAPS, provide a CA certificate chain or the LDAP server certificate (if self-signed) to enable secure communication.

ldap_usestarttls

(Optional) Set to true if your LDAP server uses STARTTLS. Defaults to false.

debug

(Optional) Set to true to enable debug logging. Defaults to false.

Class cas::war

Creates a maven project for CAS that supports an LDAP backend and optionally builds the war file.

Parameters

maven_dir

(Required) The base directory for the Maven project.

build

(Optional) Set to true to build the war once the Maven project has been created. Defaults to false.

Variables

cas::war::location

Once the war file is built, calling classes can refer to this variable to find the location of the build war file.

Limitations

CAS is a complex piece of software. I wrote this module to try to simplify getting a working CAS server connected to an LDAP backend, but the reality is that a lot can go wrong.

Development

I am happy to receive pull requests.