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/>.