rack-cas-rails 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b0818a3cce11d21fc1c56fe4b1e70fefbb52c1cc
-  data.tar.gz: bad76f891b70a7c54228b4e6001623f6a5e7caef
+  metadata.gz: b7d484d2b59603bbedf3a28c4917a463edf86c08
+  data.tar.gz: 7bbe3d6ae9fdbf53eef3fcb523c1d019d1afe1f1
 SHA512:
-  metadata.gz: 6549563c5255ef7d4864b66566774744dd58ef2e104f3620325599fb4cd720e625b9fe6fe5d0ef6e36a85c1f85de7fe34abf70eaae2ae5b2a2073f8b116d17f2
-  data.tar.gz: 79dd96b5624f71039b3facbfe1aed8bb39c7b9898a827345f753211e8aee422fb1a590ffb913e289cd17bdecb1b598cb71e06a6be6365c4c1a6fa31ba93fef4d
+  metadata.gz: 26517014d8fc90148db433d49e79084aa83fb2d7697174e1e9b201b5d98eae5d2e04ce784b659eb68a2d3fecf860241aa57e4aca33d2d1fd30c2d6d7f7c7ccbf
+  data.tar.gz: 2413da86e88601ae8995cb1813b4d429a8c3f1dfa0ae9b0f836d5e95240c9e34b1d48ee7a80d454cd2a1161be6586eb2971e8fce19da26e3847e6cd4dd1e2c24

data/README.md

@@ -1,104 +1,223 @@
 # rack-cas-rails
 
-While [rbCAS/CASinoApp](http://rbcas.com) and [biola/rack-cas](https://github.com/biola/rack-cas) are both great
-and wonderful, there is gap between them.  Namely, the bits needed to enable a Rails application to use rack-cas to integrate with
-CASinoApp for authentication are still missing.
+[rbCAS/CASinoApp](https://github.com/rbcas/casinoapp) is a great single sign-on authentication server, and
+[biola/rack-cas](https://github.com/biola/rack-cas) provides a simple means to integrate with it.  However, these two things
+coupled with your Rails application do not a **single sign-on enabled application** make.  That is, there are still some bits
+missing.
 
-This gem aims to fill in this void.
+This gem aims to provide some of the bits to close the gap.
 
 ## Installation
 
-Add the following line to a Rails application's Gemfile:
+Add the following to your Rails application's Gemfile:
 
 ```ruby
 gem "rack-cas-rails"
 ```
 
-Then open up your config/application.rb file, and add the following:
+Then run
+
+```ruby
+bundle install
+```
 
 ## Requirements
 
 The rack-cas-rails gem relies on the following:
 
-  * A CAS-compliant server, such as [CASinoApp](http://rbcas.com)
+  * A working installation of [CASinoApp](http://rbcas.com), although theoretically it should work with any CAS-compliant server
   * [rack-cas](https://github.com/biola/rack-cas)
   * [rails](http://rubyonrails.org/)
 
+Having access to a working CAS-compliant server is a pre-requisite.  [CASinoApp](http://rbcas.com) is a simple one to set up and
+use, especially if you go with the ***directly on your server*** option.  Whiichever CAS server you go with, you'll need to
+know the password of at least one login for testing purposes.
+
+### Disclaimer
+
+I don't have access to any other CAS servers except an instance of CASinoApp I have installed and configured.  So I have
+only ever developed and tested against it.  If you are able to try it against others, please let me know how well it works.
+
 ## Basic Usage
 
-The first thing you need to do is to make your Application class (file ```config/application.rb```) aware of the CAS-compliant
-server you are integrating with by pointing out its base URL, like so:
+Now that you have access to a functioning CAS-compliant server, the next thing you need to do is to make your ```Rails::Application```
+subclass aware of the server you are integrating with by pointing out its base URL, as shown here.
+
+Note that setting the ```@cas_server_url``` variable is important as the ```login_url``` helper will make use of it.
 
 ```ruby
+# config/application.rb
+
+require "rack-cas"
 module MyGreatApplication
   class Application < Rails::Application
     # ...
-    # URL of CAS server
-    config.rack_cas.server_url = "https://sso.example.org/"
+    # Root URL of the CAS server
+    @cas_server_url = "https://sso.example.org/"
+    config.rack_cas.server_url = @cas_server_url
   end
 end
 ```
 
-In the simplest scenario, you'll want your entire application protected by authentication.  That is, unless a user has authenticated,
-he can do nothing.  To do so, add the following ```before_action``` callback to your ApplicationController
-(file ```app/controllers/application_ronctoller.rb```):
+In the simplest case, you'll want your entire application protected by authentication.  That is, unless a user has authenticated,
+he can do nothing.  To do so, add the following ```before_action``` callback to your ```ApplicationController```:
 
 ```ruby
+# app/controllers/application_ronctoller.rb
+
+require "rack_cas_rails"
 class ApplicationController < ActionController::Base
-  # authenticate all actions for all controllers
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
   before_action :authenticate!
-  # ...
 end
 ```
 
-The ```authenticate!``` method will check to see if a browser session is authenticated.  If it is, controller execution will continue.
-Otherwise, it will render the ```public/401.html``` file as well as return a HTTP status of 401.
+The ```authenticate!``` helper will check to see if a browser session is authenticated.  If it is, controller execution will continue.
+Otherwise, it will render the ```public/401.html``` file if one exists, as well as return a HTTP status of 401.
 
-So, now, create a ```pubilc/401.html``` file in your application.   You can simply copy an existing file, rename and change its
-contents.
+At this point, if you fire up your application and browse to access any view of any controller subclassed from
+```ApplicationController```, the browser will get re-directed to the CAS server's log-in page.
 
 ## Helper Methods
 
-The rack-cas-rails gem also augments the ApplicationHelper module with these methods:
+The rack-cas-rails gem also adds some helper methods:
+
+* authenticate!
+* authenticated?
+* login_url
+* logout_url
+
+You have already seen ```authenticate!``` at work.  The ```authenticated?``` helper allows your application to determine whether
+a browser is authenticated or not and take appropriate action.  When invoked, the latter two helpers will return the
+CAS-integrated login and log out URLs, respectively.  They, in turn, enable you to implement *partial authentication*.
+
+## Partial Authentication
 
-  * login_url
-  * logout_url
+In this case, only certain portions of your application requires authentication.  For example, perhaps actions that are
+*read-only* need not be protected by authentication.  To do this, change your ```ApplicationController``` as follows:
+
+```ruby
+# app/controllers/application_ronctoller.rb
+
+require "rack_cas_rails"
+class ApplicationController < ActionController::Base
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
+  before_action :authenticate!, except: [:index, :show]
+end
+```
+
+Restart your application and browse to a *read-only* endpoint like ```/index``` or ```/show```, and you will not be re-directed
+to the CAS log-in page.  But if you browse to other endpoints like ```/new```, you will be re-directed and prompted to
+authenticate.
+
+Go back and look at the read-only endpoint.  It would be nice to have some indication telling a user whether he's logged in or not.
+So, open up your application layout and add a ```<div>``` container that will behave differently bepending on the authentication
+status of a browser session.
+
+```erb
+<!-- views/layouts/application.html.erb -->
+
+<!DOCTYPE html>
+<html>
+<head>
+  <title>MyGreatApplication</title>
+  <%= stylesheet_link_tag    'application', media: 'all', 'data-turbolinks-track' => true %>
+  <%= javascript_include_tag 'application', 'data-turbolinks-track' => true %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+  <div id="header">
+    <% if authenticated? %>
+      <span>You are logged in.</span>
+      <span style="float:right"><%= link_to "Logout", logout_url %></span>
+    <% else %>
+      <span>You are not logged in.</span>
+      <span style="float:right"><%= link_to "Login", login_url %></span>
+    <% end %>
+  </div>
+  <hr />
+  <div>
+    <%= yield %>
+  </div>
+</body>
+</html>
+```
 
-When invoked, these helpers will renturn the CAS-integrated login in and log out URLs, respectively.
+Refresh your browser.  This time you'll see that you're not logged in, but you are also given a login URL.  Click on it, and you'll
+be prompted to log-in once again.
 
 ## What Is Still Missing
 
-Even with the rack-cas and rack-cas-rails gems, the aforementioned basic authentication scheme is still incomplete.  Namely, for an
-authenticated session, which user does it belong to?
+However, the basic authentication scheme we have cooked up is still incomplete.  Namely:
+
+* What credentails should a user use to login, and how does your application verify it?
+* Once a user has authenticated, how does your application know about that user?
+
+The first point is that your application doesn't have to worry about it, since that is the whole point of CAS (and single sign-on).
+Once your CAS server is set up, any application you write and integrate with it won't have to worry about it.  Your CAS
+server will take care of it for you.
+
+The second point, however,requires some explanation and experimentation...
 
-Various Rails authentication gems makes the currently authenticated user available as an object via the ```current_user``` helper
-method.  The rack-cas-rails gem does not provide this functionality.  But you can look to gems such as
-[OmniAuth](https://github.com/intridea/omniauth), [Devise](https://github.com/plataformatec/devise),
-[Authlogic](https://github.com/binarylogic/authlogic) and so on to provide it.
+Once a user has authenticated, the [rack-cas](https://github.com/biola/rack-cas) gem will insert some information about
+that user into your application's session for it to retrieve.  Your application should then take this information, usually
+in the form of a username, and look up information about that user.  Based on the information available, your application can
+then implement additional features such as authorziation (not covered here).
 
-But, assuming your application has a ActiveRecord model named ```User``` where its accmpanying database table containing user records
-which are uniquely identifiable by a ```username``` attribute, you can add the following code to your ApplictionController to
-provide your application with the ```current_user``` method:
+Ideally, your application should use the same data repository as your CAS server to look up user information.  That repository can
+be a SQL database table, some LDAP server, or any number of things.  But for now, we can fake it.
+
+Go ahead and create a scaffold around a Person model (or any other name you'd like to use), like so:
+
+```
+$ rails generate scaffold person name:string age:integer
+$ rake db:migrate
+```
+
+Populate the ```people``` table with at least one row where the ```name``` column has the same value as one of the users your CAS
+server knows about and you know the password of.  For example, let's use "jsmith":
+
+```
+$ rails console
+Loading development environment (Rails 4.2.0)
+2.2.0 :001 > person = Person.new(name: "jsmith", age: 123)
+ => #<Person id: nil, name: "jsmith", age: 123, created_at: nil, updated_at: nil> 
+2.2.0 :002 > person.save!
+   (0.2ms)  begin transaction
+  SQL (33.5ms)  INSERT INTO "people" ("name", "age", "created_at", "updated_at") VALUES (?, ?, ?, ?)  [["name", "jsmith"],
+  ["age", 123], ["created_at", "2015-02-16 02:27:18.121111"], ["updated_at", "2015-02-16 02:27:18.121111"]]
+   (1.5ms)  commit transaction
+ => true 
+2.2.0 :003 > quit
+```
+
+Now, let's add a helper named ```current_user``` (or any other name you like) to your application:
 
 ```ruby
-class ApplicationController
+# app/controllers/application_ronctoller.rb
 
-  # ...
-  
+require "rack_cas_rails"
+class ApplicationController < ActionController::Base
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
+  before_action :authenticate!, except: [:index, :show]
   def current_user
-    authenciated? ? User.find_by_login(request.session["cas"]["user"]) : nil
+    authenticated? ? Person.find_by_name(request.session["cas"]["user"]) : nil
   end
-
   helper_method :current_user
-
 end
 ```
 
-*Note the user records should be the same ones available to CASinoApp for authentication.*
-
-Lastly, change your ```views/layouts/application.html.erb``` to be as follows:
+Next, change your layout to be as follows:
 
 ```erb
+<!-- views/layouts/application.html.erb -->
+
 <!DOCTYPE html>
 <html>
 <head>
@@ -108,12 +227,13 @@ Lastly, change your ```views/layouts/application.html.erb``` to be as follows:
   <%= csrf_meta_tags %>
 </head>
 <body>
-  <divi id="nav-header">
+  <div id="header">
     <% if authenticated? %>
-      <span>Logged in as <%= current_user.username %>.</span>
+      <span>You are logged in as <%= current_user.name %>.</span>
       <span style="float:right"><%= link_to "Logout", logout_url %></span>
     <% else %>
-      <span><%= link_to "Login", login_url %></span>
+      <span>You are not logged in.</span>
+      <span style="float:right"><%= link_to "Login", login_url %></span>
     <% end %>
   </div>
   <hr />
@@ -124,20 +244,27 @@ Lastly, change your ```views/layouts/application.html.erb``` to be as follows:
 </html>
 ```
 
+Restart your application again, and visit an ```/index``` endpoint.  Click the __Login__ link, and authenticate using "jsmith"
+(or whichever user you chose) and the correct password.  Once authenticated, you'll be re-directed back to the original page.
+This time, you are shown whom you are logged in as.  Now visit a ```/new``` endpoint, and you won't be prompted to authenticate
+again, until you click the __Logout__ link or restart your browser.
+
 ## Summary
 
-To recap, you'll have integrated your Rails application with a CAS-compliant server by making these changes to your application:
+With rack-cas-rails, you can integrate your Rails application with CASinoApp or another CAS-compliant server for
+authentication by making these changes in it:
 
-  1. Add ```config.rack_cas.server_url``` to config/application.rb
-  2. Add ```before_action :authenticate!``` to ApplicationController
-  3. Add ```current_user``` method to ApplictionController
-  4. Add simple navigational header to make use of ```current_user``` and the ```login_url```/```logout_url``` helpers
+1. Your Rails::Application subclass (in config/application.rb)
+2. Your ApplicationController class (in app/controllers/application_controller.rb)
+3. Your layout template (in app/views/layouts/application.html.erb)
+4. Add a model (or some other means) by which you can retrieve information about the currently logged in user
 
-As such, you can expect the following behavior:
+With these changes in place, you can expect your application to exhibit the following behavior:
 
-  * When you browse to any view within your application using a fresh session, you'll be re-directed to the sign-in page
-  * After you authenticate, you'll be re-directed back to the page you browsed to
-  * When you click the Logout link, your session will end, and the browser will be re-directed back to the login page
+* When you browse to any protected endpoint within your application using a fresh session, you'll be re-directed to the sign-in page
+* After you authenticate, you'll be re-directed back to the page you browsed to, after which you'll have access to all endpoints
+* When you click the __Logout__ link or restart your browser, your session will end; and should you now attempt to access
+  a protected enpoint, you'll be prompted to log in once again
 
 ## Credits
 

data/lib/rack_cas_rails/application.rb

@@ -0,0 +1,22 @@
+##
+# Augments the Rails application class.
+
+class Rails::Application < Rails::Engine
+
+  ##
+  # Gives the Rails::Application class a read-only class attribute to point to the CAS server URL.  The URL in turn is then
+  # settable using @cas_server_url at the class level.
+
+  class << self
+    attr_reader :cas_server_url
+  end
+
+  ##
+  # Gets the CAS server root URL.  Provides a convenience method at the instance level to fetch it.
+  # @return [String] Cas server's root URL.
+
+  def cas_server_url
+    self.class.cas_server_url
+  end
+
+end

data/lib/{rack-cas-rails → rack_cas_rails}/controllers.rb

@@ -10,7 +10,12 @@ class ApplicationController < ActionController::Base
   # When invoked, will force authenticate.  Most likely to be invoked as a before_action.
 
   def authenticate!
-    authenticated? or render(:file => "public/401.html", :status => :unauthorized) # HTTP 401
+    return if authenticated?
+    if File.exists?("public/401.html")
+      render(:file => "public/401.html", :status => :unauthorized)
+    else
+      render(:plain => "Unauthorized!", :status => :unauthorized)
+    end
   end
 
   ##
@@ -27,7 +32,7 @@ class ApplicationController < ActionController::Base
   # @return [String] The CAS login URL.
 
   def login_url(service_url=request.url)
-    url = URI(Rails.application.config.rack_cas.server_url)
+    url = URI(Rails.application.cas_server_url)
     url.path = "/login"
     url.query = "service=#{service_url || request.url}"
     url.to_s

data/lib/{rack-cas-rails → rack_cas_rails}/version.rb

@@ -1,3 +1,3 @@
 module RackCASRails
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/rack_cas_rails.rb

@@ -0,0 +1,3 @@
+require "rack_cas_rails/application"
+require "rack_cas_rails/controllers"
+require "rack_cas_rails/version"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack-cas-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Nathan Brazil
@@ -44,6 +44,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 4.2.0
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provides the integration glue between a Rails application and biola/rack-cas
   so that a CAS-compliant server (only tested with CASinoApp) can be used for authentication
   by the application.
@@ -54,9 +96,10 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- lib/rack-cas-rails.rb
-- lib/rack-cas-rails/controllers.rb
-- lib/rack-cas-rails/version.rb
+- lib/rack_cas_rails.rb
+- lib/rack_cas_rails/application.rb
+- lib/rack_cas_rails/controllers.rb
+- lib/rack_cas_rails/version.rb
 homepage: https://github.com/bitaxis/rack-cas-rails.git
 licenses:
 - MIT

data/lib/rack-cas-rails.rb

@@ -1 +0,0 @@
-require "rack-cas-rails/controllers"