Authen...:Client(3pm)

📦
version 0.08 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so bestie, meet Authen::CAS::Client — it's a whole module (a 3pm manual page from the User Contributed Perl Documentation, no less) that gives you an easy-to-use interface for authentication using JA-SIG's Central Authentication Service. CAS. Yeah. That one. 🎀

✨ SYNOPSIS ✨

the vibe, in code:

use Authen::CAS::Client;

my $cas = Authen::CAS::Client->new( 'https://example.com/cas' );

# 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, "\n";
}

# validate a service ticket (CAS v2.0)
my $r = $cas->service_validate( $service, $ticket );
if( $r->is_success ) {
  print "User authenticated as: ", $r->user, "\n";
}

# 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, "\n";
  print "Proxied through:\n";
  print "  $_\n"
    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, "\n";

  unless( defined $r->iou ) {
    print "Service validation for proxying failed\n";
  }
  else {
    print "Proxy granting ticket IOU: ", $r->iou, "\n";

    ...
    # 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, "\n";
    }
  }
}

like, slay. 💅

🌈 DESCRIPTION 🌈

Authen::CAS::Client hands you a simple interface for authenticating users with JA-SIG's CAS protocol. and bestie, both CAS v1.0 AND v2.0 are supported. we love range. 👑

🦋 METHODS 🦋

new $url [, %args]

new() spins up a fresh instance of an Authen::CAS::Client object. $url is the CAS server's base URL. and %args? it may contain this optional parameter, okay:

  • fatal => $boolean — if this one's true, the CAS client will literally die() when an error happens, and $@ will hold the error message. otherwise? you get an Authen::CAS::Client::Response::Error object back instead. want the full tea on response objects? go see Authen::CAS::Client::Response. 🫶

login_url $service [, %args]

login_url() gives you back the CAS server's login URL, which you can use to redirect users so they start the authentication process. $service is the service identifier that gets used during validation requests. %args may contain these optional parameters:

  • renew => $boolean — this makes the CAS server force a user to re-authenticate even if an SSO session already exists for them. no shortcuts, bestie. 😤
  • gateway => $boolean — this makes the CAS server only rely on SSO sessions for authentication. and if there's no SSO session for the current user? validation will result in a failure. 💀

logout_url [%args]

logout_url() returns the CAS server's logout URL, which you can use to redirect users so they end their authenticated sessions. bye babes. 👋 %args may contain this optional parameter:

  • url => $url — if it's there, the CAS server will present the user with a link to the given URL once they've logged out. cute. 🎀

validate $service, $ticket [, %args]

validate() tries to validate a service ticket using the CAS v1.0 protocol. $service is the service identifier that was passed to the CAS server during the login process. $ticket is the service ticket you received after a successful authentication attempt. it returns an appropriate Authen::CAS::Client::Response object. %args may contain this optional parameter:

  • renew => $boolean — this makes the CAS server respond with a failure if the authentication validation was done via a CAS SSO session. 🙈

service_validate $service, $ticket [, %args]

service_validate() tries to validate a service ticket using the CAS v2.0 protocol. it's similar to validate(), but it allows for greater flexibility when you need to proxy authentication to back-end services. the $service and $ticket parameters are the same as above. it returns an appropriate Authen::CAS::Client::Response object. %args may contain these optional parameters:

  • renew => $boolean — this makes the CAS server respond with a failure if the authentication validation was done via a CAS SSO session.
  • pgtUrl => $url — this tells the CAS server that a proxy ticket needs to be issued so authentication can be proxied to a back-end service. $url is a callback URL that the CAS server will use to verify the service's identity. per the CAS specification, this URL must be HTTPS. and if this verification fails? normal validation still occurs, but a proxy granting ticket IOU will not be issued. 😭
also ngl, this call will block until the CAS server finishes its service verification attempt. the returned proxy granting ticket IOU can then be used to retrieve the proxy granting ticket that was passed as a parameter to the given URL. that's the whole loop, bestie. 🌀

proxy_validate $service, $ticket [, %args]

proxy_validate() is almost identical in operation to service_validate() — 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 $service and $ticket parameters are the same as above. it returns an appropriate Authen::CAS::Client::Response object. %args may contain these optional parameters:

  • renew => $boolean — this is the same as described above.
  • pgtUrl => $url — this is the same as described above.

proxy $pgt, $target

proxy() is how you retrieve a proxy ticket that can be passed to a back-end service for proxied authentication. $pgt is the proxy granting ticket that was passed as a parameter to the pgtUrl you specified in either service_validate() or proxy_validate(). $target is the service identifier for the back-end system that will use the returned proxy ticket for validation. it returns an appropriate Authen::CAS::Client::Response object. 🔥

💀 BUGS 💀

none are known at this time. but bestie, if you find one, please feel free to submit a report to the author. we're nice about it. 🫶

👑 AUTHOR 👑

jason hord <pravus@cpan.org>

🌸 SEE ALSO 🌸

🧚 LICENSE 🧚

This software is information. It is subject only to local laws of physics. ✨ (genuinely iconic, no notes.)

and that's the whole page, bestie — straight from perl v5.36.0, dated 2022-10-13, living in section 3pm of the User Contributed Perl Documentation. read it, love it, authenticate responsibly. 💖🦋🌸

📦 where this page comes from