NAME

       WebKDC::WebRequest - Encapsulates a request to a WebAuth WebKDC

SYNOPSIS

           use WebKDC::WebRequest;

           my $req = WebKDC::WebRequest->new;
           $req->user ($user);
           $req->pass ($password);
           $req->request_token ($RT);
           $req->service_token ($ST);

DESCRIPTION

       A WebKDC::WebRequest object encapsulates a request to a WebAuth WebKDC, representing a
       login attempt for a particular WebAuth Application Server.  It is used by the WebLogin
       server as the argument to make_request_token_request.  The object has very little inherent
       functionality.  It's mostly a carrier for data.

CLASS METHODS

       new ()
           Create a new, empty WebKDC::WebRequest object.  At least some parameters must be set
           using accessor functions as described below to do anything useful with the object.

INSTANCE METHODS

       authz_subject ([USER])
           Retrieve or set the requested authorization identity.  This is an identity that the
           user wishes to assert for authorization purposes to the remote site.  It must be
           vetted by the WebKDC and will be included in the id or proxy token if asserting that
           authorization identity is permitted.

       device_id ([ID])
           Retrieve or set the ID of the device used for second factor authentication.  This
           attribute is required if neither otp() nor pass() are set.  It is used primarily to
           indicate a device with which the user is performing an out-of-band second factor
           authentication that doesn't involve a password or an OTP code.

       local_ip_addr ([ADDR])
       local_ip_port ([PORT])
       remote_ip_addr ([ADDR])
       remote_ip_port ([PORT])
           Retrieve or set information about the network connection that is attempting
           authentication.  If one of these values is set, all of them should be set.  The
           remote_* parameters are the IP address of the remote client that is attempting to
           authenticate, and the local_* parameters are the local interface and port to which
           that client connected.

       otp ([CODE])
           Retrieve or set the one-time password sent by the user.  This, pass(), or device_id()
           should be set, but otp() and pass() cannot both be set.

       otp_type ([CODE])
           Retrieve or set the one-time password type sent by the user.  Despite the name, this
           can also be used with device_id() to specify the factor type used for out-of-band
           device authentication, even if it doesn't involve OTP.  This should be a WebAuth
           factor code corresponding to the type of one-time password that this login token
           represents.  It may be left unset if the caller doesn't know.

       login_state ([STATE])
           Get or set the login state of the request.  This field can contain any data the
           implementer chooses to place and will be passed, by the WebKDC, to the user
           information service as part of an OTP validation.  It is usually used in conjunction
           with multifactor authentication to provide some additional data about the type of
           multifactor being used.  It may be left unset if unneeded.

       pass ([PASSWORD])
           Retrieve or set the password sent by the user.  Either this or otp should be set, but
           not both.

       proxy_cookie (TYPE[, COOKIE, FACTOR])
           Retrieve or set a proxy cookie of a particular type.  If COOKIE and FACTOR are given,
           sets a cookie of the given TYPE with value COOKIE and session factor FACTOR.  Returns
           the cookie value of the given TYPE or undef if no such cookie is available.

       proxy_cookies ([COOKIES])
           Retrieve or set a hash of all cookies.  If the COOKIES parameter is provided, it must
           be a hash of cookie types to anonymous hashes, with each value hash having two keys:
           "cookie", whose value is the cookie value, and "session_factor", whose value is the
           session factors for that cookie.  Returns a hash of cookie types to values without the
           factor information.

       proxy_cookies_rich ([COOKIES])
           Retrieve or set a hash of all cookies including session factors.  If the COOKIES
           parameter is provided, it must be a hash of cookie types to anonymous hashes, with
           each value hash having two keys: "cookie", whose value is the cookie value, and
           "session_factor", whose value is the session factors for that cookie.  Returns a hash
           in the same structure as the COOKIES argument.

       remote_user ([USER])
           Retrieve or set the remote username, as determined by some external authentication
           system such as Apache authentication.  This is not currently used.

       request_token ([TOKEN])
           Retrieve or set the request token from the WebAuth application server that prompted
           this authentication request.  This must be set to create a valid WebKDC::WebRequest.

       service_token ([TOKEN])
           Retrieve or set the service token provided by the WebAuth application server, which
           contains the key used to decrypt the request token.  This must be set to create a
           valid WebKDC::WebRequest.

       factor_token ([TOKEN])
           Retrieve or set the factor token, which contains a token given to the user's device in
           an earlier login to denote a successful multifactor login with that device.

       user ([USER])
           Retrieve or set the username of the authenticating user.  This must be set to create a
           valid WebKDC::WebRequest.

AUTHOR

       Roland Schemers and Russ Allbery <eagle@eyrie.org>

SEE ALSO

       WebKDC(3)

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