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