NAME

       WebKDC::WebKDCException - Exceptions for WebKDC communications

SYNOPSIS

           use WebKDC;
           use WebKDC::WebKDCException;

           eval {
               # ...
               WebKDC::request_token_request($req, $resp);
               # ...
           };
           my $e = $@;
           if (ref $e and $e->isa ('WebKDC::WebKDCException')) {
               # you can call the following methods on a WebKDCException object:
               # $e->status()
               # $e->message()
               # $e->error_code()
               # $e->verbose_message()
           }

DESCRIPTION

       Various WebKDC functions may return a WebKDC::WebKDCException object if anything goes wrong.  This object
       encapsulates various information about the error.

       This module also defines the status codes returned by the WebKDC functions.

CONSTANTS

       The following constants are exported:

       WK_SUCCESS
           This status code never comes back as part of an exception.  It is returned for success.

       WK_ERR_USER_AND_PASS_REQUIRED
           This status code indicates that a function was called that required a username and password. The user
           should be prompted for their username and the function should be called again.

       WK_ERR_LOGIN_FAILED
           This  status  code  indicates  that a function was called that attempted to validate the username and
           password and could not, due to an invalid user or password.  The user should be re-prompted for their
           username/password and the function should be called again.

       WK_ERR_UNRECOVERABLE_ERROR
           This status code indicates that a function was called and an error occurred that can not be recovered
           from.  If you are in the process of attempting to log a user in, you have no choice but to display an
           error message to the user and not prompt again.

       WK_ERR_REQUEST_TOKEN_STALE
           This status code indicates the user took too long to login, and the the request token is too  old  to
           be  used.   The  user  should  be  told  to  retry  the  action  that  caused them to be prompted for
           authentication.

       WK_ERR_WEBAUTH_SERVER_ERROR
           This status code indicates something happened that most likely indicates the WebAuth server that made
           the  request  is  misconfigured  and/or  unauthorized  to  make  the  request.   It  is  similar   to
           WK_ERR_UNRECOVERABLE_ERROR except that the error message to the user should indicate that the problem
           is most likely with the server that redirected them.

       WK_ERR_LOGIN_FORCED
           This  status  code indicates that a function was called that required a username and password even if
           single sign-on credentials were available.  The user  should  be  prompted  for  their  username  and
           password and the function should be called again with that data.

       WK_ERR_USER_REJECTED
           This  status code indicates that the authenticated principal was rejected by the WebKDC configuration
           (usually because WebKdcPermittedRealms was set and the realm of the principal wasn't in that list).

       WK_ERR_CREDS_EXPIRED
           This status code indicates that the  principal  we  attempted  to  authenticate  to  has  an  expired
           password.   If  possible, the user should be prompted to change their password and then the operation
           retried.

       WK_ERR_MULTIFACTOR_REQUIRED
           This status code indicates that authentication was successful but that authentication with  a  second
           factor  is  also  required.   The  user should be prompted for their second factor and then the login
           reattempted with that information plus the returned proxy tokens.

       WK_ERR_MULTIFACTOR_UNAVAILABLE
           This status code indicates that the desired site requires multifactor, but the  user  does  not  have
           multifactor configured or does not have the correct second factor to authenticate to that site.

       WK_ERR_LOGIN_REJECT
           This  status  code  indicates  that  this user is not allowed to log on to that site at this time for
           security reasons.  This is a transitory error; the user may be permitted to  authenticate  later,  or
           from a different location.  This error message is used for rejected logins from particular locations,
           logins that appear to be from a compromised account, or accounts that have been locked out due to too
           many failed logins.

       WK_ERR_LOA_UNAVAILABLE
           This status code indicates that the site requested a Level of Assurance for the user's authentication
           that is higher than this user can provide, either because of insufficient proof of identity available
           to the system or due to an insufficiently strong configured authentication method.

       WK_ERR_AUTH_REJECTED
           This  user  is not permitted to authenticate to the desired destination WebAuth Application Server at
           this time.  This may be due to local  policy,  security  limitations  placed  on  the  user,  missing
           prerequisite  actions  that the user must take (such as training or a usage agreement), or some other
           local factor.

       WK_ERR_AUTH_REPLAY
           This authentication attempt appears to be a replay.  Replays may be rejected as a security measure to
           protect against people who walked away with a browser open and left the WebLogin form  submission  in
           the browser cache.

       WK_ERR_AUTH_LOCKOUT
           This  account  has  been locked out due to too many unsuccessful login attempts.  The login should be
           retried later.

CLASS METHODS

       new (STATUS, MESSAGE[, ERROR[, DATA]])
           Create a new WebKDC::WebKDCException object.  STATUS is one of the  status  constants  defined  above
           other  than  WK_SUCCESS.   MESSAGE  is  the error message for the exception.  ERROR, if present, is a
           protocol error code that caused the exception.  DATA,  if  present,  is  additional  data  about  the
           exception, currently used to carry the HTML error message to display to the user if one is available.

INSTANCE METHODS

       data ()
           Returns the additional exception data (if there was any).

       error_code ()
           Returns the WebKDC protocol errorCode (if there was one).

       message ()
           Returns the error message that was passed to the constructor.

       status ()
           Returns  the WebKDC::WebKDCException status code for the exception, which will be one of the WK_ERR_*
           codes.

       verbose_message ()
           This method returns a verbose error message, which consists of the  status  code,  message,  and  any
           error code.

       to_string ()
           This  method  is  called  if  the  exception  is  used  as  a  string.   It  is  a wrapper around the
           verbose_message method.

AUTHOR

       Roland Schemers and Russ Allbery <rra@stanford.edu>

SEE ALSO

       WebKDC(3)

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

perl v5.18.1                                       2013-10-22                       WebKDC::WebKDCException(3pm)