aker 3.0.0.pre

data/lib/aker/cas/authority.rb

@@ -0,0 +1,79 @@
+require 'aker/authorities'
+
+require 'castanet'
+
+module Aker::Cas
+  ##
+  # An authority which verifies CAS tickets with an actual CAS server.
+  #
+  # @see Aker::Cas::UserExt
+  class Authority
+    include ConfigurationHelper
+    include Castanet::Client
+
+    attr_reader :configuration
+
+    ##
+    # Creates a new instance of this authority.  It reads parameters
+    # from the `:cas` parameters section of the given configuration.
+    # See {Aker::Cas::ConfigurationHelper} for information about the
+    # meanings of these parameters.
+    def initialize(configuration)
+      @configuration = configuration
+
+      unless cas_url
+        raise ":base_url parameter is required for CAS"
+      end
+    end
+
+    ##
+    # Verifies the given credentials with the CAS server.  The `:cas`
+    # and `:cas_proxy` kinds are supported.  Both kinds require two
+    # credentials in the following order:
+    #
+    # * The ticket (either a service ticket or proxy ticket)
+    # * The service URL associated with the ticket
+    #
+    # The returned user will be extended with {Aker::Cas::CasUser}.
+    #
+    # If CAS proxying is enabled, then this method also retrieves the
+    # proxy-granting ticket for the user.
+    #
+    # @see http://www.jasig.org/cas/protocol
+    #   CAS 2 protocol specification, section 2.5.4
+    # @return [Aker::User,:unsupported,nil] a user if the credentials
+    #   are valid, `:unsupported` if the kind is anything but `:cas`
+    #   or `:cas_proxy`, and nil otherwise
+    def valid_credentials?(kind, *credentials)
+      return :unsupported unless [:cas, :cas_proxy].include?(kind)
+
+      ticket = ticket_for(kind, *credentials)
+      ticket.present!
+
+      return nil unless ticket.ok?
+
+      Aker::User.new(ticket.username).tap do |u|
+        u.extend Aker::Cas::UserExt
+
+        u.cas_url = cas_url
+        u.proxy_callback_url = proxy_callback_url
+        u.proxy_retrieval_url = proxy_retrieval_url
+
+        if ticket.pgt_iou
+          ticket.retrieve_pgt!
+
+          u.pgt = ticket.pgt
+        end
+      end
+    end
+
+    private
+
+    def ticket_for(kind, ticket, service)
+      case kind
+      when :cas; service_ticket(ticket, service)
+      when :cas_proxy; proxy_ticket(ticket, service)
+      end
+    end
+  end
+end

data/lib/aker/cas/configuration_helper.rb

@@ -0,0 +1,85 @@
+require 'aker/cas'
+require 'uri'
+
+module Aker::Cas
+  ##
+  # A helper for uniform creation of derived attributes for the CAS
+  # configuration.  It expects to be mixed in to a context that
+  # provides a `configuration` method which returns a
+  # {Aker::Configuration}.
+  #
+  # @see Aker::Configuration
+  module ConfigurationHelper
+    ##
+    # The login URL on the CAS server.  This may be set explicitly
+    # in the configuration as `parameters_for(:cas)[:login_url]`.  If
+    # not set explicitly, it will be derived from the base URL.
+    #
+    # @return [String]
+    def cas_login_url
+      configuration.parameters_for(:cas)[:login_url] || URI.join(cas_url, 'login').to_s
+    end
+
+    ##
+    # The logout URL on the CAS server.  This may be set explicitly
+    # in the configuration as `parameters_for(:cas)[:logout_url]`.  If
+    # not set explicitly, it will be derived from the base URL.
+    #
+    # @return [String]
+    def cas_logout_url
+      configuration.parameters_for(:cas)[:logout_url] || URI.join(cas_url, 'logout').to_s
+    end
+
+    ##
+    # The base URL for all not-otherwise-explicitly-specified URLs on
+    # the CAS server.  It may be set in the CAS parameters as either
+    # `:base_url` (preferred) or `:cas_base_url` (for backwards
+    # compatibility with aker 1.x).
+    #
+    # The base URL should end in a `/` (forward slash).  If it does not, a
+    # trailing forward slash will be appended.
+    #
+    # @see http://www.ietf.org/rfc/rfc1808.txt
+    #   RFC 1808, sections 4 and 5
+    # @return [String, nil]
+    def cas_url
+      appending_forward_slash do
+        configuration.parameters_for(:cas)[:base_url] ||
+          configuration.parameters_for(:cas)[:cas_base_url]
+      end
+    end
+
+    ##
+    # The URL that CAS will provide the PGT and PGTIOU to, per section
+    # 2.5.4 of the spec.  Some CAS servers require that this be an
+    # SSL-protected resource.  It is set in the CAS parameters as
+    # `:proxy_callback_url`.
+    #
+    # @return [String, nil]
+    def proxy_callback_url
+      configuration.parameters_for(:cas)[:proxy_callback_url]
+    end
+
+    ##
+    # The URL that the CAS client can retrieve the PGT from once it
+    # has been deposited at the {#proxy_callback_url} by the CAS
+    # server.  It is set in the CAS parameters as
+    # `:proxy_retrieval_url`.
+    #
+    # (Note that this is not part of the CAS protocol — it is
+    # client-specific.)
+    #
+    # @return [String, nil]
+    def proxy_retrieval_url
+      configuration.parameters_for(:cas)[:proxy_retrieval_url]
+    end
+
+    private
+
+    def appending_forward_slash
+      url = yield
+
+      (url && url[-1].chr != '/') ? url + '/' : url
+    end
+  end
+end

data/lib/aker/cas/middleware/logout_responder.rb

@@ -0,0 +1,49 @@
+require 'aker'
+
+module Aker::Cas::Middleware
+  class LogoutResponder
+    include Aker::Rack::ConfigurationHelper
+
+    ##
+    # @param app a Rack app
+    # @param [String] cas_logout_url the CAS logout URL
+    def initialize(app)
+      @app = app
+    end
+
+    ##
+    # Rack entry point.
+    #
+    # Given a `GET` to the configured logout path, redirects to
+    # {#cas_logout_url}.  All other requests are passed through.
+    #
+    # @see http://www.jasig.org/cas/protocol
+    #      Section 2.3 of the CAS 2 protocol
+    def call(env)
+      if env['REQUEST_METHOD'] == 'GET' && env['PATH_INFO'] == logout_path(env)
+        ::Rack::Response.new { |r| r.redirect(cas_logout_url(env)) }.finish
+      else
+        @app.call(env)
+      end
+    end
+
+    private
+
+    def cas_logout_url(env)
+      configuration(env).parameters_for(:cas)[:logout_url] || URI.join(cas_url(env), 'logout').to_s
+    end
+
+    def cas_url(env)
+      appending_forward_slash do
+        configuration(env).parameters_for(:cas)[:base_url] ||
+          configuration(env).parameters_for(:cas)[:cas_base_url]
+      end
+    end
+
+    def appending_forward_slash
+      url = yield
+
+      (url && url[-1].chr != '/') ? url + '/' : url
+    end
+  end
+end

data/lib/aker/cas/middleware/ticket_remover.rb

@@ -0,0 +1,35 @@
+require 'aker'
+
+module Aker::Cas::Middleware
+  ##
+  # Middleware which issues a redirect immediately after CAS
+  # authentication succeeds so that users never see a URL with the
+  # ticket in it. This prevents them from, e.g., bookmarking a URL
+  # with a ticket in it, keeping things cleaner and preventing
+  # requests to the CAS server for tickets which are definitely
+  # expired.
+  class TicketRemover
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      if authenticated?(env) && ticket_present?(env)
+        url = Aker::Cas::ServiceUrl.service_url(Rack::Request.new(env))
+        [301, { 'Location' => url }, ["Removing authenticated CAS ticket"] ]
+      else
+        @app.call(env)
+      end
+    end
+
+    private
+
+    def authenticated?(env)
+      env['aker.check'] && env['aker.check'].user
+    end
+
+    def ticket_present?(env)
+      env['QUERY_STRING'] =~ /ticket=/
+    end
+  end
+end

data/lib/aker/cas/middleware.rb

@@ -0,0 +1,6 @@
+require 'aker'
+
+module Aker::Cas::Middleware
+  autoload :LogoutResponder, 'aker/cas/middleware/logout_responder'
+  autoload :TicketRemover,   'aker/cas/middleware/ticket_remover'
+end

data/lib/aker/cas/proxy_mode.rb

@@ -0,0 +1,108 @@
+require 'aker'
+
+module Aker
+  module Cas
+    ##
+    # A non-interactive mode that provides CAS proxy authentication conformant to
+    # CAS 2.
+    #
+    # This mode does _not_ handle interactive CAS authentication; see {Cas} for
+    # that.
+    #
+    # @see http://www.jasig.org/cas/protocol
+    #      CAS 2 protocol specification
+    #
+    # @author David Yip
+    class ProxyMode < Aker::Modes::Base
+      include Aker::Modes::Support::Rfc2617
+
+      ##
+      # A key that refers to this mode; used for configuration convenience.
+      #
+      # @return [Symbol]
+      def self.key
+        :cas_proxy
+      end
+
+      ##
+      # The type of credentials supplied by this mode.
+      #
+      # @return [Symbol]
+      def kind
+        self.class.key
+      end
+
+      ##
+      # The supplied proxy ticket and the {#service_url service URL}.
+      #
+      # The proxy ticket is received in the HTTP `Authorization`
+      # header, per RFC2616.  The scheme must be `CasProxy`.  Example:
+      #
+      # > `Authorization: CasProxy PT-1272928074r13CBB9ACA794867F3E`
+      #
+      # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol, section 3.7
+      # @return [Array<String>] the proxy ticket or an empty array
+      def credentials
+        key = 'HTTP_AUTHORIZATION'
+        matches = env[key].match(/CasProxy\s+([SP]T-[0-9A-Za-z\-]+)/) if env.has_key?(key)
+
+        if matches && matches[1]
+          [matches[1], service_url]
+        else
+          []
+        end
+      end
+
+      ##
+      # Returns true if a proxy ticket is present, false otherwise.
+      def valid?
+        !credentials.empty?
+      end
+
+      ##
+      # Used to build a WWW-Authenticate header that will be returned to a
+      # client failing non-interactive authentication.
+      #
+      # @return [String]
+      def scheme
+        "CasProxy"
+      end
+
+      ##
+      # Builds the service URL for this application.
+      #
+      # Colloquially, the service URL is the web server URL plus the
+      # application mount point.  It does not include anything
+      # about the specific resource being requested.  For instance, if
+      # you had the resource
+      #
+      # > https://notis.nubic.northwestern.edu/lsdb/patients/105661
+      #
+      # which was part of the `/lsdb` application, the service URL
+      # would be
+      #
+      # > https://notis.nubic.northwestern.edu/lsdb
+      #
+      # A little more formally, the URL is `url scheme +
+      # hostname + script name`.  The port is also included if it is
+      # not the default for the URL scheme.
+      #
+      # The service URL never ends with a `/`, even if the application
+      # is mounted at the root.
+      #
+      # @return [String] the service URL derived from the request
+      #   environment
+      def service_url
+        url = "#{env['rack.url_scheme']}://"
+        if env['HTTP_HOST']
+          url << env['HTTP_HOST'] # includes the port
+        else
+          url << env['SERVER_NAME']
+          default_port = { "http" => "80", "https" => "443" }[env['rack.url_scheme']]
+          url << ":#{env["SERVER_PORT"]}" unless env["SERVER_PORT"].to_s == default_port
+        end
+        url << env["SCRIPT_NAME"]
+      end
+    end
+  end
+end

data/lib/aker/cas/rack_proxy_callback.rb

@@ -0,0 +1,188 @@
+require 'aker/cas'
+require 'pstore'
+require 'tmpdir'
+
+module Aker::Cas
+  ##
+  # Rack code for handling the PGT callback part of the CAS proxy
+  # authentication protocol.  The class itself is middleware; it can
+  # also generate an {.application endpoint}.
+  #
+  # ## Behavior
+  #
+  # As middleware, this class intercepts and handles two paths and
+  # passes all other requests down the chain.  The paths are:
+  #
+  # * `/receive_pgt`: implements the PGT callback process per section
+  #   2.5.4 of the CAS protocol.
+  # * `/retrieve_pgt`: allows an application to retrieve the PGT for
+  #   a PGTIOU.  The PGTIOU is returned to the application as part of
+  #   the CAS ticket validation process.  It should be passed to
+  #   `/receive_pgt` as the `pgtIou` query parameter.  Note that a
+  #   given PGT may only be retrieved once.
+  #
+  # As a full rack app, it handles the same two paths and returns `404
+  # Not Found` for all other requests.
+  #
+  # ## Middleware vs. Application
+  #
+  # It is **only** appropriate to use the class as middleware in a
+  # **multithreaded or multiprocessing deployment**.  If your application
+  # only has one executor at a time, using this class as middleware
+  # **will cause a deadlock** during CAS authentication.
+  #
+  # ## Based on
+  #
+  # This class was heavily influenced by `CasProxyCallbackController`
+  # in rubycas-client.  That class has approximately the same
+  # behavior, but is Rails-specific.
+  #
+  # @see http://www.jasig.org/cas/protocol
+  #      CAS protocol, section 2.5.4
+  class RackProxyCallback
+    RETRIEVE_PATH = "/retrieve_pgt"
+    RECEIVE_PATH = "/receive_pgt"
+
+    ##
+    # Create a new instance of the middleware.
+    #
+    # @param [#call] app the next rack application in the chain.
+    # @param [Hash] options
+    # @option options [String] :store the file where the middleware
+    #   will store the received PGTs until they are retrieved.
+    def initialize(app, options={})
+      @app = app
+      @store_filename = options.delete(:store) or
+        raise "Please specify a filename for the PGT store"
+    end
+
+    ##
+    # Handles a single request in the manner specified in the class
+    # overview.
+    #
+    # @param [Hash] env the rack environment for the request.
+    #
+    # @return [Array] an appropriate rack response.
+    def call(env)
+      return receive(env) if env["PATH_INFO"] == RECEIVE_PATH
+      return retrieve(env) if env["PATH_INFO"] == RETRIEVE_PATH
+      @app.call(env)
+    end
+
+    ##
+    # Creates a rack application which responds as described in the
+    # class overview.
+    #
+    # @param [Hash] options the same options that you can pass to
+    #   {#initialize}.
+    #
+    # @return [#call] a full rack application
+    def self.application(options={})
+      app = lambda { |env|
+        [404, { "Content-Type" => "text/plain" }, ["Unknown resource #{env['PATH_INFO']}"]]
+      }
+      RackProxyCallback.new(app, options)
+    end
+
+    protected
+
+    ##
+    # Associates the given PGTIOU and PGT.
+    #
+    # @param [String] pgt_iou
+    # @param [String] pgt
+    #
+    # @return [void]
+    def store_iou(pgt_iou, pgt)
+      pstore = open_pstore
+
+      pstore.transaction do
+        pstore[pgt_iou] = pgt
+      end
+    end
+
+    ##
+    # Finds the PGT for the given PGTIOU.  If there isn't one, it
+    # returns nil.  If there is one, it deletes it from the store
+    # before returning it.
+    #
+    # @param [String] pgt_iou
+    # @return [String,nil]
+    def resolve_iou(pgt_iou)
+      pstore = open_pstore
+
+      pgt = nil
+      pstore.transaction do
+        pgt = pstore[pgt_iou]
+        pstore.delete(pgt_iou) if pgt
+      end
+
+      pgt
+    end
+
+    private
+
+    def receive(env)
+      req = Rack::Request.new(env)
+      resp = Rack::Response.new
+      resp.headers["Content-Type"] = "text/plain"
+
+      pgt = req.params["pgtId"]
+      pgt_iou = req.params["pgtIou"]
+
+      unless pgt && pgt_iou
+        missing = [("pgtId" unless pgt), ("pgtIou" unless pgt_iou)].compact
+        missing_msg =
+          if missing.size == 1
+            "#{missing.first} is a required query parameter."
+          else
+            "Both #{missing.join(' and ')} are required query parameters."
+          end
+        resp.status =
+          if missing.size == 2
+            #
+            # This oddity is required by the JA-SIG CAS Server.
+            #
+            200
+          else
+            400
+          end
+
+        resp.body = ["#{missing_msg}\nSee section 2.5.4 of the CAS protocol specification."]
+      else
+        store_iou(pgt_iou, pgt)
+
+        resp.body = ["PGT and PGTIOU received.  Thanks, my robotic friend."]
+      end
+
+      resp.finish
+    end
+
+    def retrieve(env)
+      req = Rack::Request.new(env)
+      resp = Rack::Response.new
+      resp.headers["Content-Type"] = "text/plain"
+
+      pgt_iou = req.params["pgtIou"]
+
+      if pgt_iou
+        pgt = resolve_iou(pgt_iou)
+        if pgt
+          resp.body = [pgt]
+        else
+          resp.status = 404
+          resp.body = ["pgtIou=#{pgt_iou} does not exist.  Perhaps it has already been retrieved."]
+        end
+      else
+        resp.status = 400
+        resp.body = ["pgtIou is a required query parameter."]
+      end
+
+      resp.finish
+    end
+
+    def open_pstore
+      PStore.new(@store_filename)
+    end
+  end
+end

data/lib/aker/cas/service_mode.rb

@@ -0,0 +1,88 @@
+require 'aker'
+require 'rack'
+
+module Aker
+  module Cas
+    ##
+    # An interactive mode that provides CAS authentication conformant to CAS 2.
+    #
+    # This mode does _not_ handle non-interactive CAS proxying.  See
+    # {ProxyMode} for that.
+    #
+    # @see http://www.jasig.org/cas/protocol
+    #      CAS 2 protocol specification
+    #
+    # @author David Yip
+    class ServiceMode < Aker::Modes::Base
+      include ConfigurationHelper
+      include ::Rack::Utils
+      include Aker::Modes::Support::AttemptedPath
+      include ServiceUrl
+
+      ##
+      # A key that refers to this mode; used for configuration convenience.
+      #
+      # @return [Symbol]
+      def self.key
+        :cas
+      end
+
+      ##
+      # Appends the {Middleware::LogoutResponder logout responder} and
+      # the {Middleware::TicketRemover ticket remover} to the Rack
+      # middleware stack.
+      def self.append_middleware(builder)
+        builder.use(Middleware::LogoutResponder)
+        builder.use(Middleware::TicketRemover)
+      end
+
+      ##
+      # The type of credentials supplied by this mode.
+      #
+      # @return [Symbol]
+      def kind
+        self.class.key
+      end
+
+      ##
+      # Extracts the service ticket from the request parameters.
+      #
+      # The service ticket is assumed to be a parameter named ST in either GET
+      # or POST data.
+      #
+      # @return [Array<String>,nil] a two-item array containing the
+      #   service ticket and the service URL to which the ticket
+      #   (it is asserted) applies
+      def credentials
+        if request['ticket']
+          [request['ticket'], service_url]
+        end
+      end
+
+      ##
+      # Returns true if a service ticket is present in the query string, false
+      # otherwise.
+      def valid?
+        credentials
+      end
+
+      ##
+      # Builds a Rack response that redirects to a CAS server's login page.
+      #
+      # The constructed response uses the URL of the resource for which
+      # authentication failed as the CAS service URL.
+      #
+      # @see http://www.jasig.org/cas/protocol
+      #      Section 2.2.1 of the CAS 2 protocol
+      #
+      # @return [Rack::Response]
+      def on_ui_failure
+        ::Rack::Response.new do |resp|
+          login_uri = URI.parse(cas_login_url)
+          login_uri.query = "service=#{escape(service_url)}"
+          resp.redirect(login_uri.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/aker/cas/service_url.rb

@@ -0,0 +1,62 @@
+require 'aker/cas'
+
+module Aker::Cas
+  ##
+  # Provides logic for reconstructing the full requested URL from a
+  # rack request.
+  #
+  # If used as a mixin, the host class must have a `#request`
+  # accessor. It may optionally also have a `#attempted_path`
+  # accessor.
+  #
+  # @see ServiceMode
+  # @see Aker::Modes::Support::AttemptedPath
+  module ServiceUrl
+    ##
+    # The service URL supplied to the CAS login page.  This is the
+    # requested URL, sans any service ticket.
+    #
+    # @return [String]
+    def service_url
+      ServiceUrl.service_url(
+        request,
+        (attempted_path if self.respond_to?(:attempted_path))
+      )
+    end
+
+    ##
+    # Builds the service URL that should be used for the given
+    # request. This is the requested URL (or the attempted_path, if
+    # given), sans any service ticket.
+    #
+    # @param [Rack::Request] request
+    # @param [String] attempted_path
+    # @return [String]
+    def self.service_url(request, attempted_path=nil)
+      requested = URI.parse(
+        if attempted_path
+          url = "#{request.scheme}://#{request.host}"
+
+          unless [ ["https", 443], ["http", 80] ].include?([request.scheme, request.port])
+            url << ":#{request.port}"
+          end
+
+          url << attempted_path
+        else
+          request.url
+        end
+                           )
+      if requested.query
+        requested.query.gsub!(/(&?)ticket=ST-[^&]+(&?)/) do
+          if [$1, $2].uniq == ['&'] # in the middle
+            '&'
+          else
+            nil
+          end
+        end
+        requested.query = nil if requested.query.empty?
+      end
+      requested.to_s
+    end
+  end
+end