Skip to content

Installation

Jump to bottom Edit New page
zuk edited this page Oct 24, 2012 · 7 revisions

Server Requirements

  • Ruby 1.8.7 or newer
  • RubyGems + Bundler
  • Ruby bindings for your preferred database.
  • An SSL certificate (CAS requires SSL)
  • A Unix-like OS

Quickstart

➭ See the Quick Start page to get up and running quickly.

➭ All configuration options are documented inside the annotated config.example.yml configuration file.

If you encounter any bugs or issues with RubyCAS-Server, please do not hesitate to open an issue ticket!

Installation Walkthrough

The following is a detailed walkthrough explaining the process of setting up and running RubyCAS-Server. A quick guide for configuring the Rails and PHP CAS clients is also provided.

This guide assumes that you are on a Linux system. RubyCAS-Server should work fine on other platforms (Windows, Mac OS X, BSD, etc.), but you will have to translate a few things for yourself (file system paths, for example).

Configuring

Follow the Quick Start instruction to get a basic standalone server running on the command line.

Note that there are several ways to run RubyCAS-Server. For production deployment, take a look at Deploying Under Passenger. The instructions below are for configuring a standalone server for testing, although many of the configuration options described here also apply to a Passenger deployment.

RubyCAS-Server's config.yml file is formatted using YAML, a simple, text-based format easily readable by both humans and machines. YAML formatting is mostly self-explanatory, but one thing to be careful about is indentation. Make sure that you use spaces instead of tabs, as YAML is sensitive to whitespace.

You can leave most of the settings in config.yml at their defaults, but a few things need to be changed:

  • ssl_cert: The ssl_cert value must point to your SSL certificate .pem file. You can use a self-signed certificate for testing, but you should obtain a real one from a Certificate Authority for production use. Free, 30-day limited certificates are available from FreeSSL, or if you just want to get started right away you can download a demo SSL certificate for use with RubyCAS-Server here. It is also possible to run RubyCAS-Server on regular, non-SSL HTTP. To do this, simply omit the ssl_cert parameter -- but keep in mind that some CAS clients will refuse to talk to your server unless it is using SSL, and in any case you should never run CAS over regular, unencrypted HTTP for production purposes.
  • database: The database settings need to be entered up for your database server. The options here are self-explanatory, but you can check the ActiveRecord documentation for details.
  • authenticator: Finally, you'll have to configure the back-end authenticator against which RubyCAS-Server validates usernames and passwords. Keep in mind that the CAS server does not maintain its own list of users -- it uses some pre-existing data source of your choice. Several example authenticator configurations are included in the config.yml file. Pick the one best suited for your needs and uncomment it (by removing the # at the beginning of each line). Your web application probably already has a SQL table with usernames and passwords, so using this existing database may be the simplest choice (if so, uncomment and modify the "SQL Authentication" section in the default config.yml). Other possible methods include LDAP, ActiveDirectory (via LDAP), or writing your own custom authenticator.

See the [[Customizing] wiki page if you're interested in changing how your RubyCAS-Server looks.

Running

Now that you have RubyCAS-Server configured, you should be able to start it up. Since by default RubyCAS-Server writes to some system directories (for example logging to /var/log/casserver.log), you will have to launch it as root. Try sudo rubycas-server in your shell prompt. You should get output roughly like this:

*** Starting RubyCAS-Server 0.4.2 using codebase at /usr/lib/ruby/gems/1.8/gems/rubycas-server-0.4.2/lib
[2007-08-03 13:14:54] INFO  WEBrick 1.3.1
[2007-08-03 13:14:54] INFO  ruby 1.8.5 (2006-08-25) [i586-linux]
[2007-08-03 13:14:54] INFO  
Certificate:
    Data:
        Version: 3 (0x2)
        ... lots of other SSL certificate info ...

** CASServer is running at https://<your hostname>:443/cas and logging to '/var/log/casserver.log'

Note that further logging is done to /var/log/casserver.log (or to whatever you configured your log path). You can monitor what's going on using tail: tail -f /var/log/casserver.log.

To make sure that everything is working, point your web browser to https://localhost/cas. You should see the default CAS login page.

Setting up CAS Clients

We've got our basic CAS server up and running, so it's time to configure our websites to use CAS for authentication.

We will assume that your CAS server is accessible at https://login.example.com/cas.

Rails Clients

For Rails 3.0 or later, we will use RubyCAS-Client-Rails. This works as a standard Rails controller filter. Detailed installation and configuration instructions are available in the README.

For Rails 2.x you'll also have to use the older CAS Filter packaged with RubyCAS-Client. Look for installation instructions in the README.

PHP Clients

To protect our PHP application, we will use the phpCAS library. Download and installation instructions are available at http://www.ja-sig.org/wiki/display/CASC/phpCAS+installation+guide+and+requirements.

Once the library has been installed, you should create a file that will be included at the top of every CAS-protected page. Lets call it cas_filter.inc.php, and paste into it the following code:

<?php
if (!$_SESSION['casfilteruser']) :
        session_start();
        
        phpCAS::setDebug('cas.log');
        
        phpCAS::client(CAS_VERSION_2_0,'login.example.com',443,'cas');
        
        if ($_REQUEST['service']) :
                phpCAS::setFixedServiceURL(urlencode($_REQUEST'service']));
        endif;
        
        phpCAS::forceAuthentication();
        
        // at this step, the user has been authenticated by the CAS server
        // and the user's login name can be read with phpCAS::getUser().
        
        // logout if desired
        if (isset($_REQUEST['logout'])) {
                phpCAS::logout();
        }
        
        $_SESSION['casfilteruser'] = phpCAS::getUser();
endif;
?>

Now, we'll need to require this at the top of our CAS-protected pages:

  <?php require('cas_filter.inc.php') ?>

However, for this to work, we have to make sure that we have a session started BEFORE the CAS authentication takes place. You should make sure then that the session is started in some code above the cas_fitler require using session_start() or that you have PHP configured to auto-start sessions with every request.

Once authenticated, as with the Rails filter, the user's username should be available at $SESSION['casfilteruser'].

To log out, simply go to any protected page with &logout added to the URI.

Add a custom footer
Add a custom sidebar
Clone this wiki locally