Hela: Hidden Extended Layer for Authentication is a Java library that implements the OpenID Connect (OIDC) / OAUth2 protocols at the client side. It therefor allows a Java / Jakarta EE application to integrate users' SSO authentication feature in a very simple way:

• Simple addition of the library jar file (eg through a Maven dependency).
• Very few modifications of the target application's code if not already done.
• Simple setting through a configuration file.

Despite the complexity of the behaviors implemented to ensure security, Hela's code remains simple to approach and study its content. This guarantees total transparency about its operation, which is absolutely necessary for such critical feature

Hela is intended for use by applications that are compliants with « Jakarta ee security » framework. It uses also the Servlet initialization mechanism. According to those conditions it is compliant with any target application that runs in an environment that supports Jakarta security and Servlets. Most known application servers and containers like Apache Tomcat, Apache TomEE or Wildfly supports such conditions. The version of Java required for execution is at least version 17.

The target application users must be managed by an OIDC/OAuth2 compliant authentication server. This server can be internal to an organization or public on the Internet.

• Google
• Yahoo!
• Linkedin
• PayPal

As examples, provides this service for users who have chosen to create accounts from them. However, since the user account informations of these service providers is not verified, their possible use for a real application must take this into account.

The use of Hela by a target application requires three conditions:

1. The binary file of the library must be integrated into the application.
2. The application must be registered by the authentication server as needed by the protocol.
3. The required settings in must be done correctly in the configuration file authentication.conf.

Since the target application is a Java web-based, the first requirement is the need to incorporate the Hela binary package, hela-x.x.x.jar, into a folder that is part of the classpath. The usual location for this is the application's «WEB-INF/lib» folder, but maybe another one.

The authentication server need to know how communicate with Hela. This is the concern of the second condition, the application must be registered. For the security concern the exchanges must be authenticated, usually through an identifier and a password. Registration allows you to exchange these settings.

Finally to allows Hela uses those settings to communicate with authentication server, It is necessary to provide them through the configuration file.

The usual way to integrate Hela library with the target application is to insert a dependency to the construction of this application. This insertion varies according to the tool used. For Maven, as an example which should be adapted for other tools, just add the «pom.xml»'s dependency:

This insertion assumes that Maven has access to a repository that contains the Hela binary package at build time. Otherwise, the construction fails. Two possibilities exist to ensure this access. Either retrieve the Hela sources, build it and install it in the local Maven repository. Or, reference in the «pom.xml» file of the target application the repository that contains this binary as follows:

The authentication server used must provide a feature for registering client applications. This feature is available through an API or through an interface that allows registration. As an example, Google provides a registration console (access requires authentication with a Google account) that allows you to perform this operation. The screen shot below shows an example window of this console where the settings of a registered test client application appear.

To made registration you must provide some informations, mainly:

• The type of the application, needs to be «web type».
• A redirect URL that allows the server to respond to Hela requests. Use: <APPLICATION_URL>/authcallback.
• The preferred security algorithm, preffer RS256. Allowed by all servers and usually default taken.
• The server to server authentication method may be « Client secret basic » (id + password). Allowed by all servers and sufficient for most use cases.

Other optional parameters can be provided to improve the end user information. These settings may include URLs to access information documentation, an application logo or other. The used server documentation should be revieweded for further details. At the end of the registration, the authentication server must provide an identifier and a password which make it possible to secure the communications. This provided data corresponds, respectively, to the client_id and client_secret parameters of the OIDC specifications.

In the application side, the following configuration example uses the Google authentication server.

Obviously, you must change the endpoint settings if you don't use Google provider. The value of protected_path parameter provide the part of application URI that must be protected through authentication. eg: /* mean you protect the whole of application.

When user is successfully authenticated, Hela creates an instance of the net.meddeb.oauth.hela.User class with informations provided by the authentication server. Then It stores this instance in the session. Informations stored:

• Unique identifier managed by the authentication server.
• Last name and first name.
• E-mail address and status of this address: verified or not.

Hela does not ask for any additional information outside the ID. It is his default behavior. You can change that by adding those parameters to the configuration file.

Depending on the server used, the userinfo_endpoint parameter should be omitted for better performance. Some servers fill those informations in the token and there are no need to make an additional call to this endpoint. See the used authentication server documents for that. The value of the userinfo_scope maybe a comma separated list of scopes supported by authentication server. profile and email should be well supported by most servers. The recovery of those informations is subject to the consent of the user during authentication. If the user does not allow access, authentication fails. Use carefully this parameter and ask access to information only if they are really usefull.

The processing to be carried out after the return of authentication information by the server must make it possible to check whether the current user is authenticated or not. If the user is authenticated, it must be possible to obtain his recovered data. To do this, use a code, in the target application, like this one:

This code example should be used in the appropriate location (s) of the target application's code to verify authentication or retrieve user's informations.