Authentication schemes can be either request or connection based. The former are
expected to provide an authorization response with each request message while the latter
is executed only once and applies to the underlying connection for its entire life span.
Care must be taken when re-using connections authorized through a connection based
authentication scheme and they may carry a particular security context and be authorized
for a particular user identity. It is important that such schemes always provide
the user identity they represent through the getPrincipal() method.
Authentication scheme are expected to transition through a series of standard phases or states.
Authentication scheme starts off its life cycle with no context and no specific state.
The processChallenge(AuthChallenge, HttpContext) method is called to
process an authentication challenge received either from the target server or a proxy.
The authentication scheme transitions to CHALLENGED state and is expected to validate
the token passed to it as a parameter and initialize its internal state based on
challenge details. Standard authentication schemes are expected to provide a realm
attribute in the challenge. getRealm() can be called to obtain an identifier
of the realm that requires authorization.
Once the challenge has been fully processed the isResponseReady(HttpHost,
CredentialsProvider, HttpContext) method to determine whether the scheme is capable of
generating a authorization response based on its current state and it holds user credentials
required to do so. If this method returns false the authentication is considered
to be in FAILED state and no authorization response. Otherwise the scheme is considered
to be in RESPONSE_READY state.
Once the scheme is ready to respond to the challenge the generateAuthResponse(
HttpHost, HttpRequest, HttpContext) method to generate a response token, which will
be sent to the opposite endpoint in the subsequent request message.
Certain non-standard schemes may involve multiple challenge / response exchanges to
fully establish a shared context and complete the authentication process. Authentication
schemes are required to return true isChallengeComplete() once the
handshake is considered complete.
The authentication scheme is considered successfully completed and in SUCCESS state if the opposite endpoint accepts the request message containing the authorization response and responds with a message indicating no authentication failure . If the opposite endpoint sends status code 401 or 407 in response to a request message containing the terminal authorization response, the scheme is considered unsuccessful and in FAILED state.
| Modifier and Type | Method and Description |
|---|---|
| public String | Returns: authorization headerThe request being authenticated request, HttpContext HTTP context context)Generates an authorization response based on the current state. |
| public String | Returns: the name of the given authentication schemeReturns textual designation of the given authentication scheme. |
| public Principal | Returns: user principalReturns |
| public String | |
| public boolean | Returns: true if the authentication process has been completed,
false otherwise.Authentication process may involve a series of challenge-response exchanges. |
| public boolean | Returns: true if the scheme is connection based, false
if the scheme is request based.Determines if the authentication scheme is expected to provide an authorization response on a per connection basis instead of the standard per request basis |
| public boolean | Returns: true if an authorization response can be generated and
the authentication handshake can proceed, false otherwise.The credentials to be used for authentication credentialsProvider, HttpContext HTTP context context)Determines whether or not an authorization response can be generated based on the actual authentication state. |
| public void | processChallenge(AuthChallenge
the auth challenge authChallenge, HttpContext HTTP context context)Processes the given auth challenge. |
| generateAuthResponse | back to summary |
|---|---|
| public String generateAuthResponse(HttpHost host, HttpRequest request, HttpContext context) throws AuthenticationException Generates an authorization response based on the current state. Some authentication
schemes may need to load user credentials required to generate an authorization
response from a
| |
| getName | back to summary |
|---|---|
| public String getName() Returns textual designation of the given authentication scheme.
| |
| getPrincipal | back to summary |
|---|---|
| public Principal getPrincipal() Returns
| |
| getRealm | back to summary |
|---|---|
| public String getRealm() Returns authentication realm. If the concept of an authentication
realm is not applicable to the given authentication scheme, returns
| |
| isChallengeComplete | back to summary |
|---|---|
| public boolean isChallengeComplete() Authentication process may involve a series of challenge-response exchanges. This method tests if the authorization process has been fully completed (either successfully or unsuccessfully), that is, all the required authorization challenges have been processed in their entirety.
| |
| isConnectionBased | back to summary |
|---|---|
| public boolean isConnectionBased() Determines if the authentication scheme is expected to provide an authorization response on a per connection basis instead of the standard per request basis
| |
| isResponseReady | back to summary |
|---|---|
| public boolean isResponseReady(HttpHost host, CredentialsProvider credentialsProvider, HttpContext context) throws AuthenticationException Determines whether or not an authorization response can be generated based on the actual authentication state. Generally the outcome of this method will depend upon availability of user credentials necessary to produce an authorization response.
| |
| processChallenge | back to summary |
|---|---|
| public void processChallenge(AuthChallenge authChallenge, HttpContext context) throws MalformedChallengeException Processes the given auth challenge. Some authentication schemes may involve multiple challenge-response exchanges. Such schemes must be able to maintain internal state when dealing with sequential challenges
| |