1Authen::CAS::Client(3)User Contributed Perl DocumentationAuthen::CAS::Client(3)
2
3
4

NAME

6       Authen::CAS::Client - Provides an easy-to-use interface for
7       authentication using JA-SIG's Central Authentication Service
8

SYNOPSIS

10         use Authen::CAS::Client;
11
12         my $cas = Authen::CAS::Client->new( 'https://example.com/cas' );
13
14
15         # generate an HTTP redirect to the CAS login URL
16         my $r = HTTP::Response->new( 302 );
17         $r->header( Location => $cas->login_url );
18
19
20         # generate an HTTP redirect to the CAS logout URL
21         my $r = HTTP::Response->new( 302 );
22         $r->header( Location => $cas->logout_url );
23
24
25         # validate a service ticket (CAS v1.0)
26         my $r = $cas->validate( $service, $ticket );
27         if( $r->is_success ) {
28           print "User authenticated as: ", $r->user, "\n";
29         }
30
31         # validate a service ticket (CAS v2.0)
32         my $r = $cas->service_validate( $service, $ticket );
33         if( $r->is_success ) {
34           print "User authenticated as: ", $r->user, "\n";
35         }
36
37
38         # validate a service/proxy ticket (CAS v2.0)
39         my $r = $cas->proxy_validate( $service, $ticket );
40         if( $r->is_success ) {
41           print "User authenticated as: ", $r->user, "\n";
42           print "Proxied through:\n";
43           print "  $_\n"
44             for $r->proxies;
45         }
46
47
48         # validate a service ticket and request a proxy ticket (CAS v2.0)
49         my $r = $cas->service_validate( $server, $ticket, pgtUrl => $url );
50         if( $r->is_success ) {
51           print "User authenticated as: ", $r->user, "\n";
52
53           unless( defined $r->iou ) {
54             print "Service validation for proxying failed\n";
55           }
56           else {
57             print "Proxy granting ticket IOU: ", $r->iou, "\n";
58
59             ...
60             # map IOU to proxy granting ticket via request to pgtUrl
61             ...
62
63             $r = $cas->proxy( $pgt, $target_service );
64             if( $r->is_success ) {
65               print "Proxy ticket issued: ", $r->proxy_ticket, "\n";
66             }
67           }
68         }
69

DESCRIPTION

71       The Authen::CAS::Client module provides a simple interface for
72       authenticating users using JA-SIG's CAS protocol.  Both CAS v1.0 and
73       v2.0 are supported.
74

METHODS

76   new $url [, %args]
77       new() creates an instance of an "Authen::CAS::Client" object.  $url
78       refers to the CAS server's base URL.  %args may contain the following
79       optional parameter:
80
81       fatal => $boolean
82
83       If this argument is true, the CAS client will die() when an error
84       occurs and $@ will contain the error message.  Otherwise an
85       "Authen::CAS::Client::Response::Error" object will be returned.  See
86       Authen::CAS::Client::Response for more detail on response objects.
87
88   login_url $service [, %args]
89       login_url() returns the CAS server's login URL which can be used to
90       redirect users to start the authentication process.  $service is the
91       service identifier that will be used during validation requests.  %args
92       may contain the following optional parameters:
93
94       renew => $boolean
95
96       This causes the CAS server to force a user to re-authenticate even if
97       an SSO session is already present for that user.
98
99       gateway => $boolean
100
101       This causes the CAS server to only rely on SSO sessions for
102       authentication.  If an SSO session is not available for the current
103       user, validation will result in a failure.
104
105   logout_url [%args]
106       logout_url() returns the CAS server's logout URL which can be used to
107       redirect users to end authenticated sessions.  %args may contain the
108       following optional parameter:
109
110       url => $url
111
112       If present, the CAS server will present the user with a link to the
113       given URL once the user has logged out.
114
115   validate $service, $ticket [, %args]
116       validate() attempts to validate a service ticket using the CAS v1.0
117       protocol.  $service is the service identifier that was passed to the
118       CAS server during the login process.  $ticket is the service ticket
119       that was received after a successful authentication attempt.  Returns
120       an appropriate Authen::CAS::Client::Response object.  %args may contain
121       the following optional parameter:
122
123       renew => $boolean
124
125       This will cause the CAS server to respond with a failure if
126       authentication validation was done via a CAS SSO session.
127
128   service_validate $service, $ticket [, %args]
129       service_validate() attempts to validate a service ticket using the CAS
130       v2.0 protocol.  This is similar to validate(), but allows for greater
131       flexibility when there is a need for proxying authentication to back-
132       end services.  The $service and $ticket parameters are the same as
133       above.  Returns an appropriate Authen::CAS::Client::Response object.
134       %args may contain the following optional parameters:
135
136       renew => $boolean
137
138       This will cause the CAS server to respond with a failure if
139       authentication validation was done via a CAS SSO session.
140
141       pgtUrl => $url
142
143       This tells the CAS server that a proxy ticket needs to be issued for
144       proxying authentication to a back-end service.  $url corresponds to a
145       callback URL that the CAS server will use to verify the service's
146       identity.  Per the CAS specification, this URL must be HTTPS.  If this
147       verification fails, normal validation will occur, but a proxy granting
148       ticket IOU will not be issued.
149
150       Also note that this call will block until the CAS server completes its
151       service verification attempt.  The returned proxy granting ticket IOU
152       can then be used to retrieve the proxy granting ticket that was passed
153       as a parameter to the given URL.
154
155   proxy_validate $service, $ticket [, %args]
156       proxy_validate() is almost identical in operation to service_validate()
157       except that both service tickets and proxy tickets can be used for
158       validation and a list of proxies will be provided if proxied
159       authentication has been used.  The $service and $ticket parameters are
160       the same as above.  Returns an appropriate
161       Authen::CAS::Client::Response object.  %args may contain the following
162       optional parameters:
163
164       renew => $boolean
165
166       This is the same as described above.
167
168       pgtUrl => $url
169
170       This is the same as described above.
171
172   proxy $pgt, $target
173       proxy() is used to retrieve a proxy ticket that can be passed to a
174       back-end service for proxied authentication.  $pgt is the proxy
175       granting ticket that was passed as a parameter to the "pgtUrl"
176       specified in either service_validate() or proxy_validate().  $target is
177       the service identifier for the back-end system that will be using the
178       returned proxy ticket for validation.  Returns an appropriate
179       Authen::CAS::Client::Response object.
180

BUGS

182       None are known at this time, but if you find one, please feel free to
183       submit a report to the author.
184

AUTHOR

186       jason hord <pravus@cpan.org>
187

SEE ALSO

189       Authen::CAS::Client::Response
190
191       More information about CAS can be found at JA-SIG's CAS homepage:
192       <http://www.ja-sig.org/products/cas/>
193
195       Copyright (c) 2007-2014, jason hord
196
197       Permission is hereby granted, free of charge, to any person obtaining a
198       copy of this software and associated documentation files (the
199       "Software"), to deal in the Software without restriction, including
200       without limitation the rights to use, copy, modify, merge, publish,
201       distribute, sublicense, and/or sell copies of the Software, and to
202       permit persons to whom the Software is furnished to do so, subject to
203       the following conditions:
204
205       The above copyright notice and this permission notice shall be included
206       in all copies or substantial portions of the Software.
207
208       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
209       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
210       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
211       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
212       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
213       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
214       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
215
216
217
218perl v5.36.0                      2023-01-19            Authen::CAS::Client(3)
Impressum