ASL HTTP Front End

From Gcube Wiki
Jump to: navigation, search


ASL HTTP Front End is a part of the system's "Integration and Interoperability Framework". It offers HTTP APIs to expose a subset of system's JAVA API facilities, in order to support a higher level calls. It's a set of servlets that intercept HTTP calls and operate on top of the JAVA libraries. The objective of this framework layer is to provide access points that cover the functionality of ASL services, such as the session handling, the searching of information and the authentication. Such clients are components external or internal to the system that have come into an agreement with the HTTP services implementers about the data/format they are expecting and the response they will be giving out, or will be implementing standard HTTP specifications offered by the HTTP front end of the system. Current ASL HTTP Front End is the result of the reformation of a previous version of Application Service's Layer HTTP API that was mandated by the need for formalization and extensibility of the framework.

Reference Architecture

The architecture of this layer is driven by the needs for provision of access to resources that fall under specific functional categories. More specifically, it consists of a set of servlets for which each access point covers a series of services. In the existing implementation, those components cover mostly the fundamental functionality needed by the end-users. Extensions in the existing framework can either provide access to resources of other functional categories or offer a standard HTTP based API adhering to a widely used specification, to support interoperability needs. All the components within the existing framework use common functionalities implemented for caller authentication.

External Architecture

HTTP Front End aims at providing access to higher level functionality, frequently compliant to web standards. Most probably each access point covers a series of services and requires interaction with lower level components in the system architecture to achieve resources aggregation. The system layer that offers this kind of access to multiple services as well as a session mechanism that can be exploited within different applications’ interactions is the ASL (Application Services Layer). Therefore, the HTTP layer is logically placed above it and offers a subset of its functionality. In the image below, the framework of ‘layers’ of gCube system is depicted, clarifying the place of this set of interfaces in the system architecture.

WP11 FrameworkLayers.jpg

Internal Architecture

HTTP Front End is composed by web applications based on Java Servlet technology. By revisiting the architecture of the existing implementation of ASL HTTP Front End, the need for extensibility drives the decision for division of the only application into a set of smaller applications that can proliferate within the framework. An HTTP application in the new version of this layer can logically group related functionalities. The grouped functionalities address demanding tasks that need access to multiple services and a sequence of logical steps to complete. In the context of this decision, the architecture of the existing implementation consists of the following new system components:


Aggregates mandated functionality to perform a gCube search

    • listing of searchable collections
    • retrieval of information about searchable collections
    • listing of search types
    • listing of languages
    • listing of searchable fields
    • submission of search query
    • retrieval of search results


Aggregates functionality for accessing gCube content

    • retrieval of information about content
    • retrieval of content
    • retrieval of metadata
    • retrieval of thumbnails


ASL HTTP Infrastructure Login component aggregates needed functionality for logging into the system and in an infrastructure scope. It allows the clients to retrieve the necessary information for logging into the system and it uses the internal ASL Session mechanism to prevent the need for passing the credentials every time in subsequent calls. The authentication of the user is performed through communication with ASL authentication facility that is independent from specific applications and authentication providers and uses a pluggable mechanism to specify "authentication modules". The set of servlets consisting this component provide the following functionalities:

  • user authentication – logging in Infrastructure
  • listing of infrastructure scopes
  • logging in an Infrastructure scope
Logging into the System

Login servlet receives the user’s credential (username – password) and communicates ASL authentication mechanism in order to authenticate the user. It makes use of status codes and HTTP headers to manage the security policy. In case of denied credentials it returns an SC_UNAUTHORIZED status code to the client. Both BASIC and Form – based authentication methods are implemented to this end. In order to login, using ASL HTTP API, a GET or POST request needs to be made to the servlet with the name “Login”.

With the basic authorization scheme, the Authorization header contains the string of "username:password" encoded in Base64. For example, the username of "webmaster" with the password "try2guess" is sent in an Authorization header with the value:


Here is an example of a URL for a login request: http://hostname:port/aslHttpInfrastructureLogin/Login

ASL HTTP makes use of the internal ASL Session mechanism that is based on the built in session tracking mechanisms of the servlets. Consequently, the user’s session can be tracked either with the use of persistent cookies, where the session ID is saved on the client in a cookie called JSESSIONID, or with URL rewriting. URL rewriting can be used by clients that don’t support cookies by sending the sessionID as part of a rewritten URL, encoded using a jsessionid path parameter. The session is returned once the user logs in the system inside an XML response, and all the following URL – encoded requests must contain it. By offering a session tracking mechanism, ASL allows the user to make subsequent requests without having to log in every time he asks for a resource.

An example of an XML response returning the session id is presented bellow:

<?xml version="1.0" encoding="UTF-8"?>
Logging in an Infrastructure Scope

All calls to the underlying infrastructure are scoped. Consequently, a user interacting with HTTP Front End has to login to a scope before trying to access resources. This is done by visiting the LoginInfrastructureScope servlet and passing as parameter the scope to enter. LoginInfrastructureScope servlet interacts with ASLCore to log the user and keep this information in the internal ASLSession to prevent the need for passing this information in all subsequent calls of the application. When anonymous access is used, there is no need for logging in to an infrastructure scope, but all the requests need to be scoped by adding one more ‘scope’ parameter to the request.

Here is an example of a URL for a login scope request: http://hostname:port/aslHttpInfrastructureLogin/LoginScope?scope=.....


ASL_HTTP_InfrastructureLogin application must be deployed in the same container as any other application of the HTTP Layer that needs to be accessible in 'named' mode (see #Authentication_Modes Authentication Modes section).

Specifications Implementations

Implementations of HTTP Standards placed in separate application components

    • ASL_HTTP_OAIPMH (under redevelopment)

Implementations offering common functionality to all HTTP applications

Based on the functionality, each servlet overrides the doGet and doPost methods of HttpServlet

Authentication Modes

Since many Web Standards require open access, HTTP Front End supports two modes for accessing the system resources: Authenticated and Open Access:

  • Named

In authenticated mode, the user needs to login to the system and to an Infrastructure scope and continue interacting with the application over HTTP without having to pass the contextual information in every request submitted. Moreover, he/she can use personalized benefits in the cases of functionalities interacting with gCube personalization services.

  • Open Access

A servlet can also support Open Access to the underlying resources . For the user interacting with the application, this means that the user has to pass the ‘scope’ parameter in every call it submits to the application.

ASL HTTP Access Management

The servlets implementers do not have to write code for any of the user authentication modes. This common functionality can be directly accessed through the aslHttpAccessManagement component, on which all servlets of the HTTP Front End should depend. Before processing the user’s call, the servlet implementer needs to authenticate the user by passing the HTTPServletRequest object to the asl authentication component for HTTP and the identifier of the operation the user asked to perform, i.e:

private static final String operationID = "Search";
AuthenticationResponse authenticationResp = CallAuthenticationManager.authenticateCall(request, operationID);

The operationID is a string that identifies the operation and is used in a generic configuration for the management of Open Access. This configuration controls the open access permission per scope and per operation through HTTP. Therefore, if the user has not previously logged in the System, the Open Access configuration for the requested scope and for the particular operation is checked. The operationId should be a static final variable declared for every operation (or group of operations) in every servlet. As a response, the servlet implementer gets back an AuthenticationResponse object, from which he can retrieve whether the user was authenticated. If the user was authenticated, the userId can be retrieved from the returned object and if not, one can retrieve the message indicating what went wrong. For example:

AuthenticationResponse authenticationResp = CallAuthenticationManager.authenticateCall(session, scopeParameterValue, operationID);
if (!authenticationResp.isAuthenticated()) {
	response.sendError(401, authenticationResp.getUnauthorizedErrorMessage());
String username = authenticationResp.getUserId();