castanet 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. data/.yardopts +1 -1
  2. data/CHANGELOG +20 -0
  3. data/README +122 -0
  4. data/lib/castanet/client.rb +3 -60
  5. data/lib/castanet/proxy_ticket.rb +3 -0
  6. data/lib/castanet/version.rb +1 -1
  7. metadata +90 -114
  8. data/History.md +0 -31
  9. data/README.md +0 -67
data/.yardopts CHANGED
@@ -2,4 +2,4 @@
2
2
  --markup markdown
3
3
  --hide-void-return
4
4
  --files lib/castanet/**/*.rl
5
- --files History.md
5
+ --files CHANGELOG
data/CHANGELOG ADDED
@@ -0,0 +1,20 @@
1
+ 2011-10-06 (1.0.1)
2
+
3
+ * Moved setup and usage examples to README.
4
+ * Made Castanet::ProxyTicketError#reify! raise Castanet::ProxyTicketError if no PGT is present.
5
+ * Added some tweaks for running CI builds on NUBIC's infrastructure.
6
+
7
+ 2011-02-18 (1.0.0)
8
+
9
+ * Castanet::Client#https_disabled has changed to Castanet::Client#https_required, and mixed HTTP/HTTPS communication is now possible. See the documentation of {Castanet::Client} for more information.
10
+ * Castanet::ProxyTicket#reify! no longer returns self.
11
+
12
+ 2011-02-14 (0.0.2)
13
+
14
+ * castanet/client.rb: require net/https to properly activate the HTTPS bits of Net::HTTP. (Dates to version 0.0.1.)
15
+ * castanet/proxy_ticket.rb: fix formatting error in documentation. (Dates to version 0.0.1.)
16
+ * Included this changelog in the YARD docs.
17
+
18
+ 2011-02-03 (0.0.1)
19
+
20
+ * Initial release.
data/README ADDED
@@ -0,0 +1,122 @@
1
+ Castanet
2
+ ========
3
+
4
+ Castanet is a client library for applications that use Jasig's Central
5
+ Authentication Service. It fully implements version 2.0 of the CAS protocol.
6
+
7
+ Castanet was built at the Northwestern University Health and Biomedical
8
+ Informatics Center as a replacement for RubyCAS-Client in internal software.
9
+
10
+
11
+ Installation and setup
12
+ ======================
13
+
14
+ To install:
15
+
16
+ $ gem install castanet
17
+
18
+ The Castanet::Client module is the top-level interface for all of Castanet's
19
+ functions. Mix it into the classes that will do CAS interaction:
20
+
21
+ class Authenticator
22
+ include Castanet::Client
23
+
24
+ ##
25
+ # The base URL of the CAS server. Required.
26
+ def cas_url
27
+ 'https://cas.example.edu'
28
+ end
29
+
30
+ ##
31
+ # The URL to a service that will be used by the CAS server to deposit
32
+ # proxy-granting tickets. Required if you're using CAS proxying.
33
+ def proxy_callback_url
34
+ 'https://cas.example.edu/callback/receive_pgt'
35
+ end
36
+
37
+ ##
38
+ # The URL to a service that will be used to retrieve deposited PGTs.
39
+ # Required if you're doing CAS proxying.
40
+ def proxy_retrieval_url
41
+ 'https://cas.example.edu/callback/receive_pgt'
42
+ end
43
+ end
44
+
45
+ Using Castanet
46
+ ==============
47
+
48
+ Validating a service ticket presented by a user
49
+ -----------------------------------------------
50
+
51
+ # First parameter is the ticket, second is the service URL
52
+ st = service_ticket('ST-1foo', 'https://service.example.edu')
53
+ st.present!
54
+
55
+ st.ok? # true or false
56
+
57
+
58
+ Retrieving a proxy-granting ticket from a service ticket
59
+ --------------------------------------------------------
60
+
61
+ st = service_ticket('ST-1foo', 'https://service.example.edu')
62
+ st.present!
63
+
64
+ st.retrieve_pgt! if st.ok?
65
+ pgt = st.pgt
66
+
67
+
68
+ Retrieving a proxy-granting ticket from a proxy ticket
69
+ ------------------------------------------------------
70
+
71
+ pt = proxy_ticket('PT-1foo', 'https://service.example.edu')
72
+ pt.present!
73
+
74
+ pt.retrieve_pgt! if pt.ok?
75
+ pgt = pt.pgt
76
+
77
+
78
+ Validating a proxy ticket received from an incoming request
79
+ -----------------------------------------------------------
80
+
81
+ # First parameter is the ticket, second is the service URL
82
+ pt = proxy_ticket('PT-1foo', 'https://service.example.edu')
83
+ pt.present!
84
+
85
+ pt.ok? # true or false
86
+
87
+
88
+ Requesting a proxy ticket for a service
89
+ ---------------------------------------
90
+
91
+ begin
92
+ # First parameter is a PGT, second is the URL of the service to contact
93
+ pt = issue_proxy_ticket('PGT-1foo', 'https://proxied.example.edu')
94
+
95
+ # string representation of the ticket can now be retrieved using pt.ticket
96
+ # or pt.to_s for use in e.g. URLs
97
+ service = "https://proxied.example.edu/endpoint?PT=#{pt.to_s}"
98
+
99
+ # more code here...
100
+ rescue Castanet::ProxyTicketError
101
+ # code to rescue from a PT issuance error
102
+ end
103
+
104
+ More usage examples can be found in Castanet's tests and NUBIC's Aker library
105
+ at https://github.com/NUBIC/aker.git.
106
+
107
+ Acknowledgments
108
+ ===============
109
+
110
+ Castanet's test harness was based on code originally written by Rhett Sutphin.
111
+
112
+ Query string building code was taken from Rack.
113
+
114
+
115
+ License
116
+ =======
117
+
118
+ Copyright (c) 2011 David Yip. Released under the X11 (MIT) License; see LICENSE
119
+ for details.
120
+
121
+
122
+ vim:ts=2:sw=2:et:tw=80
data/lib/castanet/client.rb CHANGED
@@ -6,29 +6,10 @@ require 'uri'
6
6
 
7
7
  module Castanet
8
8
  ##
9
- # A CAS client.
10
- #
11
- # Expected interface
12
- # ==================
13
- #
14
- # Classes that mix in this module must define the method
15
- #
16
- # cas_url => String
17
- #
18
- # `cas_url` defines the base URL of the CAS server and must have a terminating /.
19
- #
20
- # If CAS proxying is desired, classes must further define
21
- #
22
- # proxy_callback_url => String
23
- # proxy_retrieval_url => String
24
- #
25
- # `proxy_callback_url` is a URL of a service that will be used by the CAS
26
- # server for depositing PGTs. (In the CAS protocol, it's the URL passed to
27
- # `/serviceValidate` in the `pgtIou` parameter.)
28
- #
29
- # `proxy_retrieval_url` is a URL of a service that will be used to retrieve
30
- # deposited PGTs.
9
+ # The top-level interface for Castant.
31
10
  #
11
+ # See the README for usage examples and interface expectations.
12
+ #
32
13
  #
33
14
  # Security requirements
34
15
  # =====================
@@ -62,44 +43,6 @@ module Castanet
62
43
  # end
63
44
  # end
64
45
  #
65
- # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol, section 2.5.4
66
- #
67
- # Examples
68
- # ========
69
- #
70
- # Presenting a service ticket
71
- # ---------------------------
72
- #
73
- # ticket = service_ticket('ST-1foo', 'https://service.example.edu')
74
- # ticket.present!
75
- #
76
- # ticket.ok? # => true or false
77
- #
78
- #
79
- # Retrieving a proxy-granting ticket
80
- # ----------------------------------
81
- #
82
- # ticket = service_ticket(...)
83
- # ticket.present!
84
- # ticket.retrieve_pgt! # PGT can be retrieved from ticket.pgt
85
- #
86
- #
87
- # Requesting a proxy ticket
88
- # -------------------------
89
- #
90
- # ticket = proxy_ticket(pgt, service) # returns a ProxyTicket
91
- #
92
- # {ProxyTicket}s can be coerced into Strings.
93
- #
94
- #
95
- # Validating a proxy ticket
96
- # -------------------------
97
- #
98
- # ticket = proxy_ticket(pgt, service)
99
- # ticket.present!
100
- #
101
- # ticket.ok? # => true or false
102
- #
103
46
  # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol
104
47
  module Client
105
48
  ##
data/lib/castanet/proxy_ticket.rb CHANGED
@@ -89,9 +89,12 @@ module Castanet
89
89
  # here. Also, if you're managing `ProxyTicket` instances manually for some
90
90
  # reason, you may find this method useful.
91
91
  #
92
+ # @raise [ProxyTicketError] if the PGT is nil
92
93
  # @raise [ProxyTicketError] if a proxy ticket cannot be issued
93
94
  # @return void
94
95
  def reify!
96
+ raise ProxyTicketError, 'A PGT is not present.' unless pgt
97
+
95
98
  uri = URI.parse(proxy_url).tap do |u|
96
99
  u.query = grant_parameters
97
100
  end
data/lib/castanet/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  module Castanet
2
- VERSION = '1.0.0'
2
+ VERSION = '1.0.1'
3
3
  end
metadata CHANGED
@@ -1,140 +1,125 @@
1
- --- !ruby/object:Gem::Specification
1
+ --- !ruby/object:Gem::Specification
2
2
  name: castanet
3
- version: !ruby/object:Gem::Version
4
- prerelease: false
5
- segments:
6
- - 1
7
- - 0
8
- - 0
9
- version: 1.0.0
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.1
5
+ prerelease:
10
6
  platform: ruby
11
- authors:
7
+ authors:
12
8
  - David Yip
13
9
  autorequire:
14
10
  bindir: bin
15
11
  cert_chain: []
16
-
17
- date: 2011-02-18 00:00:00 +00:00
18
- default_executable:
19
- dependencies:
20
- - !ruby/object:Gem::Dependency
12
+ date: 2011-10-06 00:00:00.000000000Z
13
+ dependencies:
14
+ - !ruby/object:Gem::Dependency
21
15
  name: autotest
22
- requirement: &id001 !ruby/object:Gem::Requirement
16
+ requirement: &2157027920 !ruby/object:Gem::Requirement
23
17
  none: false
24
- requirements:
25
- - - ">="
26
- - !ruby/object:Gem::Version
27
- segments:
28
- - 0
29
- version: "0"
18
+ requirements:
19
+ - - ! '>='
20
+ - !ruby/object:Gem::Version
21
+ version: '0'
30
22
  type: :development
31
23
  prerelease: false
32
- version_requirements: *id001
33
- - !ruby/object:Gem::Dependency
24
+ version_requirements: *2157027920
25
+ - !ruby/object:Gem::Dependency
34
26
  name: ci_reporter
35
- requirement: &id002 !ruby/object:Gem::Requirement
27
+ requirement: &2157027380 !ruby/object:Gem::Requirement
36
28
  none: false
37
- requirements:
38
- - - ">="
39
- - !ruby/object:Gem::Version
40
- segments:
41
- - 0
42
- version: "0"
29
+ requirements:
30
+ - - ! '>='
31
+ - !ruby/object:Gem::Version
32
+ version: '0'
43
33
  type: :development
44
34
  prerelease: false
45
- version_requirements: *id002
46
- - !ruby/object:Gem::Dependency
35
+ version_requirements: *2157027380
36
+ - !ruby/object:Gem::Dependency
47
37
  name: cucumber
48
- requirement: &id003 !ruby/object:Gem::Requirement
38
+ requirement: &2157026860 !ruby/object:Gem::Requirement
49
39
  none: false
50
- requirements:
51
- - - ">="
52
- - !ruby/object:Gem::Version
53
- segments:
54
- - 0
55
- version: "0"
40
+ requirements:
41
+ - - ! '>='
42
+ - !ruby/object:Gem::Version
43
+ version: '0'
56
44
  type: :development
57
45
  prerelease: false
58
- version_requirements: *id003
59
- - !ruby/object:Gem::Dependency
46
+ version_requirements: *2157026860
47
+ - !ruby/object:Gem::Dependency
60
48
  name: mechanize
61
- requirement: &id004 !ruby/object:Gem::Requirement
49
+ requirement: &2157026420 !ruby/object:Gem::Requirement
62
50
  none: false
63
- requirements:
64
- - - ">="
65
- - !ruby/object:Gem::Version
66
- segments:
67
- - 0
68
- version: "0"
51
+ requirements:
52
+ - - ! '>='
53
+ - !ruby/object:Gem::Version
54
+ version: '0'
69
55
  type: :development
70
56
  prerelease: false
71
- version_requirements: *id004
72
- - !ruby/object:Gem::Dependency
57
+ version_requirements: *2157026420
58
+ - !ruby/object:Gem::Dependency
73
59
  name: rack
74
- requirement: &id005 !ruby/object:Gem::Requirement
60
+ requirement: &2157025900 !ruby/object:Gem::Requirement
61
+ none: false
62
+ requirements:
63
+ - - ! '>='
64
+ - !ruby/object:Gem::Version
65
+ version: '0'
66
+ type: :development
67
+ prerelease: false
68
+ version_requirements: *2157025900
69
+ - !ruby/object:Gem::Dependency
70
+ name: rake
71
+ requirement: &2157025420 !ruby/object:Gem::Requirement
75
72
  none: false
76
- requirements:
77
- - - ">="
78
- - !ruby/object:Gem::Version
79
- segments:
80
- - 0
81
- version: "0"
73
+ requirements:
74
+ - - ! '>='
75
+ - !ruby/object:Gem::Version
76
+ version: '0'
82
77
  type: :development
83
78
  prerelease: false
84
- version_requirements: *id005
85
- - !ruby/object:Gem::Dependency
79
+ version_requirements: *2157025420
80
+ - !ruby/object:Gem::Dependency
86
81
  name: rspec
87
- requirement: &id006 !ruby/object:Gem::Requirement
82
+ requirement: &2157024900 !ruby/object:Gem::Requirement
88
83
  none: false
89
- requirements:
84
+ requirements:
90
85
  - - ~>
91
- - !ruby/object:Gem::Version
92
- segments:
93
- - 2
94
- - 0
95
- version: "2.0"
86
+ - !ruby/object:Gem::Version
87
+ version: '2.0'
96
88
  type: :development
97
89
  prerelease: false
98
- version_requirements: *id006
99
- - !ruby/object:Gem::Dependency
90
+ version_requirements: *2157024900
91
+ - !ruby/object:Gem::Dependency
100
92
  name: webmock
101
- requirement: &id007 !ruby/object:Gem::Requirement
93
+ requirement: &2157023100 !ruby/object:Gem::Requirement
102
94
  none: false
103
- requirements:
104
- - - ">="
105
- - !ruby/object:Gem::Version
106
- segments:
107
- - 0
108
- version: "0"
95
+ requirements:
96
+ - - ! '>='
97
+ - !ruby/object:Gem::Version
98
+ version: '0'
109
99
  type: :development
110
100
  prerelease: false
111
- version_requirements: *id007
112
- - !ruby/object:Gem::Dependency
101
+ version_requirements: *2157023100
102
+ - !ruby/object:Gem::Dependency
113
103
  name: yard
114
- requirement: &id008 !ruby/object:Gem::Requirement
104
+ requirement: &2157022340 !ruby/object:Gem::Requirement
115
105
  none: false
116
- requirements:
117
- - - ">="
118
- - !ruby/object:Gem::Version
119
- segments:
120
- - 0
121
- version: "0"
106
+ requirements:
107
+ - - ! '>='
108
+ - !ruby/object:Gem::Version
109
+ version: '0'
122
110
  type: :development
123
111
  prerelease: false
124
- version_requirements: *id008
112
+ version_requirements: *2157022340
125
113
  description: A small, snappy CAS 2.0 client library for Ruby applications
126
- email:
114
+ email:
127
115
  - yipdw@northwestern.edu
128
116
  executables: []
129
-
130
117
  extensions: []
131
-
132
118
  extra_rdoc_files: []
133
-
134
- files:
119
+ files:
135
120
  - .yardopts
136
- - README.md
137
- - History.md
121
+ - README
122
+ - CHANGELOG
138
123
  - LICENSE
139
124
  - lib/castanet/client.rb
140
125
  - lib/castanet/proxy_ticket.rb
@@ -149,37 +134,28 @@ files:
149
134
  - lib/castanet/service_ticket.rb
150
135
  - lib/castanet/version.rb
151
136
  - lib/castanet.rb
152
- has_rdoc: true
153
- homepage: ""
137
+ homepage: ''
154
138
  licenses: []
155
-
156
139
  post_install_message:
157
140
  rdoc_options: []
158
-
159
- require_paths:
141
+ require_paths:
160
142
  - lib
161
- required_ruby_version: !ruby/object:Gem::Requirement
143
+ required_ruby_version: !ruby/object:Gem::Requirement
162
144
  none: false
163
- requirements:
164
- - - ">="
165
- - !ruby/object:Gem::Version
166
- segments:
167
- - 0
168
- version: "0"
169
- required_rubygems_version: !ruby/object:Gem::Requirement
145
+ requirements:
146
+ - - ! '>='
147
+ - !ruby/object:Gem::Version
148
+ version: '0'
149
+ required_rubygems_version: !ruby/object:Gem::Requirement
170
150
  none: false
171
- requirements:
172
- - - ">="
173
- - !ruby/object:Gem::Version
174
- segments:
175
- - 0
176
- version: "0"
151
+ requirements:
152
+ - - ! '>='
153
+ - !ruby/object:Gem::Version
154
+ version: '0'
177
155
  requirements: []
178
-
179
156
  rubyforge_project:
180
- rubygems_version: 1.3.7
157
+ rubygems_version: 1.8.6
181
158
  signing_key:
182
159
  specification_version: 3
183
160
  summary: A CAS client library
184
161
  test_files: []
185
-
data/History.md DELETED
@@ -1,31 +0,0 @@
1
- 1.0.0 (2011-02-18)
2
- ==================
3
-
4
- Backwards-incompatible changes
5
- ------------------------------
6
-
7
- - `Castanet::Client#https_disabled` has changed to
8
- {Castanet::Client#https_required}, and mixed HTTP/HTTPS communication is now
9
- possible. See the documentation of {Castanet::Client} for more information.
10
- - {Castanet::ProxyTicket#reify!} no longer returns `self`.
11
-
12
- 0.0.2 (2011-02-14)
13
- ==================
14
-
15
- Errors fixed
16
- ------------
17
-
18
- - `castanet/client.rb` now `require`s `net/https` to properly activate the
19
- HTTPS bits of `Net::HTTP`. (Dates to version 0.0.1.)
20
- - A formatting error in the documentation for `Castanet::ProxyTicket` was
21
- fixed. (Dates to version 0.0.1.)
22
-
23
- Minor enhancements
24
- ------------------
25
-
26
- - Included this changelog in the YARD docs.
27
-
28
- 0.0.1 (2011-02-03)
29
- ==================
30
-
31
- - Initial release.
data/README.md DELETED
@@ -1,67 +0,0 @@
1
- Castanet: a small, snappy CAS client library
2
- ============================================
3
-
4
- Castanet is a [Central Authentication Service](http://www.jasig.org/cas) (CAS)
5
- client library. It implements version 2.0 of the CAS protocol.
6
-
7
- Castanet was built at the [Northwestern University Biomedical Informatics
8
- Center](http://www.nucats.northwestern.edu/clinical-research-resources/data-collection-biomedical-informatics-and-nubic/bioinformatics-overview.html)
9
- as a replacement for [RubyCAS-Client](https://github.com/gunark/rubycas-client)
10
- in internal software.
11
-
12
- 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.
13
- Continuous integration reports are available at [NUBIC's CI
14
- server](https://ctms-ci.nubic.northwestern.edu/hudson/job/castanet/).
15
-
16
- Getting started
17
- ===============
18
-
19
- Castanet is distributed as a Rubygem, and can be installed like any other Rubygem:
20
-
21
- gem install castanet
22
-
23
- Mix `Castanet::Client` into the objects that need CAS client behavior.
24
-
25
- Objects that include `Castanet::Client` must implement `cas_url`,
26
- `proxy_callback_url`, and `proxy_retrieval_url`.
27
-
28
- See the documentation for `Castanet::Client` for more information and usage
29
- examples.
30
-
31
- Acknowledgments
32
- ===============
33
-
34
- Castanet's test harness was based off of code originally written by [Rhett
35
- Sutphin](mailto:rhett@detailedbalance.net).
36
-
37
- Query string building code was taken from [Rack](http://rack.rubyforge.org/).
38
-
39
- Development
40
- ===========
41
-
42
- Castanet uses [Bundler](http://gembundler.com/) version `~> 1.0` for dependency
43
- management.
44
-
45
- Some of Castanet's development dependencies work best in certain versions of
46
- Ruby. Additionally, some implementations of Ruby do not support constructs
47
- (i.e. `fork`) used by Castanet's tests. For this reason, Castanet's Cucumber
48
- scenarios use [RVM](http://rvm.beginrescueend.com/) to run servers in
49
- appropriate Ruby implementations.
50
-
51
- Castanet's CAS response parsers are implemented using
52
- [Ragel](http://www.complang.org/ragel/).
53
-
54
- Once you've got Bundler, RVM, and Ragel installed and set up:
55
-
56
- $ bundle install
57
- $ rake udaeta:install_dependencies --trace # because it helps to see what's going on
58
- $ rake ci --trace # ditto
59
-
60
- Assuming you cloned Castanet at a point where its CI build succeeded, all steps
61
- should pass. If they don't, feel free to ping me.
62
-
63
- License
64
- =======
65
-
66
- Copyright (c) 2011 David Yip. Released under the X11 (MIT) License; see LICENSE
67
- for details.