Module: Castanet::Client

Defined in:
lib/castanet/client.rb

Overview

The top-level interface for Castant.

See the README for usage examples and interface expectations.

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.

By default, Castanet requires HTTPS for all communication with the CAS server or CAS proxy callback, and will raise a RuntimeError when non-HTTPS communication is attempted.

However, because of the above 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_required equal to false:

class InsecureClient
  include Castanet::Client

  def https_required
    false
  end
end

See Also:

Instance Method Summary collapse

Instance Method Details

#https_required ⇒ true

Whether or not to require HTTPS for CAS server communication. Defaults to true.

Returns:

  • (true) 


53
54
55
 
# File 'lib/castanet/client.rb', line 53

def https_required
  true
end

#issue_proxy_ticket(pgt, service) ⇒ ProxyTicket

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.

Returns:

Raises:

See Also:



121
122
123
124
125
126
127
128
129
 
# File 'lib/castanet/client.rb', line 121

def issue_proxy_ticket(pgt, service)
  ProxyTicket.new(nil, pgt, service).tap do |pt|
    pt.https_required = https_required
    pt.proxy_url = proxy_url
    pt.proxy_validate_url = proxy_validate_url

    pt.reify!
  end
end

#proxy_ticket(ticket, service) ⇒ ProxyTicket

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!.

Parameters:

  • ticket (String, ProxyTicket) —

    the proxy ticket

  • service (String) —

    the service URL

Returns:



140
141
142
143
144
145
146
147
148
 
# File 'lib/castanet/client.rb', line 140

def proxy_ticket(ticket, service)
  ProxyTicket.new(ticket.to_s, nil, service).tap do |pt|
    pt.https_required = https_required
    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

#proxy_url ⇒ String

Returns the proxy ticket grantor endpoint for the configured CAS URL.

Returns:

  • (String)

See Also:



76
77
78
 
# File 'lib/castanet/client.rb', line 76

def proxy_url
  URI.join(cas_url, 'proxy').to_s
end

#proxy_validate_url ⇒ String

Returns the proxy ticket validation endpoint for the configured CAS URL.

Returns:

  • (String)

See Also:



86
87
88
 
# File 'lib/castanet/client.rb', line 86

def proxy_validate_url
  URI.join(cas_url, 'proxyValidate').to_s
end

#service_ticket(ticket, service) ⇒ ServiceTicket

Prepares a ServiceTicket for the ticket ticket and the service URL service.

The prepared ServiceTicket can be presented for validation at a later time.

Parameters:

  • ticket (String) —

    text of a service ticket

  • service (String) —

    a service URL

Returns:



100
101
102
103
104
105
106
107
 
# File 'lib/castanet/client.rb', line 100

def service_ticket(ticket, service)
  ServiceTicket.new(ticket, service).tap do |st|
    st.https_required = https_required
    st.proxy_callback_url = proxy_callback_url
    st.proxy_retrieval_url = proxy_retrieval_url
    st.service_validate_url = service_validate_url
  end
end

#service_validate_url ⇒ String

Returns the service ticket validation endpoint for the configured CAS URL.

The service ticket validation endpoint is defined as cas_url + "/serviceValidate".

Returns:

  • (String)

See Also:



66
67
68
 
# File 'lib/castanet/client.rb', line 66

def service_validate_url
  URI.join(cas_url, 'serviceValidate').to_s
end