Package org.apache.sling.api.auth

# Interface Authenticator

@ProviderType public interface Authenticator
The `Authenticator` interface defines the service interface which may be used by applications to enforce requests to be authenticated (see `login(HttpServletRequest, HttpServletResponse)`) or to end enforced authentication (see `logout(HttpServletRequest, HttpServletResponse)` ). As such this service may be looked at as the functionality to enable applications to log users in and out.

A very simple login script (using ESP here) could be implemented like this:

     var auth = sling.getService(org.apache.sling.api.auth.Authenticator);
     if (auth != null) {
         try {
             auth.login(request, response);
             return; // we are done here
         } catch (e) {
             // probably NoAuthenticationHandler exception
         }
     }
     // Authenticator service is missing or no AuthenticationHandler
     ... do whatever you want to for error handling ...

Likewise implementing a logout script (ESP, too) is equally simple:

     if (request.authType) {
         // not logged in at all, no need to logout
     } else {
         var auth = sling.getService(org.apache.sling.api.auth.Authenticator);
         if (auth != null) {
             auth.logout(request, response);
         } else {
             // handle the case of no Authenticator service to logout with
         }
     }

This interface is not intended to be implemented by applications but may be used to initiate the authentication process form a request processing servlet or script.

Since:
  1.0 (Sling API Bundle 2.1.0)

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`LOGIN_RESOURCE`
Name of the request attribute which may be set by the application to indicate to the `login(HttpServletRequest, HttpServletResponse)` method to which resource access should actually be authenticated.
`static final String`
`SERVICE_NAME`
The name under which this service is registered.

## Method Summary

Modifier and Type
Method
Description
`void`
`login(@NotNull jakarta.servlet.http.HttpServletRequest request, @NotNull jakarta.servlet.http.HttpServletResponse response)`
Tries to login a request user for the current request.
`void`
`login(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
Deprecated.
Use `login(HttpServletRequest, HttpServletResponse)` instead.
`void`
`logout(@NotNull jakarta.servlet.http.HttpServletRequest request, @NotNull jakarta.servlet.http.HttpServletResponse response)`
Logs out if the current request is authenticated.
`void`
`logout(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
Deprecated.
Use `logout(HttpServletRequest, HttpServletResponse)` instead.

## Field Details

### SERVICE_NAME

static final String SERVICE_NAME
The name under which this service is registered.

### LOGIN_RESOURCE

static final String LOGIN_RESOURCE
Name of the request attribute which may be set by the application to indicate to the `login(HttpServletRequest, HttpServletResponse)` method to which resource access should actually be authenticated. If this request attribute is not set or is the empty string, the `login(HttpServletRequest, HttpServletResponse)` method uses the request path info (`HttpServletRequest.getPathInfo()`) method to find the resource to which to authenticate access.

This request attribute can be used by frontend servlets/scripts which call into `login(HttpServletRequest, HttpServletResponse)` on behalf of users.

See Also:
  - Constant Field Values

## Method Details

### login

void login(@NotNull @NotNull jakarta.servlet.http.HttpServletRequest request, @NotNull @NotNull jakarta.servlet.http.HttpServletResponse response)
Tries to login a request user for the current request.

To identify the resource to which access should be authenticated the ``resource`` request attribute is considered. If the request attribute is not set the request path info ( `HttpServletRequest.getPathInfo()`) is used.

This method must be called on an uncommitted response since the implementation may want to reset the response to start the authentication process with a clean response. If the response is already committed an `IllegalStateException` is thrown.

After this method has finished, request processing should be terminated and the response be considered committed and finished unless the `NoAuthenticationHandlerException` exception is thrown in which case no response has been sent to the client.

Parameters:
  `request` - The object representing the client request.
  `response` - The object representing the response to the client.
Throws:
  `NoAuthenticationHandlerException` - If the service cannot find a way to authenticate a request user.
  `IllegalStateException` - If the response has already been committed.
Since:
  1.1.0

### login

@Deprecated void login(@NotNull javax.servlet.http.HttpServletRequest request, @NotNull javax.servlet.http.HttpServletResponse response)
Deprecated.
Use `login(HttpServletRequest, HttpServletResponse)` instead.
Tries to login a request user for the current request.

Parameters:
  `request` - The object representing the client request.
  `response` - The object representing the response to the client.
Throws:
  `NoAuthenticationHandlerException` - If the service cannot find a way to authenticate a request user.
  `IllegalStateException` - If the response has already been committed.

### logout

void logout(@NotNull @NotNull jakarta.servlet.http.HttpServletRequest request, @NotNull @NotNull jakarta.servlet.http.HttpServletResponse response)
Logs out if the current request is authenticated.

This method must be called on an uncommitted response since the implementation may want to reset the response to restart the authentication process with a clean response. If the response is already committed an `IllegalStateException` is thrown.

After this method has finished, request processing should be terminated and the response be considered committed and finished.

Parameters:
  `request` - The object representing the client request.
  `response` - The object representing the response to the client.
Throws:
  `IllegalStateException` - If the response has already been committed.
Since:
  1.1.0

### logout

@Deprecated void logout(@NotNull javax.servlet.http.HttpServletRequest request, @NotNull javax.servlet.http.HttpServletResponse response)
Deprecated.
Use `logout(HttpServletRequest, HttpServletResponse)` instead.
Logs out if the current request is authenticated.

Parameters:
  `request` - The object representing the client request.
  `response` - The object representing the response to the client.
Throws:
  `IllegalStateException` - If the response has already been committed.