Atlassian Crowd (http://www.atlassian.com/software/crowd/) offers a simple solution for single sign on. It comes with an authentication server, a web based administration console and Java client libraries. Other Atlassian products such as Jira, Confluence and Bamboo integrate with Crowd. With the crowd_rails plugin, Ruby on Rails can also benefit from single sign on with Atlassian Crowd 2.0.

Installing the Plugin

The plugin is available at http://github.com/stefanwille/crowd_rails.

To install the crowd_rails plugin, run

$ gem install crowd_rails
$ gem crowd-stefanwille

crowd-stefanwille is a Ruby client library for Crowd, and crowd_rails is the Rails plugin.

Installing a Crowd Server

Beyond these gems, you will also need a Crowd server with version 2.0 or greater.

The easiest way to get started is to install an evaluation copy of Crowd on your local machine.

After you have installed your local Crowd server, test it using its demo application. Go to http://localhost:8095/demo Make sure that you can log in.

Running the Demo Application

On Github you can clone a simple demo application that uses crowd_rails for authentication. The URL is: http://github.com/stefanwille/crowd_rails_test

To run it, you will need

• a Crowd server on localhost, port 8095
• an application configured in Crowd with app name and password soaptest
• the application soaptest set 'directory' set to True

Enter

$ git clone git@github.com:stefanwille/crowd_rails_test.git
$ cd crowd_rails_test
$ bundle install
$ ruby script/server

And then point your browser to http://localhost:3000/demo.

You will get the browser's log in dialog. When you enter correct credentials, you will see a success page. Next, you can try if you are also logged in for Crowd's demo application, which should run at http://localhost:8095/demo on your local Crowd server.

Using the Plugin

To use the plugin in your own application, you need to configure the Crowd client library and then mix the module Crowd::SingleSignOn into your ApplicationController.

Add a file config/initializers/crowd_setup.rb with this content:

require 'crowd'
Crowd.crowd_url = 'http://127.0.0.1:8095/crowd/services/SecurityServer'
Crowd.crowd_app_name = 'soaptest'
Crowd.crowd_app_pword = 'soaptest'
Crowd.crowd_validation_factors_need_user_agent = false # false for Crowd 2.0.5, true for Crowd 2.0.2
Crowd.crowd_session_validationinterval = 0 # Set > 0 for authentication caching.`

This file contains the Crowd configuration for your application. Change the configuration according to your needs. Then add this to your ApplicationController class:

class ApplicationController < ActionController::Base
  include Crowd::SingleSignOn
  ...
  before_filter :authenticate

  private
  def authenticate
    return if RAILS_ENV == "test"
    return if crowd_authenticated?
    authenticate_or_request_with_http_basic('My Application') do |user_name, password|
      crowd_authenticate(user_name, password)
    end
  end
end

This will give you the browser's grey password dialog (= basic auth). Replace the call to Rails' authenticate_or_request_with_http_basic() that asks the user for username and password if you want something fancier. The demo app uses the same basic auth approach.

Log Out

There is little gotcha with respect to log out. The plugin offers the method crowd_log_out, which is also used in the demo application. The problem is that basic authentication makes it more or less impossible to log a user out, because the browser keeps sending the user's crendentials with every request. So if you want a log out feature, you need to replace basic authentication with a login form.

Interoperability

I haved tested crowd_rails plugin with Crowd 2.0.2 and 2.0.5. Also, I tested single sign on interoperability with Jira, Confluence and Bamboo.