focal (3) WebKDC::WebKDCException.3pm.gz

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.

       WK_ERR_LOGIN_TIMEOUT
           There was a timeout while attempting to log in.  The login should be retried, though multiple errors
           could mean a problem outside of WebAuth.

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 <eagle@eyrie.org>

SEE ALSO

       WebKDC(3)

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