ABE4JWT

Source code showcasing the ABE4JWT framework. If you landed here you probably read the paper Attribute-Based Encryption for Access Control in Cloud Ecosystems describing our protocol. If not, we suggest to read the paper for more details.

This project implements a simple interactive website featured with a protected area where users can login and post their messages. The different components used to implement the site are three independent nodes taking the roles of the Authorization Server (AS, implementing login&consent), the Client (website front-end) and the Resource Server (RS, storage service, a simple database exposing RESTful API). Users log in through their own identity provider (i.e., their email provider), while an independent Authorization Server releases tokens containing permissions to perform various actions (post comments, modify user’s profile settings, etc). The Client uses the acquired credentials to perform persistence operations on the Resource Server. The challenge-response authentication needed by our protocol is implemented through a Reverse Proxy which forwards the Client requests to the Resource Server. The Reverse Proxy handles all the burden of the cryptographic procedure leaving unmodified the legacy RS interface.

This source code has been adapted from the work by Baeldung describing how to implement an OpenID Connect 1.0 server flow in J2EE.

NOTE: The code is intended for educational purpose only (production code may need additional security features).

Install OpenABE first!

OpenABE is probably the most advanced and performant ABE framework at the time of writing available and it is written in C++. Our code relies on it, so the OpenABE framework needs to be installed on the machine running the AS, the Proxy and the Client (the RS does not need any crypto). The following procedure should work on any Linux compatible machine.

apt-get -y update && apt-get -y --no-install-recommends install sudo && git clone https://github.com/zeutro/openabe && cd openabe && . ./env && ./deps/install_pkgs.sh && export LD_LIBRARY_PATH=: && make && make install && . ./env"

Note that 'sudo' should be available on the machine as it is invoked from an OpenABE library installation script. Note also that variable LD_LIBRARY_PATH is first overridden by the script and then unset for installing the mail library.

Using Maven on localhost (as command line or in Eclipse)

First, source environment for OpenABE:

cd openabe
. ./env

Download and compile each component using Git and Maven:

	git clone https://github.com/netgroup/abe4jwt.git && \
	cd abe4jwt/jwt && mvn clean install && \ 
	cd ../as && mvn clean package && \
	cd ../rs && mvn clean package && \
	cd ../client && mvn clean package && \
	cd ../proxy && mvn clean package

Copy file key.p12 in the AS project folder, and run the AS:

cd abe4jwt/as/
cp ../key.p12 .
export IGNORE_HOSTNAME_VERIFIER=true
mvn liberty:stop liberty:run-server

Test the server by visiting the following URL in a browser:

https://localhost:9443/as/jwk

(ABE Master Public Key generated by the server will be displayed)

On a second shell, copy key.p12 in the 'proxy' project folder and run the Proxy by Maven command:

cd abe4jwt/proxy/
cp ../key.p12 .
export IGNORE_HOSTNAME_VERIFIER=true
mvn -e jetty:stop jetty:run

Check if the ABE Master Public Key is correctly retrieved from the server (will be printed on the consolle).

On a third shell run the RS by Maven command:

cd abe4jwt/rs/
mvn liberty:stop clean package liberty:run-server

On a fourth shell, copy key.p12 in the 'client' project folder and run the Client by Maven command:

cd abe4jwt/client/
cp ../key.p12 .
export IGNORE_HOSTNAME_VERIFIER=true
mvn liberty:stop clean package liberty:run-server

Check whether the Client has started by visiting the following URL:

https://localhost:9543/client/index.jsp

NOTE for Eclipse users: If you run under Eclipse, after importing the whole project from GitHub, import each component as a single mvn project: right click on each component folder > Import > Existing MVN project.

SSL Keys

AS, Client and Proxy use the same self-signed key and the corresponding certificate, which is stored in the same keystore named "key.p12" and protected by the password "initial". The keystore key.p12 is used, by default, as a truststore too, so any server trusts each other. RS does not need SSL, as it is is assumed to be in a safe network zone and only accessed through the reverse Proxy.

NOTE: Before starting each server, you should just copy file key.p12 into topmost folder of each projext (AS, Client and Proxy). The respective configuration files (Liberty configuration file server.xml for AS and Client, and jetty-ssl-context.xml for the Proxy) expect to find it there.

##Alternative truststore settings ## Alternative truststore settings consists in exporting the server certificate from key.p12 and importing it in java default truststore as follows (assumed the default truststore is /opt/java/openjdk/lib/security/cacerts and has password 'changeit'):

	keytool -exportcert -v -keystore abe4jwt-pri/key.p12 -storepass initial -alias default -file fake-pwd.crt && \
	keytool -importcert -v -trustcacerts -keystore /opt/java/openjdk/lib/security/cacerts -storepass changeit -alias fake-play-with-docker -file fake-pwd.crt -noprompt

Ignore Hostname verification!

IMPORTANT: If you don't know the exact IP address where your servers will run, or you don't provide it in your server certificate, you must skip hostname verification, setting the following environment variable for each of the three servers using HTTPS (AS, Client, Proxy).

export IGNORE_HOSTNAME_VERIFIER=true

Default configuration file

Other than pom.xml in the topmost folder and in each subfolder (AS, Client, Proxy, RS), each component has its own default properties that may be configured. This is usually not needed if you run all servers on the same host (using the localhost interface). However, you may need to be aware of these specific settings to extend the framework or make some other hacks.

AS The AS may use Sendgrid.com API to mail users. After obtaining your own key from Sendgrid, configure Sendgrid properties from resource file:

resources/META-INF/microprofile-config.properties.

If you do not configure this file, the server will not send any email, but will show on the screen the access code just after the user submits his own email address (this is for testing purpose only!). Default assigned HTTPS port for the AS is 9443 (see pom.xml).

Proxy You may need to configure the file

/webapp/WEB-INF/web.xml

with the following parameters:

authority --> the url assigned to the AS
proxyTo --> the url assigned to the RS
protected --> resources under this prefix needs to be protected by authorization

Please read Jetty documentation if you need to alter further parameters (see jetty*.xml files contained in the project 'resources' folder). Default assigned HTTPS port for the Proxy is 8443 (see jetty.xml).

Client Configure resources/META-INF/microprofile-config.properties to provide the url assigned to the AS and to the RS. Default assigned HTTPS port for the Client is 9543 (see pom.xml).

If you each server on different machines (or Docker containers)...

There is no need to alter default configuration files above, this can be done easily, by defining two environment variables. If defined, these variables will override the related settings in resources/META-INF/microprofile-config.properties (for the Client) and in /webapp/WEB-INF/web.xml (for the Proxy).

You just need to inform:

the Proxy about the URI assigned to the AS:

export AS_URI=<HTTP URL where your AS is running>

the Client about the URIs assigned to both the AS and the Proxy:

export AS_URI=<HTTP URL where your AS is running>
export PROXY_URI=<HTTP URL where your Proxy is running>

For example, to run in a Docker environment use:

export IGNORE_HOSTNAME_VERIFIER=true
export AS_URI=<https url to the AS>
export PROXY_URI=<https url to the Proxy>
docker run -dp 9443:9443 -e IGNORE_HOSTNAME_VERIFIER as
docker run -dp 8443:8443 -e IGNORE_HOSTNAME_VERIFIER -e AS_URI -e proxy
docker run -dp 9543:9543 -e IGNORE_HOSTNAME_VERIFIER -e AS_URI -e PROXY_URI client

And check whether the Client has started by visiting the following URL:

https://<IP where your Client is running>:9543/client/index.jsp

Have fun!

ROMA (Italy), January 2021

--Giovanni Bartolomeo

netgroup / abe4jwt