Package org.apache.sling.auth.core.spi

# Interface AuthenticationHandler

All Known Implementing Classes:
  `AbstractAuthenticationHandler`

@ConsumerType public interface AuthenticationHandler
The `AuthenticationHandler` interface defines the service API used by the authentication implementation to support plugin various ways of extracting credentials from the request.

> Important: This interface is deprecated. Use `JakartaAuthenticationHandler` instead. This interface is not directly marked as deprecated as the inner enum `AuthenticationHandler.FAILURE_REASON_CODES` is not deprecated! This interface is deprecated since package version 1.3.0.

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static enum`
`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

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`FAILURE_REASON`
Deprecated.
Use `JakartaAuthenticationHandler`
`static final String`
`FAILURE_REASON_CODE`
Deprecated.
Use `JakartaAuthenticationHandler`
`static final String`
`PATH_PROPERTY`
Deprecated.
Use `JakartaAuthenticationHandler`
`static final String`
`REQUEST_LOGIN_PARAMETER`
Deprecated.
Use `JakartaAuthenticationHandler`
`static final String`
`SERVICE_NAME`
Deprecated.
Use `JakartaAuthenticationHandler`
`static final String`
`TYPE_PROPERTY`
Deprecated.
Use `JakartaAuthenticationHandler`

## Method Summary

Modifier and Type
Method
Description
`void`
`dropCredentials(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
Deprecated.
Use `JakartaAuthenticationHandler`
`AuthenticationInfo`
`extractCredentials(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
Deprecated.
Use `JakartaAuthenticationHandler`
`boolean`
`requestCredentials(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
Deprecated.
Use `JakartaAuthenticationHandler`

## Field Details

### SERVICE_NAME

@Deprecated(since="1.3.0") static final String SERVICE_NAME
Deprecated.
Use `JakartaAuthenticationHandler`
The name under which an implementation of this interface must be registered to be used as an authentication handler.

See Also:
  - Constant Field Values

### PATH_PROPERTY

@Deprecated(since="1.3.0") static final String PATH_PROPERTY
Deprecated.
Use `JakartaAuthenticationHandler`
The name of the service registration property listing one or more URL paths for which the authentication handler is to be used. The property may be a single string value or an array of strings or a Collection of strings.

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.

See Also:
  - Constant Field Values

### TYPE_PROPERTY

@Deprecated(since="1.3.0") static final String TYPE_PROPERTY
Deprecated.
Use `JakartaAuthenticationHandler`
The name of the service registration property (single string) providing the authentication type of authentication handler. This is the same value as will be returned as the `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.

See Also:
  - `REQUEST_LOGIN_PARAMETER`
  - Constant Field Values

### REQUEST_LOGIN_PARAMETER

@Deprecated(since="1.3.0") static final String REQUEST_LOGIN_PARAMETER
Deprecated.
Use `JakartaAuthenticationHandler`
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)`.

See Also:
  - `requestCredentials(HttpServletRequest, HttpServletResponse)`
  - `TYPE_PROPERTY`
  - Constant Field Values

### FAILURE_REASON

@Deprecated(since="1.3.0") static final String FAILURE_REASON
Deprecated.
Use `JakartaAuthenticationHandler`
Name of the request attribute which may be set by the `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.

Since:
  1.0.2 (Bundle version 1.0.4)
See Also:
  - `extractCredentials(HttpServletRequest, HttpServletResponse)`
  - Constant Field Values

### FAILURE_REASON_CODE

@Deprecated(since="1.3.0") static final String FAILURE_REASON_CODE
Deprecated.
Use `JakartaAuthenticationHandler`
Name of the request attribute which may be set by the `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".

Since:
  1.1.0
See Also:
  - `extractCredentials(HttpServletRequest, HttpServletResponse)`
  - Constant Field Values

## Method Details

### extractCredentials

@Deprecated(since="1.3.0") AuthenticationInfo extractCredentials(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Deprecated.
Use `JakartaAuthenticationHandler`
Extracts credential data from the request if at all contained.

The method returns any of the following values :

Extracted Information
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.

Parameters:
  `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.
Returns:
  A valid `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.

### requestCredentials

@Deprecated(since="1.3.0") boolean requestCredentials(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws IOException
Deprecated.
Use `JakartaAuthenticationHandler`
Requests authentication information from the client. Returns `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.

Parameters:
  `request` - The request object.
  `response` - The response object to which to send the request.
Returns:
  `true` if the handler is able to send an authentication inquiry for the given request. `false` otherwise.
Throws:
  `IOException` - If an error occurs sending the authentication inquiry to the client.

### dropCredentials

@Deprecated(since="1.3.0") void dropCredentials(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws IOException
Deprecated.
Use `JakartaAuthenticationHandler`
Drops any credential and authentication details from the request and asks the client to do the same.

Parameters:
  `request` - The request object.
  `response` - The response object to which to send the request.
Throws:
  `IOException` - If an error occurs asking the client to drop any authentication traces.