CAS Client Gem

Introduction

---

This gem is meant to be used as a wrapper over the User API and CAS authentication functionality. It consists of these two parts, as a controller that can be inherited from, and a module to be included into an ActiveRecord model.

SessionsController

---

Provides a template for an app’s SessionsController.

‘

class SessionsController < CASClient::SessionsController

  skip_before_filter :authorize, :only => [:new, :create] # disable whatever authorization mechanism you have for these actions so that the server can redirect users who are not logged in

  def create
    session[:uuid] = request.env['rack.auth']['uid'] # do whatever you need here to persist the users session within your app
    redirect_to '/'
  end

  def cas_logout
    session[:uuid] = nil # do whatever you need here to kill a user's session
    super
  end

end

‘

Scenarios:

* User login
  1. User goes to '/login' which hits Sessions#new
  2. User is redirected to CAS to login
  3. CAS will authenticate and redirect back to Sessions#create which will receive all of the users credential info in request.env['rack.auth']

* User logout
  1. User goes to '/logout'
  2. User is redirected to CAS where their session on CAS is expired
  3. CAS opens up connections to '/cas_logout' to expire sessions on all client apps covered by the CAS

User API

---

A module to be included into your User model:

‘

class User < ActiveRecord::Base
  include CASClient::UserAPI

  after_create :cas_create
  after_save :cas_update_attributes

  def self.cas_map
    {
      :uuid        => :username,
      :first_name  => :firstname,
      :middle_name => :middlename,
      :last_name   => :lastname,
      :email       => :email_address
    }
  end
end

‘

**The callbacks in the example model above are optional.**

Class Methods:

* User.cas_all: returns an array with hashes of attributes for all users
* User.cas_fetch_user(uuid): returns a hash of the attributes for this user or nil if there is no user with this uuid
* User.cas_uuid_available?(uuid): returns true or false depending on the availability of the uuid on CAS

Instance Methods:

* user.cas_create: creates a new user on CAS with this user's attributes
  - **NOTE: if the unique user ID that is submitted has already been taken, CASClient will raise UserAlreadyExists
* user.cas_update_attributes: updates the attributes for this user on CAS
* user.cas_retrieve_attributes: retrieves the attributes for this user on CAS
  - **NOTE: if the unique user ID that is submitted has already been taken, CASClient will raise UserAlreadyExists
* user.cas_reset_password: will flag the user as needing password reset, and send them and email to do so
  - **NOTE: if this user does not have an email address on CAS before calling this method, CASClient will raise MissingEmail

Creating a User account through Facebook

---

1. Add a link to the facebook_signup_path where you would have your icon for Facebook Connect.

2. In Sessions#create you can use User.find_or_create_facebook_user_by_* to wrap the lower-level User.find_or_create_by_* call, but populated with the Facebook parameters.

- Pass the request.env['rack.auth'] hash into this method call
- This will return a user