NAME

       WebAuth::Token - Generic WebAuth token handling

SYNOPSIS

           use WebAuth;

           my $wa = WebAuth->new;
           eval {
               $token = WebAuth->token_decode ($wa, $data, $keyring);
               print ref ($token), " received\n";
               print "Encoded: ", $token->encode, "\n";
           };
           if ($@) {
               # handle exception
           }

DESCRIPTION

       WebAuth::Token is the parent class for all WebAuth token objects.  Other than when creating a new token
       by decoding an encrypted token, this class will never be used directly.  Instead, it is the base class
       for all other WebAuth::Token::* classes, each of which represents a specific type of protocol token.

       The following token classes are currently supported:

       WebAuth::Token::App
           Used  by a WebAuth Application Server to store data, such as the identity of an authenticated user or
           the session key for that identity information.

       WebAuth::Token::Cred
           Holds a credential for some other service, usually a Kerberos service ticket.  It is sent back by the
           WebKDC to a WebAuth Application Server when requested using a proxy token, and the WAS also  uses  it
           to store the credentials in cookies.

       WebAuth::Token::Error
           Returned  by  the  WebKDC  in  response  to a request token if some error occurred in processing that
           request.

       WebAuth::Token::Id
           Identifies a user to a WebAuth Authentication Server.  This token is sent from the WebKDC to the  WAS
           following a user authentication to communicate the authentication information.

       WebAuth::Token::Login
           Used to communicate the user's username and password or other authentication secret from the WebLogin
           server to the WebKDC.

       WebAuth::Token::Proxy
           Used  by  a  WebAuth Application Server to request other tokens from the WebKDC.  This is returned by
           the WebKDC to  a  WebAuth  Application  Server  if  the  WAS  may  need  to  request  various  tokens
           (particularly credential tokens).

       WebAuth::Token::Request
           Sent by the WebAuth Application Server to the WebKDC to initiate a request.

           This  token  has  two  forms.   The  first is sent by the WAS to the WebKDC via a redirect to request
           either an id or a proxy token for the user, depending on whether the WAS will need credentials.   The
           second  is  sent to the WebKDC as part of a request for a service token and contains only the command
           and creation time.

       WebAuth::Token::WebKDCProxy
           Stores user credentials or authentication information for later use by the WebKDC.  This is the token
           that's stored as a single sign-on cookie in the user's browser, allowing the user to authenticate  to
           subsequent web sites without reauthenticating.  This token is also returned inside a proxy token to a
           WAS, which can then present it back to the WebKDC to obtain id or cred tokens.

       WebAuth::Token::WebKDCService
           Sent  by the WebKDC to a WAS and returned by the WAS to the WebKDC as part of the request token.  The
           purpose of this token is to store the session key used for  encrypting  the  request  token  and  its
           responses.   It's  encrypted  in  the  WebKDC's long-term key, and is therefore used by the WebKDC to
           recover the session key without having local state.

       Each of these tokens have different data elements and therefore different accessor  functions,  and  each
       has  its  own  separate documentation.  See that individual documentation for the available operations on
       each type of token.

CLASS METHODS

       As with WebAuth module functions, failures are signaled by throwing  WebAuth::Exception  rather  than  by
       return status.

       new (WEBAUTH, TOKEN, KEYRING)
           Given   an   encrypted   and   base64-encoded  TOKEN,  decode  and  decrypt  it  using  the  provided
           WebAuth::Keyring object.  The return value will be a subclass of WebAuth::Token as described above in
           "DESCRIPTION".

           Callers will normally want to check via isa() whether the returned token is  of  the  type  that  the
           caller expected.  Not performing that check can lead to security issues.

           This is a convenience wrapper around the WebAuth token_decode() method.

       The  subclasses  of WebAuth::Token also have a traditional new() constructor to create a new, empty token
       of that type.

AUTHOR

       Russ Allbery <eagle@eyrie.org>

SEE ALSO

       WebAuth(3),         WebAuth::Keyring(3),         WebAuth::Token::App(3),         WebAuth::Token::Cred(3),
       WebAuth::Token::Error(3),   WebAuth::Token::Id(3),   WebAuth::Token::Login(3),  WebAuth::Token::Proxy(3),
       WebAuth::Token::Request(3), WebAuth::Token::WebKDCProxy(3), WebAuth::Token::WebKDCService(3)

       This module is part of WebAuth.  The current version is available from <http://webauth.stanford.edu/>.

perl v5.22.1                                       2015-12-19                                WebAuth::Token(3pm)