Putting some Gravitee into Neo4j — Part II — go Gravitee

Tom Geudens

6 min readDec 20, 2021

Preamble

I explained the why and what in the first part. Now it is time to get to the how.

You can see there is quite a dance going on.

Your web browser communicates with the Neo4j Web Server.
UI application elements move to your web browser. The Neo4j Web Server does not serve the application itself.
Your web browser communicates with the Gravitee Gateway Server. This is the main part of the dance.
The Gravitee Gateway Server communicates with the identity provider. This may lead to an authentication request.
With the dance complete your web browser can access the database.

In this part I’ll focus on setting up the Gravitee Access Management solution.

Setup

I am going with a single AWS server for the whole architecture. The assumption is that you have access to the ec2-user on that server. Additionally you need the following before we can install Gravitee.

Ports 8092, 8093 and 8094 must be accessible.
DNS name linked to the public ip address of the server. For the rest of the document I’ll assume the DNS name is apollo.yourdomain.io (I like Greek mythology).
Certificate is ready and waiting on the server.

ls -l /home/ec2-user

certificate files

Installation

Installing the Gravitee Access Management solution is simple:

sudo curl -sSL https://bit.ly/install-am-3x | bash

Quite a lot happens after that fancy start. Java is installed. MongoDB is installed. Elasticsearch is installed. A gravitee group and user are created and finally the gateway, api and console application are installed.

In this post I’m not going into further detail on that. You can check everything is running by checking the ports:

sudo ss -lntp

Your next action is to prepare the certificate files for usage. Gravitee uses both the Jetty and the Nginx webserver. For Jetty you need a keystore:

openssl pkcs12 -export \
    -in /home/ec2-user/certificate.crt \
    -inkey /home/ec2-user/private.key \
    -out /home/ec2-user/apollo.yourdomain.io.p12 \
    -name apollo.yourdomain.io \
    -CAfile /home/ec2-user/ca_bundle.crt \
    -caname "ZeroSSL Certificate apollo.yourdomain.io" \
    -password pass:notverysecurekeytool -importkeystore \
   -deststorepass notverysecure \
   -destkeypass notverysecure \
   -deststoretype JKS \
   -srckeystore /home/ec2-user/apollo.yourdomain.io.p12 \
   -srcstoretype JKS \
   -srcstorepass notverysecure \
   -destkeystore /home/ec2-user/apollo.yourdomain.io.jks \
   -alias apollo.yourdomain.io

For Nginx the original format is fine but you do need the full chain of trust in one file:

cat /home/ec2-user/certificate.crt /home/ec2-user/ca_bundle.crt > /home/ec2-user/apollo.yourdomain.io.cert

And then you put everything in place:

sudo mkdir /opt/graviteeio/security
sudo cp /home/ec2-user/apollo.yourdomain.io.cert /opt/graviteeio/security/
sudo cp /home/ec2-user/apollo.yourdomain.io.jks /opt/graviteeio/security/
sudo cp /home/ec2-user/private.key /opt/graviteeio/security/apollo.yourdomain.io.key
sudo chown -R gravitee:gravitee /opt/graviteeio/security
ls -l /opt/graviteeio/security

ready to use

Fix /opt/graviteeio/am/gateway/config/gravitee.yml

http:
  port: 8092
  secured: true
  ssl:
    keystore:
      type: jks
      path: /opt/graviteeio/security/apollo.yourdomain.io.jks
      password: notverysecure
...services:
  core:
    http:
      enabled: false
      port: 18092
...

Fix /opt/graviteeio/am/management-api/config/gravitee.yml

jetty:
  port: 8093
  secured: true
  ssl:
    keystore:
      type: jks
      path: /opt/graviteeio/security/apollo.yourdomain.io.jks
      password: notverysecure
...services:
  core:
    http:
      enabled: false
      port: 18093
...

Fix /opt/graviteeio/am/management-ui/constants.json

{
  "baseURL": "https://apollo.yourdomain.io:8093/management"
}

Fix /etc/nginx/conf.d/graviteeio-am-management-ui.conf

server {
        listen  0.0.0.0:8094 ssl;
        server_name apollo.yourdomain.io;
        ssl_certificate /opt/graviteeio/security/apollo.yourdomain.io.cert;
        ssl_certificate_key /opt/graviteeio/security/apollo.yourdomain.io.key;
        root    /opt/graviteeio/am/management-ui;
        index index.html;location / {
                try_files $uri $uri/ /index.html;
        }
}

Restart the services and verify the ports again (give it a couple of seconds).

sudo systemctl restart graviteeio-am-gateway.service
sudo systemctl restart graviteeio-am-management-api.service
sudo systemctl restart nginx
sudo ss -lntp

Access the gateway url — https://apollo.yourdomain.io:8092 in a web browser. The response should be:
No security domain matches the request URI.
But more importantly this allows you to verify the certificate is in place correctly.

For a final test, access the UI url — https://apollo.yourdomain:8094 in a web browser. The response should be:

Well done. You’ve come quite a way and Gravitee is now running. Time to configure it!

Configuration

The default username / password combination for the AM console is admin / adminadmin.

Instead of going for the obvious button … click Organization settings first. Then scroll down to and select Entrypoints.

An entrypoint is how the application (Neo4j Browser) will contact Gravitee AM. In this Open-source Software setup of Gravitee there is only one possibility. Use the cogwheel to change the url of the default entrypoint to https://apollo.yourdomain.io:8092 and SAVE.

You could now navigate your way back. Instead, select the administrator icon on the top right and … Create domain.

New options appear on screen. Once more, do not do the obvious (despite the bright orange highlighting)! Click the new Settings menu option instead.

A few things need changing. Go through them one by one and make sure to SAVE on every panel:

General → Enable domain → SAVE
Login → User Registration → SAVE
User Accounts → Select the Default Identity Provider in the pull-down-menu → SAVE
Users → Create a new user (yourself for example) … fill out the mandatory fields, make sure to select the Default Identity Provider → Create
Groups → Create a new group … the name should be (lowercase) admin → Create

Next you click the new Applications menu option. Only one option … create a new application.

For the application type you go with Single Page App which fits the Neo4j Browser. You then fill out the form:

Name → neo4jssoapplicationapollo
Redirect URI → https://apollo.yourdomain.io:7473/browser
OAuth2.0 Client ID → neo4jgravitee
OAuth2.0 Client Secret → neo4jgravitee

And Create

Almost there … a few more things need changing for the application:

Identity Providers → Enable → SAVE
Settings → OAuth2.0/OIDC → Scopes → ADD SCOPES

Application level OAuth2.0/OIDC Settings

Add profile, openid, email and groups as scopes then SAVE.

Done. You are done. You can now select the dashboard. Relax for a little while. In the next part you’ll install the Neo4j database and link it up, so don’t expect the lines on the dashboard to start moving yet.

Thoughts

This felt like a lot of work. And I glossed over nearly all of the concepts as well to keep it manageable. If you’ve never done an OAuth or SSO flow before it may not have made a lot of sense. So what did you do?

You set up a broker that can handle SSO authentication flows for you. With configuration only.
You went with the default identity provider (and created a user and group in it), but you could as easily have plugged in an external identity provider such as Google or your organization’s Active Directory, or …
You defined an application that can handle the specific flow that the Neo4j database you are going to install on the same server requires. With configuration only.
…

Yes. It was a lot of work. But nothing compared to what custom building it would entail. You want to understand the concepts to better understand your decisions in the future. For now though … well done!