.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Authen::CAS::Client 3pm"
.TH Authen::CAS::Client 3pm "2022-10-13" "perl v5.34.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 Authen::CAS::Client 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 .SS "new $url [, %args]"
.el .SS "new \f(CW$url\fP [, \f(CW%args\fP]"
.IX Subsection "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:
.PP
\fIfatal => \f(CI$boolean\fI\fR
.IX Subsection "fatal => $boolean"
.PP
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.
.ie n .SS "login_url $service [, %args]"
.el .SS "login_url \f(CW$service\fP [, \f(CW%args\fP]"
.IX Subsection "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:
.PP
\fIrenew => \f(CI$boolean\fI\fR
.IX Subsection "renew => $boolean"
.PP
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.
.PP
\fIgateway => \f(CI$boolean\fI\fR
.IX Subsection "gateway => $boolean"
.PP
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.
.SS "logout_url [%args]"
.IX Subsection "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:
.PP
\fIurl => \f(CI$url\fI\fR
.IX Subsection "url => $url"
.PP
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.
.ie n .SS "validate $service, $ticket [, %args]"
.el .SS "validate \f(CW$service\fP, \f(CW$ticket\fP [, \f(CW%args\fP]"
.IX Subsection "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::Client::Response object.  \f(CW%args\fR may
contain the following optional parameter:
.PP
\fIrenew => \f(CI$boolean\fI\fR
.IX Subsection "renew => $boolean"
.PP
This will cause the \s-1CAS\s0 server to respond with a failure if authentication
validation was done via a \s-1CAS SSO\s0 session.
.ie n .SS "service_validate $service, $ticket [, %args]"
.el .SS "service_validate \f(CW$service\fP, \f(CW$ticket\fP [, \f(CW%args\fP]"
.IX Subsection "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::Client::Response
object.  \f(CW%args\fR may contain the following optional parameters:
.PP
\fIrenew => \f(CI$boolean\fI\fR
.IX Subsection "renew => $boolean"
.PP
This will cause the \s-1CAS\s0 server to respond with a failure if authentication
validation was done via a \s-1CAS SSO\s0 session.
.PP
\fIpgtUrl => \f(CI$url\fI\fR
.IX Subsection "pgtUrl => $url"
.PP
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.
.PP
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
.ie n .SS "proxy_validate $service, $ticket [, %args]"
.el .SS "proxy_validate \f(CW$service\fP, \f(CW$ticket\fP [, \f(CW%args\fP]"
.IX Subsection "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::Client::Response object.
\&\f(CW%args\fR may contain the following optional parameters:
.PP
\fIrenew => \f(CI$boolean\fI\fR
.IX Subsection "renew => $boolean"
.PP
This is the same as described above.
.PP
\fIpgtUrl => \f(CI$url\fI\fR
.IX Subsection "pgtUrl => $url"
.PP
This is the same as described above.
.ie n .SS "proxy $pgt, $target"
.el .SS "proxy \f(CW$pgt\fP, \f(CW$target\fP"
.IX Subsection "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::Client::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"
.IP "Authen::CAS::Client::Response" 4
.IX Item "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 "LICENSE"
.IX Header "LICENSE"
This software is information.
It is subject only to local laws of physics.