webkdc(3pm) [debian man page]

WebKDC(3pm)						User Contributed Perl Documentation					       WebKDC(3pm)

NAME

       WebKDC - functions to support the WebKDC

SYNOPSIS

	 use WebAuth;
	 use WebKDC;
	 use WebKDC::Exception;
	 use WebKDC::WebRequest;
	 use WebKDC::WebResponse;

	 my ($status, $exception) =
		WebKDC::make_request_token_request($req, $resp);

DESCRIPTION

       WebKDC is a set of convenience functions built on top of mod WebAuth to implement the WebKDC.

       All functions have the potential to throw either a WebKDC::WebKDCException or WebAuth::Exception.

EXPORT

       None

FUNCTIONS

       make_request_token_request(req,resp)
	     ($status, $e) = WebKDC::make_request_token_request($req, $resp);

	   Used to handle an incoming request token. It should be used in the following fashion:

	     my $req = new WebKDC::WebRequest;
	     my $resp = new WebKDC::WebResponse;

	     # if the user just submitted their username/password, include them
	     if ($username && $password) {
	       $req->user($username);
	       $req->pass($password);
	     }

	     # pass in any proxy-tokens we have from a cookies
	     # i.e., enumerate through all cookies that start with webauth_wpt
	     # and put them into a hash:
	     # $cookies = { "webauth_wpt_krb5" => $cookie_value }

	     $req->proxy_cookies($cookies);

	     # $req_token_str and $service_token_str would normally get
	     # passed in via query/post parameters

	     $req->request_token($req_token_str);
	     $req->service_token($service_token_str);

	     my ($status, $e) = WebKDC::make_request_token_request($req, $resp);

	     # for all these cases, check if $resp->proxy_cookies() has any
	     # proxy cookies we need to update when sending back a page to
	     # the browser

	     if ($status == WK_SUCCESS) {
		# ok, request successful
	     } elsif ($status == WK_ERR_USER_AND_PASS_REQUIRED
		      || $status == WK_LOGIN_FORCED) {
		# prompt for user/pass
	     } elsif ($status == WK_ERR_LOGIN_FAILED) {
		# supplied user/pass was invalid, try again
	     } else {
	       # use this if/elsif/else to pick the error message
	       if ($status == WK_ERR_UNRECOVERABLE_ERROR) {
		  # something nasty happened.
	       } elsif ($status == WK_ERR_REQUEST_TOKEN_STATLE) {
		  # user took too long to login, original request token is stale
	       } elsif ($status == WK_ERR_WEBAUTH_SERVER_ERROR) {
		  # like WK_ERR_UNRECOVERABLE_ERROR, but indicates the error
		  # most likely is due to the webauth server making the request,
	       } else {
		  # treat like WK_ERROR_UNRECOVERABLE ERROR
	       }
	       # display the error message and don't prompt anymore
	     }

AUTHOR

       Roland Schemers (schemers@stanford.edu)

SEE ALSO

       WebKDC::WebKDCException WebKDC::Token WebKDC::WebRequest WebKDC::WebRespsonse WebAuth.

perl v5.14.2							    2012-04-25							       WebKDC(3pm)

WebKDC::WebKDCException(3pm)				User Contributed Perl Documentation			      WebKDC::WebKDCException(3pm)

NAME

       WebKDC::WebKDCException - exceptions for WebKDC

SYNOPSIS

	 use WebKDC;
	 use WebKDC::WebKDCException;

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

DESCRIPTION

       The various WebKDC functions can all throw WebKDCException if something wrong happens.

EXPORT

       The following constants are exported:

	 WK_SUCCESS
	 WK_ERR_USER_AND_PASS_REQUIRED
	 WK_ERR_LOGIN_FAILED
	 WK_ERR_UNRECOVERABLE_ERROR
	 WK_ERR_REQUEST_TOKEN_STATLE
	 WK_ERR_WEBAUTH_SERVER_ERROR
	 WK_ERR_LOGIN_FORCED
	 WK_ERR_USER_REJECTED
	 WK_ERR_CREDS_EXPIRED
	 WK_ERR_MULTIFACTOR_REQUIRED
	 WK_ERR_MULTIFACTOR_UNAVAILABLE
	 WK_ERR_LOGIN_REJECTED
	 WK_ERR_LOA_UNAVAILABLE

       WK_SUCCESS
	   This status code never comes back as part of an exception, though it might be returned by a function that uses these status codes as
	   return values.

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

       WK_ERR_WEBAUTH_SERVER_ERROR
	   This status code indicates something happened that most likely indicates the webauth server that made the request is mis-configured
	   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.

       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.

METHODS and FUNCTIONS
       match($exception[, $status])
	   This class function (not a method) returns true if the given $exception is a WebKDC::WebKDCException. If $status is specified, then
	   $exception->status() will also be compared to $status.

       new(status, message, wrapped_exception)
	   This method is used to created new WebKDC::WebKDCException objects.

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

       message()
	   This method returns the error message that was used in the constructor.

       error_code()
	   This method returns the WebKDC errorCode (if there was one).

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

	   The verbose_message method is also called if the exception is used as a string.

AUTHOR

       Roland Schemers (schemers@stanford.edu)

SEE ALSO

       WebKDC.

perl v5.14.2							    2012-04-25					      WebKDC::WebKDCException(3pm)