.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Authen::CAS::Client 3pm"
.TH Authen::CAS::Client 3pm "2009-07-27" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Authen::CAS::Client \- Provides an easy\-to\-use interface for authentication using JA\-SIG's Central Authentication Service
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Authen::CAS::Client;
\&
\&  my $cas = Authen::CAS::Client\->new( \*(Aqhttps://example.com/cas\*(Aq );
\&
\&
\&  # generate an HTTP redirect to the CAS login URL
\&  my $r = HTTP::Response\->new( 302 );
\&  $r\->header( Location => $cas\->login_url );
\&
\&
\&  # generate an HTTP redirect to the CAS logout URL
\&  my $r = HTTP::Response\->new( 302 );
\&  $r\->header( Location => $cas\->logout_url );
\&
\&
\&  # validate a service ticket (CAS v1.0)
\&  my $r = $cas\->validate( $service, $ticket );
\&  if( $r\->is_success ) {
\&    print "User authenticated as: ", $r\->user, "\en";
\&  }
\&
\&  # validate a service ticket (CAS v2.0)
\&  my $r = $cas\->service_validate( $service, $ticket );
\&  if( $r\->is_success ) {
\&    print "User authenticated as: ", $r\->user, "\en";
\&  }
\&
\&
\&  # validate a service/proxy ticket (CAS v2.0)
\&  my $r = $cas\->proxy_validate( $service, $ticket );
\&  if( $r\->is_success ) {
\&    print "User authenticated as: ", $r\->user, "\en";
\&    print "Proxied through:\en";
\&    print "  $_\en"
\&      for $r\->proxies;
\&  }
\&
\&
\&  # validate a service ticket and request a proxy ticket (CAS v2.0)
\&  my $r = $cas\->service_validate( $server, $ticket, pgtUrl => $url );
\&  if( $r\->is_success ) {
\&    print "User authenticated as: ", $r\->user, "\en";
\&
\&    unless( defined $r\->iou ) {
\&      print "Service validation for proxying failed\en";
\&    }
\&    else {
\&      print "Proxy granting ticket IOU: ", $r\->iou, "\en";
\&
\&      ...
\&      # map IOU to proxy granting ticket via request to pgtUrl
\&      ...
\&
\&      $r = $cas\->proxy( $pgt, $target_service );
\&      if( $r\->is_success ) {
\&        print "Proxy ticket issued: ", $r\->proxy_ticket, "\en";
\&      }
\&    }
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Authen::CAS::Client\*(C'\fR module provides a simple interface for
authenticating users using JA-SIG's \s-1CAS\s0 protocol.  Both \s-1CAS\s0 v1.0
and v2.0 are supported.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "\fBnew \fB$url\fB [, \f(BI%args\fB]\fR" 2
.el .IP "\fBnew \f(CB$url\fB [, \f(CB%args\fB]\fR" 2
.IX Item "new $url [, %args]"
\&\f(CW\*(C`new()\*(C'\fR creates an instance of an \f(CW\*(C`Authen::CAS::Client\*(C'\fR object.  \f(CW$url\fR
refers to the \s-1CAS\s0 server's base \s-1URL\s0.  \f(CW%args\fR may contain the
following optional parameter:
.RS 2
.IP "\(bu" 4
fatal => \f(CW$boolean\fR
.Sp
If this argument is true, the \s-1CAS\s0 client will \f(CW\*(C`die()\*(C'\fR when an error
occurs and \f(CW$@\fR will contain the error message.  Otherwise an
\&\f(CW\*(C`Authen::CAS::Client::Response::Error\*(C'\fR object will be returned.  See
Authen::CAS::Client::Response for more detail on response objects.
.RE
.RS 2
.RE
.ie n .IP "\fBlogin_url \fB$service\fB [, \f(BI%args\fB]\fR" 2
.el .IP "\fBlogin_url \f(CB$service\fB [, \f(CB%args\fB]\fR" 2
.IX Item "login_url $service [, %args]"
\&\f(CW\*(C`login_url()\*(C'\fR returns the \s-1CAS\s0 server's login \s-1URL\s0 which can be used to
redirect users to start the authentication process.  \f(CW$service\fR is the
service identifier that will be used during validation requests.
\&\f(CW%args\fR may contain the following optional parameters:
.RS 2
.IP "\(bu" 4
renew => \f(CW$boolean\fR
.Sp
This causes the \s-1CAS\s0 server to force a user to re-authenticate even if
an \s-1SSO\s0 session is already present for that user.
.IP "\(bu" 4
gateway => \f(CW$boolean\fR
.Sp
This causes the \s-1CAS\s0 server to only rely on \s-1SSO\s0 sessions for authentication.
If an \s-1SSO\s0 session is not available for the current user, validation
will result in a failure.
.RE
.RS 2
.RE
.IP "\fBlogout_url [%args]\fR" 2
.IX Item "logout_url [%args]"
\&\f(CW\*(C`logout_url()\*(C'\fR returns the \s-1CAS\s0 server's logout \s-1URL\s0 which can be used to
redirect users to end authenticated sessions.  \f(CW%args\fR may contain
the following optional parameter:
.RS 2
.IP "\(bu" 4
url => \f(CW$url\fR
.Sp
If present, the \s-1CAS\s0 server will present the user with a link to the given
\&\s-1URL\s0 once the user has logged out.
.RE
.RS 2
.RE
.ie n .IP "\fBvalidate \fB$service\fB, \f(BI$ticket\fB [, \f(CB%args\fB]\fR" 2
.el .IP "\fBvalidate \f(CB$service\fB, \f(CB$ticket\fB [, \f(CB%args\fB]\fR" 2
.IX Item "validate $service, $ticket [, %args]"
\&\f(CW\*(C`validate()\*(C'\fR attempts to validate a service ticket using the \s-1CAS\s0 v1.0
protocol.  \f(CW$service\fR is the service identifier that was passed to the
\&\s-1CAS\s0 server during the login process.  \f(CW$ticket\fR is the service ticket
that was received after a successful authentication attempt.  Returns an
appropriate Authen::CAS::Response object.  \f(CW%args\fR may contain the
following optional parameter:
.RS 2
.IP "\(bu" 4
renew => \f(CW$boolean\fR
.Sp
This will cause the \s-1CAS\s0 server to respond with a failure if authentication
validation was done via a \s-1CAS\s0 \s-1SSO\s0 session.
.RE
.RS 2
.RE
.ie n .IP "\fBservice_validate \fB$service\fB, \f(BI$ticket\fB [, \f(CB%args\fB]\fR" 2
.el .IP "\fBservice_validate \f(CB$service\fB, \f(CB$ticket\fB [, \f(CB%args\fB]\fR" 2
.IX Item "service_validate $service, $ticket [, %args]"
\&\f(CW\*(C`service_validate()\*(C'\fR attempts to validate a service ticket using the
\&\s-1CAS\s0 v2.0 protocol.  This is similar to \f(CW\*(C`validate()\*(C'\fR, but allows for
greater flexibility when there is a need for proxying authentication
to back-end services.  The \f(CW$service\fR and \f(CW$ticket\fR parameters are
the same as above.  Returns an appropriate Authen::CAS::Response
object.  \f(CW%args\fR may contain the following optional parameters:
.RS 2
.IP "\(bu" 4
renew => \f(CW$boolean\fR
.Sp
This will cause the \s-1CAS\s0 server to respond with a failure if authentication
validation was done via a \s-1CAS\s0 \s-1SSO\s0 session.
.IP "\(bu" 4
pgtUrl => \f(CW$url\fR
.Sp
This tells the \s-1CAS\s0 server that a proxy ticket needs to be issued for
proxying authentication to a back-end service.  \f(CW$url\fR corresponds to
a callback \s-1URL\s0 that the \s-1CAS\s0 server will use to verify the service's
identity.  Per the \s-1CAS\s0 specification, this \s-1URL\s0 must be \s-1HTTPS\s0.  If this
verification fails, normal validation will occur, but a proxy granting
ticket \s-1IOU\s0 will not be issued.
.Sp
Also note that this call will block until the \s-1CAS\s0 server completes its
service verification attempt.  The returned proxy granting ticket \s-1IOU\s0
can then be used to retrieve the proxy granting ticket that was passed
as a parameter to the given \s-1URL\s0.
.RE
.RS 2
.RE
.ie n .IP "\fBproxy_validate \fB$service\fB, \f(BI$ticket\fB [, \f(CB%args\fB]\fR" 2
.el .IP "\fBproxy_validate \f(CB$service\fB, \f(CB$ticket\fB [, \f(CB%args\fB]\fR" 2
.IX Item "proxy_validate $service, $ticket [, %args]"
\&\f(CW\*(C`proxy_validate()\*(C'\fR is almost identical in operation to \f(CW\*(C`service_validate()\*(C'\fR
except that both service tickets and proxy tickets can be used for
validation and a list of proxies will be provided if proxied authentication
has been used.  The \f(CW$service\fR and \f(CW$ticket\fR parameters are the same as
above.  Returns an appropriate Authen::CAS::Response object.  \f(CW%args\fR
may contain the following optional parameters:
.RS 2
.IP "\(bu" 4
renew => \f(CW$boolean\fR
.Sp
This is the same as described above.
.IP "\(bu" 4
pgtUrl => \f(CW$url\fR
.Sp
This is the same as described above.
.RE
.RS 2
.RE
.ie n .IP "\fBproxy \fB$pgt\fB, \f(BI$target\fB\fR" 2
.el .IP "\fBproxy \f(CB$pgt\fB, \f(CB$target\fB\fR" 2
.IX Item "proxy $pgt, $target"
\&\f(CW\*(C`proxy()\*(C'\fR is used to retrieve a proxy ticket that can be passed to
a back-end service for proxied authentication.  \f(CW$pgt\fR is the proxy
granting ticket that was passed as a parameter to the \f(CW\*(C`pgtUrl\*(C'\fR
specified in either \f(CW\*(C`service_validate()\*(C'\fR or \f(CW\*(C`proxy_validate()\*(C'\fR.
\&\f(CW$target\fR is the service identifier for the back-end system that will
be using the returned proxy ticket for validation.  Returns an appropriate
Authen::CAS::Response object.
.SH "BUGS"
.IX Header "BUGS"
None are known at this time, but if you find one, please feel free to
submit a report to the author.
.SH "AUTHOR"
.IX Header "AUTHOR"
jason hord <pravus@cpan.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Authen::CAS::Client::Response
.PP
More information about \s-1CAS\s0 can be found at JA-SIG's \s-1CAS\s0 homepage:
<http://www.ja\-sig.org/products/cas/>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2007\-2009, jason hord
.PP
All rights reserved.
.PP
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
.IP "\(bu" 2
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 2
Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
.PP
\&\s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1PROVIDED\s0 \s-1BY\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND\s0 \s-1CONTRIBUTORS\s0
\&\*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1AND\s0 \s-1ANY\s0 \s-1EXPRESS\s0 \s-1OR\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0
\&\s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0
A \s-1PARTICULAR\s0 \s-1PURPOSE\s0 \s-1ARE\s0 \s-1DISCLAIMED\s0. \s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1SHALL\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1OWNER\s0 \s-1OR\s0
\&\s-1CONTRIBUTORS\s0 \s-1BE\s0 \s-1LIABLE\s0 \s-1FOR\s0 \s-1ANY\s0 \s-1DIRECT\s0, \s-1INDIRECT\s0, \s-1INCIDENTAL\s0, \s-1SPECIAL\s0,
\&\s-1EXEMPLARY\s0, \s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 (\s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0,
\&\s-1PROCUREMENT\s0 \s-1OF\s0 \s-1SUBSTITUTE\s0 \s-1GOODS\s0 \s-1OR\s0 \s-1SERVICES\s0; \s-1LOSS\s0 \s-1OF\s0 \s-1USE\s0, \s-1DATA\s0, \s-1OR\s0
\&\s-1PROFITS\s0; \s-1OR\s0 \s-1BUSINESS\s0 \s-1INTERRUPTION\s0) \s-1HOWEVER\s0 \s-1CAUSED\s0 \s-1AND\s0 \s-1ON\s0 \s-1ANY\s0 \s-1THEORY\s0 \s-1OF\s0
\&\s-1LIABILITY\s0, \s-1WHETHER\s0 \s-1IN\s0 \s-1CONTRACT\s0, \s-1STRICT\s0 \s-1LIABILITY\s0, \s-1OR\s0 \s-1TORT\s0 (\s-1INCLUDING\s0
\&\s-1NEGLIGENCE\s0 \s-1OR\s0 \s-1OTHERWISE\s0) \s-1ARISING\s0 \s-1IN\s0 \s-1ANY\s0 \s-1WAY\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OF\s0 \s-1THIS\s0
\&\s-1SOFTWARE\s0, \s-1EVEN\s0 \s-1IF\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0 \s-1SUCH\s0 \s-1DAMAGE\s0.