README

Castanet
========

Castanet is a client library for applications that use Jasig's Central
Authentication Service.  It fully implements version 2.0 of the CAS protocol.

Castanet was built at the Northwestern University Health and Biomedical
Informatics Center as a replacement for RubyCAS-Client in internal software.


License
=======

Castanet is MIT-licensed.  See LICENSE for more information.


Installation and setup
======================

To install:

    $ gem install castanet

The Castanet::Client module is the top-level interface for all of Castanet's
functions.  Mix it into the classes that will do CAS interaction:

    class Authenticator
      include Castanet::Client
    
      ##
      # The base URL of the CAS server.  Required.
      def cas_url
        'https://cas.example.edu'
      end
        
      ##
      # The URL to a service that will be used by the CAS server to deposit
      # proxy-granting tickets.  Required if you're using CAS proxying.
      def proxy_callback_url
        'https://cas.example.edu/callback/receive_pgt'
      end

      ##
      # The URL to a service that will be used to retrieve deposited PGTs.
      # Required if you're doing CAS proxying.
      def proxy_retrieval_url
        'https://cas.example.edu/callback/receive_pgt'
      end
    end

Using Castanet
==============

Validating a service ticket presented by a user
-----------------------------------------------

    # First parameter is the ticket, second is the service URL
    st = service_ticket('ST-1foo', 'https://service.example.edu')
    st.present!

    st.ok?  # true or false


Retrieving a proxy-granting ticket from a service ticket
--------------------------------------------------------

    st = service_ticket('ST-1foo', 'https://service.example.edu')
    st.present!

    st.retrieve_pgt! if st.ok?
    pgt = st.pgt


Retrieving a proxy-granting ticket from a proxy ticket
------------------------------------------------------

    pt = proxy_ticket('PT-1foo', 'https://service.example.edu')
    pt.present!

    pt.retrieve_pgt! if pt.ok?
    pgt = pt.pgt


Validating a proxy ticket received from an incoming request
-----------------------------------------------------------

    # First parameter is the ticket, second is the service URL
    pt = proxy_ticket('PT-1foo', 'https://service.example.edu')
    pt.present!
    
    pt.ok?  # true or false


Requesting a proxy ticket for a service
---------------------------------------

    begin
      # First parameter is a PGT, second is the URL of the service to contact
      pt = issue_proxy_ticket('PGT-1foo', 'https://proxied.example.edu')
      
      # string representation of the ticket can now be retrieved using pt.ticket
      # or pt.to_s for use in e.g. URLs
      service = "https://proxied.example.edu/endpoint?PT=#{pt.to_s}"

      # more code here...
    rescue Castanet::ProxyTicketError
      # code to rescue from a PT issuance error
    end

More usage examples can be found in Castanet's tests and NUBIC's Aker library 
at https://github.com/NUBIC/aker.git.

Acknowledgments
===============

Castanet's test harness was originally based on code written by Rhett Sutphin.

Query string building code was taken from Rack.

 vim:ts=2:sw=2:et:tw=80