Package org.silverpeas.core.web.rs

Class HTTPAuthentication

  • @Service
public class HTTPAuthentication
extends Object
    An HTTP authentication mechanism for Silverpeas to allow users to consume the Silverpeas Web API. It implements the authentication process for any incoming HTTPs requests targeting a web resource of the Silverpeas Web API. This HTTP request can be as well an explicit authentication ask as a Silverpeas API consume. The HTTP request is expected either to contain the HTTP header Authorization valued with the authentication scheme and the user credentials as expected by the IETF RFC 2617 or to target a web resource URI with the query parameter access_token (see IETF RFC 6750).

    Actually, Silverpeas supports for its web resources two HTTP authentication schemes: the Basic one (covered by the IETF RFC 2617) and the Bearer one (covered by the IETF RFC 6750). The API token of the users must be passed with the Bearer scheme to access the REST API of Silverpeas. Any other authentication schemes throws a WebApplicationException exception with the status Response.Status.UNAUTHORIZED.

    The two ways to authenticate with Silverpeas are for different purposes:

    • The authentication by credentials (carried by the Basic authentication scheme) is for opening a session in Silverpeas in order to perform one or several Web API invocations. The user behind will be then counted as a connected user.
    • The authentication by the API token (carried either by the query parameter access_token or by the Bearer authentication scheme) is for a one-shot API call and for doing it doesn't require a session to be opened. It is usually used by external tools interacting with Silverpeas in the behalf of the user.

    The failure of the authentication throws a WebApplicationException exception with the status Response.Status.UNAUTHORIZED.

    Author:
    mmoquillon

    • Constructor Detail

      • HTTPAuthentication

        protected HTTPAuthentication()

    • Method Detail

      • authenticate

        public SessionInfo authenticate​(HTTPAuthentication.AuthenticationContext context)
        Authenticates the user that sent the incoming HTTP request according to the specified authentication context.

        The context is defined for the incoming HTTP request and for the HTTP response to send. The HTTP request contains the elements required to authenticate the user at the source of the request. The mandatory element is either the Authorization HTTP header that must be valued with an authentication scheme and with the credentials of the user, or the access_token URI query parameter, or the access_token form-encoded body parameter.

        A WebApplicationException is thrown with the status Response.Status.UNAUTHORIZED in the following cases:

        • No Authentication header and no access_token parameter;
        • The authentication scheme isn't supported;
        • The credentials passed in the Authentication header are invalid;
        • The user API token passed in the access_token parameter is invalid;
        • The user account in Silverpeas isn't in a valid state (blocked, deactivated, ...).

        If the authentication process succeeds, then a session is created and returned. For a basic authentication scheme, the session comes from a session opening in Silverpeas by the SessionManagement subsystem and its unique identifier is set in the UserPrivilegeValidation.HTTP_SESSIONKEY header of the HTTP response; the session life will span over several HTTP requests and it will be closed either explicitly or by the default session timeout. For a bearer authentication scheme and for an authentication from the access_token parameter, the session is just created for the specific incoming request and will expire at the end of it; this is why the session identifier is not sent back to the user with the HTTP response.

        At the end of the authentication, the context is alimented with the user credentials and with the authentication scheme that were fetched from the HTTP request. They can then be retrieved for further operation by the invoker of this method. In the case of an authentication from the access_token parameter, the authentication scheme in the context is set as a bearer authentication scheme.

        Parameters:
        context - the context of the authentication with the HTTP request and with the HTTP response.
        Returns:
        the created session for the request if the authentication succeeds or throws a WebApplicationException with as status Response.Status.UNAUTHORIZED.