cas_client 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rvmrc

@@ -0,0 +1 @@
+rvm use ree-1.8.7-2010.02@spec_app

data/Gemfile

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in cas_client.gemspec
+gemspec
+

data/README

@@ -0,0 +1,89 @@
+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

data/Rakefile

@@ -0,0 +1,4 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+load File.dirname(__FILE__) + "/spec/tasks/spec.rake"

data/TODO

@@ -0,0 +1 @@
+1. test SessionsController

data/app/controllers/cas_client/sessions_controller.rb

@@ -0,0 +1,20 @@
+class CASClient::SessionsController < ApplicationController
+  unloadable # ensures this controller doesn't get reloaded between requests in development
+
+  def new
+    redirect_to '/auth/cas'
+  end
+
+  def create
+    raise "Not Implemented"
+  end
+
+  def destroy
+    redirect_to ::CAS_SERVER["domain"] + '/logout'
+  end
+
+  def cas_logout
+    render :nothing => true
+  end
+
+end

data/cas_client.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "cas_client/version"
+
+Gem::Specification.new do |s|
+  s.name        = "cas_client"
+  s.version     = CASClient::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Ryan Moran"]
+  s.email       = ["ryan.moran@revolutionprep.com"]
+  s.homepage    = "http://www.revolutionprep.com"
+  s.summary     = %q{CAS client implementation}
+  s.description = %q{Helpers, controllers and middleware to implement a CAS client app}
+
+  s.rubyforge_project = "cas_client"
+  
+  s.add_dependency('oa-enterprise', '>= 0.1.6')
+  s.add_dependency('yajl-ruby')
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/config/routes.rb

@@ -0,0 +1,8 @@
+Rails.application.routes.draw do
+  get "/login",                        :to => "sessions#new",     :as => :login
+  get "/logout",                       :to => "sessions#destroy", :as => :logout
+  get "/cas_logout",                   :to => "sessions#cas_logout"
+  get "auth/cas/callback",             :to => "sessions#create"
+  get "auth/facebook_signup/callback", :to => "sessions#create"
+  get "auth/facebook_signup",                                     :as => :facebook_signup
+end

data/lib/cas_client/engine.rb

@@ -0,0 +1,28 @@
+require 'cas_client'
+require 'rails'
+require 'omniauth/enterprise'
+require 'net/https'
+require File.dirname(__FILE__) + '/user_api.rb'
+
+module CASClient
+
+  class Engine < Rails::Engine
+    engine_name :cas_client
+
+    initializer "cas_client.configure_omniauth" do |app|
+      if File.exists?(Rails.root.to_s + '/config/cas_server.yml')
+        ::CAS_SERVER = YAML::load(File.open(Rails.root.to_s + '/config/cas_server.yml'))[Rails.env]
+        OmniAuth::Strategies.autoload :FacebookSignup, 'facebook_signup'
+        app.config.middleware.use OmniAuth::Builder do
+          provider :c_a_s,           :cas_server => CAS_SERVER["domain"]
+          provider :facebook_signup, :cas_server => CAS_SERVER["domain"]
+        end
+      end
+    end
+    
+    generators do
+      require File.dirname(__FILE__) + '/../generators/install_generator.rb'
+    end
+  end
+
+end

data/lib/cas_client/errors.rb

@@ -0,0 +1,10 @@
+module CASClient
+  class UUIDNotFound < StandardError
+  end
+  
+  class MissingEmail < StandardError
+  end
+  
+  class UserAlreadyExists < StandardError
+  end
+end

data/lib/cas_client/user_api.rb

@@ -0,0 +1,172 @@
+require 'net/http'
+require 'yajl'
+
+module CASClient
+  module UserAPI
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      
+      def find_or_create_facebook_user(attribute, auth)
+        if auth['provider'] == 'facebook_signup'
+          attributes = {}
+          cas_map.invert.each_pair do |k,v|
+            attributes.store(k.to_sym, auth['extra'][v.to_s]) unless attribute.to_sym == k.to_sym
+          end
+          send(("find_or_create_by_" + attribute), auth['extra'][cas_map.invert[attribute.to_sym].to_s], attributes)
+        end
+      end
+
+      def cas_all
+        res = fetch("#{CAS_SERVER["domain"]}/api/users")
+        Yajl::Parser.new(:symbolize_keys => true).parse(res.body)
+      end
+
+      def cas_fetch_user(uuid)
+        res = fetch("#{CAS_SERVER["domain"]}/api/users/#{uuid}")
+        Yajl::Parser.new(:symbolize_keys => true).parse(res.body)
+      rescue CASClient::UUIDNotFound
+      end
+
+      def cas_uuid_available?(uuid)
+        !cas_fetch_user(uuid)
+      end
+
+      def fetch(uri_string, limit = 10)
+        raise StandardError, 'HTTP redirect too deep' if limit == 0
+        url = URI.parse(uri_string)
+        handle_response(make_request(url, Net::HTTP::Get.new(url.path)), limit)
+      end
+      private :fetch
+      
+      def make_request(url, req)
+        req.basic_auth CAS_SERVER["username"], CAS_SERVER["password"]
+        res = Net::HTTP.start(url.host, url.port) { |http| http.request(req) }
+      end
+      private :make_request
+      
+      def handle_response(res, limit = 10)
+        case res
+        when Net::HTTPSuccess
+          res
+        when Net::HTTPRedirection
+          fetch(res['location'], limit - 1)
+        when Net::HTTPNotFound
+          raise CASClient::UUIDNotFound
+        else
+          res.error!
+        end
+      end
+      private :handle_response
+      
+      def method_missing(method_sym, *arguments, &block)
+        if method_sym.to_s =~ /^find_or_create_facebook_user_by_(.*)$/
+          find_or_create_facebook_user($1, arguments.first)
+        else
+          super
+        end
+      end
+
+    end
+    
+    def cas_password=(_password)
+      @cas_password = _password
+    end
+    
+    def cas_password
+      @cas_password
+    end
+    
+    def cas_password_confirmation=(_password_confirmation)
+      @cas_password_confirmation = _password_confirmation
+    end
+    
+    def cas_password_confirmation
+      @cas_password_confirmation
+    end
+
+    def cas_create
+      url = URI.parse("#{CAS_SERVER["domain"]}/api/users")
+      res = handle_response(make_request(url, Net::HTTP::Post.new(url.path)))
+      Yajl::Parser.new(:symbolize_keys => true).parse(res.body)
+    end
+
+    def cas_update_attributes
+      if self.changes.keys.include?(self.class.cas_map[:uuid].to_s)
+        _user_identifier = self.changes[self.class.cas_map[:uuid].to_s].first
+      else
+        _user_identifier = self.send(self.class.cas_map[:uuid])
+      end
+      url = URI.parse("#{CAS_SERVER["domain"]}/api/users/#{_user_identifier}")
+      res = handle_response(make_request(url, Net::HTTP::Put.new(url.path)))
+      Yajl::Parser.new(:symbolize_keys => true).parse(res.body)
+    end
+
+    def cas_retrieve_attributes
+      res = fetch("#{CAS_SERVER["domain"]}/api/users/#{self.send(self.class.cas_map[:uuid])}")
+      Yajl::Parser.new(:symbolize_keys => true).parse(res.body)
+    end
+    
+    def cas_reset_password
+      res = fetch("#{CAS_SERVER["domain"]}/api/users/#{self.send(self.class.cas_map[:uuid])}/reset_password")
+      res.body
+    end
+
+    def fetch(uri_string, limit = 10)
+      raise StandardError, 'HTTP redirect too deep' if limit == 0
+      url = URI.parse(uri_string)
+      handle_response(make_request(url, Net::HTTP::Get.new(url.path)), limit)
+    end
+    private :fetch
+    
+    def make_request(url, req)
+      req.basic_auth CAS_SERVER["username"], CAS_SERVER["password"]
+      req.set_form_data(build_user_attributes_hash, ';') if [Net::HTTP::Post, Net::HTTP::Put].include?(req.class)
+      Net::HTTP.new(url.host, url.port).start { |http| http.request(req) }
+    end
+    private :make_request
+    
+    def handle_response(res, limit = 10)
+      case res
+      when Net::HTTPSuccess
+        res
+      when Net::HTTPRedirection
+        fetch(res['location'], limit - 1)
+      when Net::HTTPNotFound
+        raise CASClient::UUIDNotFound
+      when Net::HTTPForbidden
+        case Yajl::Parser.new(:symbolize_keys => true).parse(res.body)[:errors].first
+        when "Email is required to reset password"
+          raise CASClient::MissingEmail, "Email is required to reset password"
+        when "Uuid has already been taken"
+          raise CASClient::UserAlreadyExists, "This unique user ID has already been taken"
+        else
+          puts res.body
+          res.error!
+        end
+      else
+        res.error!
+      end
+    end
+    private :handle_response
+    
+    def build_user_attributes_hash
+      hash = {}
+      self.class.cas_map.each_pair do |k,v|
+        if value = self.send(v.to_sym)
+          hash.store(k.to_sym, value)
+        end
+      end
+      if cas_password && cas_password_confirmation
+        hash.store(:password, cas_password)
+        hash.store(:password_confirmation, cas_password_confirmation)
+      end
+      hash
+    end
+    private :build_user_attributes_hash
+
+  end
+end

data/lib/cas_client/version.rb

@@ -0,0 +1,3 @@
+module CASClient
+  VERSION = "0.1.0"
+end

data/lib/cas_client.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'bundler'
+Bundler.require
+
+if defined?(Rails) && Rails::VERSION::MAJOR == 3
+  require 'cas_client/engine'
+  require 'omniauth/strategies/facebook_signup/strategy'
+end
+require 'cas_client/errors'
+
+module CASClient
+end

data/lib/generators/install_generator.rb

@@ -0,0 +1,19 @@
+require 'rails/generators'
+
+module CASClient
+  class InstallGenerator < Rails::Generators::Base
+
+    source_root File.join(File.dirname(__FILE__), 'templates')
+
+    def manifest
+      copy_file "sessions_controller.rb", "app/controllers/sessions_controller.rb.example"
+      copy_file "cas_server.yml", "config/cas_server.yml.example"
+      copy_file "user.rb", "app/models/user.rb.example"
+    end
+    
+    def self.namespace(name = nil)
+      super.gsub("c_a_s_client", "cas_client")
+    end
+
+  end
+end

data/lib/generators/templates/cas_server.yml

@@ -0,0 +1,14 @@
+development:
+  domain: 'http://localhost:4000'
+  username: 'test'
+  password: 'password'
+
+test:
+  domain: 'http://localhost:4000'
+  username: 'test'
+  password: 'password'
+
+production:
+  domain: 'http://localhost:4000'
+  username: 'test'
+  password: 'password'

data/lib/generators/templates/sessions_controller.rb

@@ -0,0 +1,18 @@
+class SessionsController < CASClient::SessionsController
+  
+  # disable whatever authorization mechanism you have for these actions so that the server can redirect users who are not logged in
+  # skip_before_filter :authorize, :only => [:new, :create]
+
+  def create
+    # do whatever you need here to persist the users session within your app
+    # session[:uuid] = request.env['rack.auth']['uid']
+    # redirect_to '/'
+  end
+
+  def cas_logout
+    # do whatever you need here to kill a user's session
+    # session[:uuid] = nil
+    super # DO NOT REMOVE THIS
+  end
+  
+end

data/lib/generators/templates/user.rb

@@ -0,0 +1,16 @@
+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

data/lib/omniauth/strategies/facebook_signup/configuration.rb

@@ -0,0 +1,91 @@
+require 'rack'
+
+module OmniAuth
+  module Strategies
+    class FacebookSignup
+      class Configuration
+        
+        DEFAULT_LOGIN_URL = "%s/auth/facebook/prerequest"
+
+        DEFAULT_SERVICE_VALIDATE_URL = "%s/serviceValidate"
+
+        # @param [Hash] params configuration options
+        # @option params [String, nil] :cas_server the CAS server root URL; probably something like
+        #         `http://cas.mycompany.com` or `http://cas.mycompany.com/cas`; optional.
+        # @option params [String, nil] :cas_login_url (:cas_server + '/login') the URL to which to
+        #         redirect for logins; options if `:cas_server` is specified,
+        #         required otherwise.
+        # @option params [String, nil] :cas_service_validate_url (:cas_server + '/serviceValidate') the
+        #         URL to use for validating service tickets; optional if `:cas_server` is
+        #         specified, requred otherwise.
+        def initialize(params)
+          parse_params params
+        end
+
+        # Build a CAS login URL from +service+.
+        #
+        # @param [String] service the service (a.k.a. return-to) URL
+        # 
+        # @return [String] a URL like `http://cas.mycompany.com/login?service=...`
+        def login_url(service)
+          append_service @login_url, service
+        end
+
+        # Build a service-validation URL from +service+ and +ticket+.
+        # If +service+ has a ticket param, first remove it. URL-encode
+        # +service+ and add it and the +ticket+ as paraemters to the
+        # CAS serviceValidate URL.
+        #
+        # @param [String] service the service (a.k.a. return-to) URL
+        # @param [String] ticket the ticket to validate
+        #
+        # @return [String] a URL like `http://cas.mycompany.com/serviceValidate?service=...&ticket=...`
+        def service_validate_url(service, ticket)
+          service = service.sub(/[?&]ticket=[^?&]+/, '')
+          url = append_service(@service_validate_url, service)
+          url << '&ticket=' << Rack::Utils.escape(ticket)
+        end
+
+        private
+
+        def parse_params(params)
+          if params[:cas_server].nil? && params[:cas_login_url].nil?
+            raise ArgumentError.new(":cas_server or :cas_login_url MUST be provided")
+          end
+          @login_url   = params[:cas_login_url]
+          @login_url ||= DEFAULT_LOGIN_URL % params[:cas_server]
+          validate_is_url 'login URL', @login_url
+
+          if params[:cas_server].nil? && params[:cas_service_validate_url].nil?
+            raise ArgumentError.new(":cas_server or :cas_service_validate_url MUST be provided")
+          end
+          @service_validate_url   = params[:cas_service_validate_url]
+          @service_validate_url ||= DEFAULT_SERVICE_VALIDATE_URL % params[:cas_server]
+          validate_is_url 'service-validate URL', @service_validate_url
+        end
+
+        IS_NOT_URL_ERROR_MESSAGE = "%s is not a valid URL"
+
+        def validate_is_url(name, possibly_a_url)
+          url = URI.parse(possibly_a_url) rescue nil
+          raise ArgumentError.new(IS_NOT_URL_ERROR_MESSAGE % name) unless url.kind_of?(URI::HTTP)
+        end
+
+        # Adds +service+ as an URL-escaped parameter to +base+.
+        #
+        # @param [String] base the base URL
+        # @param [String] service the service (a.k.a. return-to) URL.
+        #
+        # @return [String] the new joined URL.
+        def append_service(base, service)
+          result = base.dup
+          result << '?force_create=1'
+          result << (result.include?('?') ? '&' : '?')
+          result << 'service='
+          result << Rack::Utils.escape(service)
+        end
+        
+      end
+    end
+  end
+end

data/lib/omniauth/strategies/facebook_signup/service_ticket_validator.rb

@@ -0,0 +1,80 @@
+require 'nokogiri'
+
+module OmniAuth
+  module Strategies
+    class FacebookSignup
+      class ServiceTicketValidator        
+
+        VALIDATION_REQUEST_HEADERS = { 'Accept' => '*/*' }
+
+        # Build a validator from a +configuration+, a
+        # +return_to+ URL, and a +ticket+.
+        #
+        # @param [OmniAuth::Strategies::CAS::Configuration] configuration the CAS configuration
+        # @param [String] return_to_url the URL of this CAS client service
+        # @param [String] ticket the service ticket to validate
+        def initialize(configuration, return_to_url, ticket)
+          @uri = URI.parse(configuration.service_validate_url(return_to_url, ticket))
+        end
+
+        # Request validation of the ticket from the CAS server's
+        # serviceValidate (CAS 2.0) function.
+        #
+        # Swallows all XML parsing errors (and returns +nil+ in those cases).
+        #
+        # @return [Hash, nil] a user information hash if the response is valid; +nil+ otherwise.
+        #
+        # @raise any connection errors encountered.
+        def user_info
+          parse_user_info(find_authentication_success(get_service_response_body))
+        end
+
+        private
+
+        # turns an `<cas:authenticationSuccess>` node into a Hash;
+        # returns nil if given nil
+        def parse_user_info(node)
+          return nil if node.nil?
+          node.children.inject({}) do |hash, child|
+            unless child.kind_of?(Nokogiri::XML::Text) ||
+                   child.name == 'cas:proxies' ||
+                   child.name == 'proxies'
+              hash[child.name.sub(/^cas:/, '')] = child.content
+            end
+            hash
+          end
+        end
+        
+        # finds an `<cas:authenticationSuccess>` node in
+        # a `<cas:serviceResponse>` body if present; returns nil
+        # if the passed body is nil or if there is no such node.
+        def find_authentication_success(body)
+          return nil if body.nil? || body == ''
+          begin
+            doc = Nokogiri::XML(body)
+            begin
+              doc.xpath('/cas:serviceResponse/cas:authenticationSuccess')
+            rescue Nokogiri::XML::XPath::SyntaxError
+              doc.xpath('/serviceResponse/authenticationSuccess')
+            end
+          rescue Nokogiri::XML::XPath::SyntaxError
+            nil
+          end
+        end
+        
+        # retrieves the `<cas:serviceResponse>` XML from the CAS server
+        def get_service_response_body
+          result = ''
+          http = Net::HTTP.new(@uri.host, @uri.port)
+          http.use_ssl = @uri.port == 443 || @uri.instance_of?(URI::HTTPS)
+          http.start do |c|
+            response = c.get "#{@uri.path}?#{@uri.query}", VALIDATION_REQUEST_HEADERS
+            result = response.body
+          end
+          result
+        end
+        
+      end
+    end
+  end
+end