castanet 0.0.1

data/History.md

@@ -0,0 +1,4 @@
+0.0.1 (unreleased)
+==================
+
+- Initial release.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 David Yip
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+Castanet: a small, snappy CAS client library
+============================================
+
+Castanet is a [Central Authentication Service](http://www.jasig.org/cas) (CAS)
+client library.  It implements version 2.0 of the CAS protocol.
+
+Castanet was built at the [Northwestern University Biomedical Informatics
+Center](http://www.nucats.northwestern.edu/clinical-research-resources/data-collection-biomedical-informatics-and-nubic/bioinformatics-overview.html)
+as a replacement for [RubyCAS-Client](https://github.com/gunark/rubycas-client)
+in internal software.
+
+Castanet is tested on Ruby 1.8.7, Ruby 1.9.2, JRuby 1.5.6 in Ruby 1.8 mode, and Rubinius 1.2.0.
+Continuous integration reports are available at [NUBIC's CI
+server](https://ctms-ci.nubic.northwestern.edu/hudson/job/castanet/).
+
+Getting started
+===============
+
+Mix `Castanet::Client` into the objects that need CAS client behavior.
+
+Objects that include `Castanet::Client` must implement `cas_url`,
+`proxy_callback_url`, and `proxy_retrieval_url`.
+
+See the documentation for `Castanet::Client` for more information and usage
+examples.
+
+Acknowledgments
+===============
+
+Castanet's test harness was based off of code originally written by [Rhett
+Sutphin](mailto:rhett@detailedbalance.net).
+
+Query string building code was taken from [Rack](http://rack.rubyforge.org/).
+
+Development
+===========
+
+Castanet uses [Bundler](http://gembundler.com/) version `~> 1.0` for dependency
+management.
+
+Some of Castanet's development dependencies work best in certain versions of
+Ruby.  Additionally, some implementations of Ruby do not support constructs
+(i.e. `fork`) used by Castanet's tests.  For this reason, Castanet's Cucumber
+scenarios use [RVM](http://rvm.beginrescueend.com/) to run servers in
+appropriate Ruby implementations.
+
+Castanet's CAS response parsers are implemented using
+[Ragel](http://www.complang.org/ragel/).
+
+Once you've got Bundler, RVM, and Ragel installed and set up:
+
+    $ bundle install
+    $ rake udaeta:install_dependencies --trace   # because it helps to see what's going on
+    $ rake ci --trace                            # ditto
+
+Assuming you cloned Castanet at a point where its CI build succeeded, all steps
+should pass.  If they don't, feel free to ping me.
+
+License
+=======
+
+Copyright (c) 2011 David Yip.  Released under the X11 (MIT) License; see LICENSE
+for details.

data/lib/castanet.rb

@@ -0,0 +1,8 @@
+module Castanet
+  autoload :Client,           'castanet/client'
+  autoload :ProxyTicket,      'castanet/proxy_ticket'
+  autoload :ProxyTicketError, 'castanet/proxy_ticket_error'
+  autoload :Responses,        'castanet/responses'
+  autoload :QueryBuilding,    'castanet/query_building'
+  autoload :ServiceTicket,    'castanet/service_ticket'
+end

data/lib/castanet/client.rb

@@ -0,0 +1,207 @@
+require 'castanet'
+
+require 'net/http'
+require 'uri'
+
+module Castanet
+  ##
+  # A CAS client.
+  #
+  # Expected interface
+  # ==================
+  #
+  # Classes that mix in this module must define the method
+  #
+  #     cas_url => String
+  #
+  # `cas_url` defines the base URL of the CAS server and must have a terminating /.
+  #
+  # If CAS proxying is desired, classes must further define
+  #
+  #     proxy_callback_url => String
+  #     proxy_retrieval_url => String
+  #
+  # `proxy_callback_url` is a URL of a service that will be used by the CAS
+  # server for depositing PGTs.  (In the CAS protocol, it's the URL passed to
+  # `/serviceValidate` in the `pgtIou` parameter.)
+  #
+  # `proxy_retrieval_url` is a URL of a service that will be used to retrieve
+  # deposited PGTs.
+  #
+  #
+  # Security requirements
+  # =====================
+  #
+  # Section 2.5.4 of the CAS 2.0 protocol mandates that the proxy callback
+  # service pointed to by `proxy_callback_url` must
+  #
+  # 1. be accessible over HTTPS and
+  # 2. present an SSL certificate that
+  #     1. is valid and
+  #     2. has a canonical name that matches that of the proxy callback service.
+  #
+  # Secure channels are not required for any other part of the CAS protocol,
+  # but we still recommend using HTTPS for all communication involving any
+  # permutation of interactions between the CAS server, the user, and the
+  # application.
+  #
+  # Because of this ambiguity in the CAS protocol -- and because unencrypted
+  # transmission can be useful in isolated development environments -- Castanet
+  # will permit non-HTTPS communication with CAS servers.  However, you must
+  # explicitly declare your intent in the class using this client by defining
+  # {#https_disabled} equal to `true`:
+  #
+  #     class InsecureClient
+  #       include Castanet::Client
+  #
+  #       def https_disabled
+  #         true
+  #       end
+  #     end
+  #
+  # Also keep in mind that future revisions of Castanet may remove this option.
+  #
+  # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol, section 2.5.4
+  # @see http://www.daemonology.net/blog/2009-09-04-complexity-is-insecurity.html
+  #   "Complexity is insecurity" by Colin Percival
+  #
+  # Examples
+  # ========
+  #
+  # Presenting a service ticket
+  # ---------------------------
+  #
+  #     ticket = service_ticket('ST-1foo', 'https://service.example.edu')
+  #     ticket.present!
+  #
+  #     ticket.ok? # => true or false
+  #
+  #
+  # Retrieving a proxy-granting ticket
+  # ----------------------------------
+  #
+  #     ticket = service_ticket(...)
+  #     ticket.present!
+  #     ticket.retrieve_pgt!    # PGT can be retrieved from ticket.pgt
+  #
+  #
+  # Requesting a proxy ticket
+  # -------------------------
+  #
+  #     ticket = proxy_ticket(pgt, service)  # returns a ProxyTicket
+  #
+  # {ProxyTicket}s can be coerced into Strings.
+  #
+  #
+  # Validating a proxy ticket
+  # -------------------------
+  #
+  #     ticket = proxy_ticket(pgt, service)
+  #     ticket.present!
+  #
+  #     ticket.ok? # => true or false
+  #
+  #
+  # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol
+  module Client
+    ##
+    # Whether or not to disable HTTPS for CAS server communication.  Defaults
+    # to false.
+    #
+    # @return [false]
+    def https_disabled
+      false
+    end
+
+    ##
+    # Returns the service ticket validation endpoint for the configured CAS URL.
+    #
+    # The service ticket validation endpoint is defined as `cas_url` +
+    # `"/serviceValidate"`.
+    #
+    # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol, section 2.5
+    # @see #cas_url
+    # @return [String]
+    def service_validate_url
+      URI.join(cas_url, 'serviceValidate').to_s
+    end
+
+    ##
+    # Returns the proxy ticket grantor endpoint for the configured CAS URL.
+    #
+    # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol, section 2.7
+    # @see #cas_url
+    # @return [String]
+    def proxy_url
+      URI.join(cas_url, 'proxy').to_s
+    end
+
+    ##
+    # Returns the proxy ticket validation endpoint for the configured CAS URL.
+    #
+    # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol, section 2.6
+    # @see #cas_url
+    # @return [String]
+    def proxy_validate_url
+      URI.join(cas_url, 'proxyValidate').to_s
+    end
+
+    ##
+    # Prepares a {ServiceTicket} for the ticket `ticket` and the service URL
+    # `service`.
+    #
+    # The prepared {ServiceTicket} can be presented for validation at a later
+    # time.
+    #
+    # @param [String] ticket text of a service ticket
+    # @param [String] service a service URL
+    # @return [ServiceTicket]
+    def service_ticket(ticket, service)
+      ServiceTicket.new(ticket, service).tap do |st|
+        st.https_disabled = https_disabled
+        st.proxy_callback_url = proxy_callback_url
+        st.proxy_retrieval_url = proxy_retrieval_url
+        st.service_validate_url = service_validate_url
+      end
+    end
+
+    ##
+    # Given the PGT `pgt`, retrieves a proxy ticket for the service URL
+    # `service`.
+    #
+    # If a proxy ticket cannot be issued for any reason, this method raises a
+    # {ProxyTicketError} containing the failure code and reason returned by the
+    # CAS server.
+    #
+    # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol, section 2.7
+    # @see {ProxyTicket#reify!}
+    # @raise [ProxyTicketError]
+    # @return [ProxyTicket] the issued proxy ticket
+    def issue_proxy_ticket(pgt, service)
+      ProxyTicket.new(nil, pgt, service).tap do |pt|
+        pt.https_disabled = https_disabled
+        pt.proxy_url = proxy_url
+        pt.proxy_validate_url = proxy_validate_url
+      end.reify!
+    end
+
+    ##
+    # Builds a {ProxyTicket} for the proxy ticket `pt` and service URL `service`.
+    #
+    # The returned {ProxyTicket} instance can be used to validate `pt` for
+    # `service` using `#present!`.
+    #
+    # @param [String, ProxyTicket] ticket the proxy ticket
+    # @param [String] service the service URL
+    # @return [ProxyTicket]
+    def proxy_ticket(ticket, service)
+      ProxyTicket.new(ticket.to_s, nil, service).tap do |pt|
+        pt.https_disabled = https_disabled
+        pt.proxy_callback_url = proxy_callback_url
+        pt.proxy_retrieval_url = proxy_retrieval_url
+        pt.proxy_url = proxy_url
+        pt.proxy_validate_url = proxy_validate_url
+      end
+    end
+  end
+end

data/lib/castanet/proxy_ticket.rb

@@ -0,0 +1,133 @@
+require 'castanet'
+
+require 'uri'
+
+module Castanet
+  class ProxyTicket < ServiceTicket
+    ##
+    # The URL of the CAS server's proxy ticket granting service.
+    #
+    # @return [String]
+    attr_accessor :proxy_url
+
+    ##
+    # The URL of the CAS server's proxy ticket validation service.
+    #
+    # @return [String]
+    attr_accessor :proxy_validate_url
+
+    ##
+    # The `/proxy` response from the CAS server.
+    #
+    # This is set by {#reify!}, but can be set manually for testing purposes.
+    #
+    # @return [#ticket]
+    attr_accessor :proxy_response
+
+    def_delegator :proxy_response, :ok?, :issued?
+
+    def_delegators :proxy_response, :failure_code, :failure_reason
+
+    ##
+    # Initializes an instance of ProxyTicket.
+    #
+    # Instantiation guide
+    # ===================
+    #
+    # 1. If requesting a proxy ticket, set `pt` to nil, `service` to the
+    #    service URL, and `pgt` to the proxy granting ticket.
+    # 2. If checking a proxy ticket, set `pt` to the proxy ticket, `service` to
+    #    the service URL, and `pgt` to nil.
+    #
+    # @param [String, nil] pt the proxy ticket
+    # @param [String, nil] pgt the proxy granting ticket
+    # @param [String] service the service URL
+    def initialize(pt, pgt, service)
+      super(pt, service)
+
+      self.pgt = pgt
+    end
+
+    ##
+    # The proxy ticket wrapped by this object.  This can come either from a
+    # proxy ticket issuance via {#reify!} or be set at instantiation.  Tickets
+    # issued via {#reify!} have higher precedence.
+    #
+    # If a proxy ticket was neither supplied at instantiation nor requested via
+    # {#reify!}, then ticket will return nil.
+    #
+    # @return [String, nil] the proxy ticket
+    def ticket
+      proxy_response ? proxy_response.ticket : super
+    end
+
+    ##
+    # Returns the string representation of {#ticket}.
+    #
+    # If {#ticket} is not nil, then the return value of this method is
+    # {#ticket}; otherwise, it is `""`.
+    #
+    # @return [String] the ticket or empty string
+    def to_s
+     ticket.to_s
+    end
+
+    ##
+    # Requests a proxy ticket from {#proxy_url} and stores it in {#ticket}.
+    #
+    # If a proxy ticket cannot be issued for any reason, this method raises a
+    # {ProxyTicketError} containing the failure code and reason returned by the
+    # CAS server.
+    #
+    # This method should only be run once per `ProxyTicket` instance.  It can be
+    # run multiple times, but each invocation will overwrite {#ticket} with a
+    # new ticket.
+    #
+    # This method is automatically called by {Client#proxy_ticket}, and as such
+    # should never need to be called by users of Castanet; however, in the
+    # interest of program organization, the method is public and located here.
+    # Also, if you're managing `ProxyTicket` instances manually for some reason,
+    # you may find this method useful.
+    #
+    # @raise [ProxyTicketError] if a proxy ticket cannot be issued
+    # @return void
+    def reify!
+      uri = URI.parse(proxy_url).tap do |u|
+        u.query = grant_parameters
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port).tap do |h|
+        h.use_ssl = !https_disabled
+      end
+
+      http.start do |h|
+        cas_response = h.get(uri.to_s)
+
+        self.proxy_response = parsed_proxy_response(cas_response.body)
+
+        unless issued?
+          raise ProxyTicketError, "A proxy ticket could not be issued.  Code: <#{failure_code}>, reason: <#{failure_reason}>."
+        end
+
+        self
+      end
+    end
+
+    protected
+
+    ##
+    # The URL to use for ticket validation.
+    #
+    # @return [String]
+    def validation_url
+      proxy_validate_url
+    end
+
+    private
+
+    def grant_parameters
+      query(['pgt',           pgt],
+            ['targetService', service])
+    end
+  end
+end

data/lib/castanet/proxy_ticket_error.rb

@@ -0,0 +1,6 @@
+require 'castanet'
+
+module Castanet
+  class ProxyTicketError < StandardError
+  end
+end