@ConsumerType
public interface AuthenticationHandler
AuthenticationHandler
interface defines the service API used
by the authentication implementation to support plugin various ways of
extracting credentials from the request.Modifier and Type | Interface and Description |
---|---|
static class |
AuthenticationHandler.FAILURE_REASON_CODES
This enum indicates the supported detailed login failure reason codes:
invalid_login : indicates username/password mismatch.
password_expired : indicates password has expired or was never set and
change initial password is enabled
account_locked : the account was disabled or locked
account_not_found : the account was not found (not the same as username password mismatch)
expired_token : the token credentials used have expired
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
FAILURE_REASON
Name of the request attribute which may be set by the
extractCredentials(HttpServletRequest, HttpServletResponse)
method if AuthenticationInfo.FAIL_AUTH is returned. |
static java.lang.String |
FAILURE_REASON_CODE
Name of the request attribute which may be set by the
extractCredentials(HttpServletRequest, HttpServletResponse)
method if AuthenticationInfo.FAIL_AUTH is returned. |
static java.lang.String |
PATH_PROPERTY
The name of the service registration property listing one or more URL
paths for which the authentication handler is to be used.
|
static java.lang.String |
REQUEST_LOGIN_PARAMETER
The request parameter which may be used to explicitly select an
authentication handler by its
type if
authentication will be requested through
requestCredentials(HttpServletRequest, HttpServletResponse) . |
static java.lang.String |
SERVICE_NAME
The name under which an implementation of this interface must be
registered to be used as an authentication handler.
|
static java.lang.String |
TYPE_PROPERTY
The name of the service registration property (single string) providing
the authentication type of authentication handler.
|
Modifier and Type | Method and Description |
---|---|
void |
dropCredentials(javax.servlet.http.HttpServletRequest request,
javax.servlet.http.HttpServletResponse response)
Drops any credential and authentication details from the request and asks
the client to do the same.
|
AuthenticationInfo |
extractCredentials(javax.servlet.http.HttpServletRequest request,
javax.servlet.http.HttpServletResponse response)
Extracts credential data from the request if at all contained.
|
boolean |
requestCredentials(javax.servlet.http.HttpServletRequest request,
javax.servlet.http.HttpServletResponse response)
Requests authentication information from the client.
|
static final java.lang.String SERVICE_NAME
static final java.lang.String PATH_PROPERTY
Each string value may either be an absolute path (e.g. /content) or an absolute URL (e.g. http://thehost/content) to assign the authentication handler to authenticate request for a select virtual host.
Authentication handlers without a path
service registration
property are ignored.
static final java.lang.String TYPE_PROPERTY
authentication type
returned by the
extractCredentials(HttpServletRequest, HttpServletResponse)
method.
This property is optional but allows the client to optionally select the
authentication handler which will actually request credentials upon the
requestCredentials(HttpServletRequest, HttpServletResponse)
method.
REQUEST_LOGIN_PARAMETER
,
Constant Field Valuesstatic final java.lang.String REQUEST_LOGIN_PARAMETER
type
if
authentication will be requested through
requestCredentials(HttpServletRequest, HttpServletResponse)
.static final java.lang.String FAILURE_REASON
extractCredentials(HttpServletRequest, HttpServletResponse)
method if AuthenticationInfo.FAIL_AUTH
is returned.
This result may be used by authentication handlers to inform the user of any failures.
extractCredentials(HttpServletRequest, HttpServletResponse)
,
Constant Field Valuesstatic final java.lang.String FAILURE_REASON_CODE
extractCredentials(HttpServletRequest, HttpServletResponse)
method if AuthenticationInfo.FAIL_AUTH
is returned.
This result may be used by authentication handlers to inform the user of more detailed failure reasons, e.g. "password_expired".
extractCredentials(HttpServletRequest, HttpServletResponse)
,
Constant Field ValuesAuthenticationInfo extractCredentials(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
The method returns any of the following values :
value | description |
---|---|
null
| no user details were contained in the request or the handler is not capable or willing to extract credentials from the request |
AuthenticationInfo.DOING_AUTH
| the handler is in an ongoing authentication transaction with the client. Request processing should be aborted at this stage. |
AuthenticationInfo.FAIL_AUTH
| the handler failed extracting the credentials from the request for
any reason. An example of this result is that credentials are present in
the request but they could not be validated and thus not be used for
request processing. When returning this value, the authentication handler
may also set the FAILURE_REASON request attribute to inform
interested parties (including its own
requestCredentials(HttpServletRequest, HttpServletResponse)
method for the reasons of failure to extract the credentials.
|
AuthenticationInfo object
| The user sent credentials. The returned object contains the credentials as well as the type of authentication transmission employed. |
The method must not request credential information from the client, if they are not found in the request.
The value of PATH_PROPERTY
service registration property value
triggering this call is available as the path
request
attribute. If the service is registered with multiple path values, the
value of the path
request attribute may be used to implement
specific handling.
request
- The request object containing the information for the
authentication.response
- The response object which may be used to send the
information on the request failure to the user.AuthenticationInfo
instance identifying the
request user, AuthenticationInfo.DOING_AUTH
if the
handler is in an authentication transaction with the client or
null if the request does not contain authentication information.
In case of AuthenticationInfo.DOING_AUTH
, the method must
have sent a response indicating that fact to the client.boolean requestCredentials(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws java.io.IOException
true
if the information has been requested and request
processing can be terminated normally. Otherwise the authorization
information could not be requested.
The HttpServletResponse.sendError
methods should not be used
by the implementation because these responses might be post-processed by
the servlet container's error handling infrastructure thus preventing the
correct operation of the authentication handler. To convey a HTTP
response status the HttpServletResponse.setStatus
method
should be used.
The value of PATH_PROPERTY
service registration property value
triggering this call is available as the path
request
attribute. If the service is registered with multiple path values, the
value of the path
request attribute may be used to implement
specific handling.
If the REQUEST_LOGIN_PARAMETER
request parameter is set only
those authentication handlers registered with an authentication type
matching the parameter will be considered for
requesting credentials through this method.
A handler not registered with an authentication
type
will, for backwards compatibility reasons, always be called
ignoring the actual value of the REQUEST_LOGIN_PARAMETER
parameter.
request
- The request object.response
- The response object to which to send the request.true
if the handler is able to send an authentication
inquiry for the given request. false
otherwise.java.io.IOException
- If an error occurs sending the authentication
inquiry to the client.void dropCredentials(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws java.io.IOException
request
- The request object.response
- The response object to which to send the request.java.io.IOException
- If an error occurs asking the client to drop any
authentication traces.Copyright © 2022 The Apache Software Foundation. All rights reserved.