OpenCCT is a Java module / component that implements the OpenID Connect protocol on the client side. As such, it allows a Java / JEE application that uses it to integrate a user SSO authentication feature in a very simple way:
- Simple addition of the binary module (eg by a Maven dependency).
- Very few modifications of the target application's code.
- Simple setting by configuration file.
Despite the relative complexity of the features implemented to ensure security, the OpenCCT code remains simple to address and study the content. It guarantees total transparency as to its operation.
A Java / JEE web application that uses OpenCCT must integrate the component's binary package. It must also include the appropriate settings in its web deployment descriptor (web.xml file). This setting provides the link between the target application and the component via the HTTP filter provided by OpenCCT. Under these conditions, if a user wishes to access the protected area of the application (step 1):
- If it is not already authenticated to the authentication server: it will be redirected to this server to perform connection (step 2).
- If it is already authenticated to the authentication server: it will be declared as connected.
In both cases, exchanges between OpenCCT and the authentication server (step 3) make it possible to confirm the identity of the user, retrieve information about this identity and make them available to the application.
OpenCCT is a free and opensource software. It is licensed under the GNU GPL v3+ license.
OpenCCT is intended for use by applications developed for the Apache TomEE application server. Although tested only with this application server, this component should work without any problem with any Java / JEE web-based application run by a JEE 7 compatible application server. The version of Java required for execution is at least version 1.8.
The users to authenticate for the target application must be managed by an OppenID Connect compliant authentication server. This server can be internal to an organization or on the Internet:
As examples, provide this service for users who have chosen to create accounts from them. However, since the user account information of these service providers is not verified, their possible use for a real application must take this into account.The use of OpenCCT in a target application requires three conditions:
- The binary file of the component must be integrated into the application.
- The application must be registered with the authentication server as needed by the protocol.
- The required settings in the application's «web.xml» file must be done correctly.
Since the target application is a JEE web-based, the first requirement is the need to incorporate the OpenCCT binary package, opencct-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.
The authentication server need to know how communicate with OpenCCT. 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 OpenCCT uses those settings to communicate with authentication server, It is necessary to provide them through the standard file «web.xml» of the application.
The conventional way to integrate OpenCCT with the target application is to insert a dependency on 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:
<groupId>net.meddeb.oauth</groupId>
<artifactId>opencct</artifactId>
<version>0.9.0</version>>
</dependency>
This insertion assumes that Maven has access to a repository that contains the OpenCCT binary package at build time. Otherwise, the construction fails. Two possibilities exist to ensure this access. Either retrieve the OpenCCT 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:
<repository>
<id>meddeb-net</id>
<name>Meddeb.net Repository</name>
<url>http://meddeb.net/maven</url>
</repository>
</repositories>
The authentication server used must provide a feature for registering client applications. This feature is available primarily 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.
You must provide some informations for the registration, mainly:
- The type of the application, needs to be «web type».
- A redirect URL that allows the server to respond to OpenCCT requests. Use: <APPLICATION_URL>/authcallback.
- The preferred security algorithm must be RS256. Allowed by all servers and usually default taken.
- The server to server authentication method must 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 OpenID Connect specifications.
In the application side, the following configuration example uses the Google authentication server.
<filter-name>auth-filter</filter-name>
<filter-class>net.meddeb.oauth.opencct.AuthFilter</filter-class>
<init-param>
<param-name>login-endpoint</param-name>
<param-value>https://accounts.google.com/o/oauth2/v2/auth</param-value>
</init-param>
<init-param>
<param-name>token-endpoint</param-name>
<param-value>https://www.googleapis.com/oauth2/v4/token</param-value>
</init-param>
<init-param>
<param-name>oauth-id</param-name>
<param-value>CLIENT_ID_PROVIDED_BY_GOOGLE_REGISTRATION</param-value>
</init-param>
<init-param>
<param-name>oauth-secret</param-name>
<param-value>CLIENT_SECRET_PROVIDED_BY_GOOGLE_REGISTRATION</param-value>
</init-param>
</filter>
<filter-name>auth-filter</filter-name>
<url-pattern>/URI_TO_PROTECT</url-pattern>
</filter-mapping>
Two parameters have to be added in the «web.xml» web deployment descriptor file of the target application. The first parameter «filter» must declare the «AuthFilter» filter provided by OpenCCT, as well as the parameters of the authentication server used. The second parameter «filter-mapping» indicates the protected area of the application, which should only be accessible to authenticated users. Naturally, the values used in the example should be adapted to the specific use case by doing the following:
- Replace, if necessary, the values of the «login-endpoint» and «token-endpoint» parameters if the server used is other than Google's one.
- Replace the values of the «oauth-id» and «oauth-secret» parameters by the values provided at application's registration time.
- Replace the value of the «url-pattern» of «filter-mapping» parameter by the desired path. eg: /* to protect the entire application.
During exchanges between OpenCCT and the authentication server, errors may occur. In particular, the server may become unavailable or identity theft attempts may occur. In this case, and by default, the following error message is displayed.
This behavior may be modified by the introduction of the filter's optional parameter: «error-path». This parameter must indicate a path for the custom management of this error. In this case, the provision of the management code for this custom path is the responsibility of the target application. This option allows, for example, to add to the custom error page a link to a public access location (without authentication).
...
<init-param>
<param-name>error-path</param-name>
<param-value>/custom_error</param-value>
</init-param>
</filter>
If the user, redirected to the authentication server, is authenticated, OpenCCT creates an instance of the net.meddeb.oauth.opencct.User class with this user's data. Then store this instance in the session. This class is used to enter the following data:
- Unique identifier managed by the authentication server.
- Last name and first name.
- E-mail address and status of this address: verified or not.
By default only the unique identifier is retrieved by OpenCCT but this behavior can be modified by the introduction of the filter's optional parameter oauth-scope. This parameter can be added to the «web.xml» file as follows:
...
<init-param>
<param-name>oauth-scope</param-name>
<param-value>PE</param-value>
</init-param>
</filter>
The value of this parameter must be a combination of the letters E and P: one of the two or both at the same time. «P» allows to retrieve the first and last name of the user and «E» his email address. The recovery of this data is subject to the consent of the user during authentication. If the user does not allow access to this data, authentication fails. For this, it's necessary to use carefully this parameter and to ask access to a data only if it's really essential.
On the other hand, some authentication servers require the call to an additional information point to retrieve this data: Userinfo endpoint. You should take information about this for the used server. If this is the case, you must add the userinfo-endpoint parameter in the file «web.xml». The value of this parameter is the URL of this access point and which the server documentation used must provide.
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:
String userID = "";
if (loggedUser == null) {
// User isn't authenticated
} else userID = loggedUser.getUid(); // to obtain user ID
This code example should be used in the appropriate place (s) of the target application's code to verify authentication or retrieve user's data.