Advanced installation and configuration

Bloom web app hosted in a separate web server

You may want to host the Bloom client on a separate web server, instead of on the Neo4j database server. This may be desirable for security reasons, or for load balancing reasons to separate the types of traffic directed at different types of servers. In this case, the Bloom client UI (provided as a separate package) will be hosted by your own web server, while the Bloom server plugin will still get installed on the Neo4j database (whether single instance or clustered setup).

web server hosted bloom client

For scenarios where you want to host Bloom client on a web server separate from the Neo4j database server, the Bloom client UI is available as a web asset bundle. Follow the steps below to set it up:

  1. Download the Bloom server package here.

  2. Unzip the downloaded Bloom server package. Look for a web asset bundle in the form of neo4j-bloom-<version>-assets.zip.

  3. Unzip and setup the files in the bundle to be served from your web server.

  4. Serve a json file containing Neo4j database discovery URL, which the Bloom client uses to connect to the intended Neo4j database server. The discovery URL is expected in the following format and saved as discovery.json in the root folder of your web server.

    {
    	"bolt" : "bolt://<neo4j-database-server-address>:<bolt-port>"
    }

    The asset bundle provided does include a discovery.json file. Modify the file provided to specify the correct Neo4j server and port information.

  5. Users should be able to access Bloom by loading the provided index.html in a web browser using your configured web server path.

Web server configuration

Neo4j has no specific recommendations about what web server to use for hosting the Bloom assets. Since it’s only serving static files it could be any web server that could be configured to do so (for example Apache, nginx, IIS). The only requirement is that it can handle the number of users, and thus the number of requests, you have. Bloom will make in the order of 10:s of requests per user per session.

If you have configured your Neo4j instance to only accept secured Bolt connections, you need to configure the web server to serve the assets over https and make sure the needed TLS certificates are available. Otherwise, Bloom may be unable to connect to Neo4j in many web browsers because of security policies that forbid mixing secured and unsecured connections.

This is an example configuration for the nginx web server:

user       www www;
worker_processes  1;  # If this nginx instance is the only thing running on this machine this can be set to number of cores

error_log  logs/error.log;
error_log  logs/error.log  notice;
error_log  logs/error.log  info;

pid        logs/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  my-bloom-domain;

        location / {
            root   /path/to/bloom/asset/files;
            index  index.html;
        }
    }

    # HTTPS server
    #
    #server {
    #    listen       443 ssl;
    #    server_name  my-bloom-domain;

    #    ssl_certificate      cert.pem;
    #    ssl_certificate_key  cert.key;

    #    ssl_session_cache    shared:SSL:1m;
    #    ssl_session_timeout  5m;

    #    ssl_ciphers  HIGH:!aNULL:!MD5;
    #    ssl_prefer_server_ciphers  on;

    #    location / {
    #        root   /path/to/bloom/asset/files;
    #        index  index.html;
    #    }
    #}
}

Using Bloom with LDAP authentication

In order to use Bloom with a Neo4j installation that uses LDAP authentication, Neo4j needs to be configured to use both native and LDAP authentication simultaneously. This is because the perspective sharing feature of Bloom requires the ability to list all the roles that are configured, and this is not possible when only using LDAP.

Note that Bloom does not support Neo4j 3.x databases. Use the following configuration for all installations with Neo4j 4.x and 5:

dbms.security.authentication_providers=native,ldap
dbms.security.authorization_providers=native,ldap

LDAP Example Scenario

Say the following users are defined in LDAP:

User Attributes

cn=Homer

memberOf: cn=bloom_group_1

memberOf: cn=bloom_reader

cn=Marge

memberOf: cn=bloom_group_2

memberOf: cn=bloom_reader

cn=Lisa

memberOf: cn=bloom_admin

The group to role mapping can be configured in neo4j.conf as follows:

dbms.security.ldap.authorization.group_to_role_mapping=   \
 "cn=bloom_group_1,dc=example,dc=com" = role_1;           \
 "cn=bloom_group_2,dc=example,dc=com" = role_2;           \
 "cn=bloom_admin,dc=example,dc=com"   = admin;            \
 "cn=bloom_reader,dc=example,dc=com"  = reader

Finally, the roles role_1 and role_2 need to be created in the database (by using the dbms.security.createRole procedure).

Remember to authorize all the roles who need Bloom access to the neo4j.bloom.authorization_role (with Neo4j 4.x)/dbms.bloom.authorization_role (with Neo4j 5) configuration property as described in the Installing server plugin section.

It should now be possible to log into Bloom with the user Lisa and create two perspectives, say Nuclear waste and Painting. If Lisa then assigns the Nuclear waste perspective to role_1 and Painting to role_2, the user Homer will get the Nuclear waste perspective when he logs in, but Marge will get the Painting perspective. See Operations Manual → LDAP Integration to learn more about LDAP support in Neo4j.

Bloom Single Sign-On (SSO)

Neo4j Bloom provides support for Single Sign-On (SSO) providers. This is an Enterprise feature and requires specific configuration and a (self-hosted) Neo4j Server v4.4 and later. Additionally, you need a compatible SSO provider (local or external) already configured. For more information on the configuration, see Operations Manual → OIDC configuration settings.

For deployments other than with self-hosted Neo4j Server v4.4+, SSO can be configured with a separate OAuth plugin which requires engagement from Professional Services. See https://neo4j.com/professional-services/ for more information about Professional Services.

Supported providers at this time include OpenID Connect (OIDC) OAuth 2.0 providers Google, Keycloak, Microsoft Azure AD, and Okta. Bloom supports two authorization flows:

  • Authorization Code flow with PKCE

  • Implicit flow

It is strongly advised to use PKCE to ensure security. Further information about OpenID Connect and OAuth can be found at https://openid.net/connect/.

Security information should always be exchanged with encrypted transport, and therefore HTTPS should be used. Mixed HTTP/HTTPS flows for single sign-on are not supported.

Once your SSO provider is configured, you need to configure Neo4j to use OpenID Connect. This is done by updating the neo4j.conf file according to the instructions in Operations Manual → Configure Neo4j to use OpenId Connect.

Make sure to avoid duplicate entries in the neo4j.conf file.

Bloom needs to be aware of the identity providers available for use. When used with Neo4j v4.4+, this is specified the neo4j.conf file, as described above.

Deployments that use an earlier version of Neo4j require a separate OAuth plugin and assistance from Professional Services, as mentioned previously. However, in such cases, identity providers can be specified in two ways:

  • Specify a URL parameter discoveryURL that specifies a URL to a json file containing the SSO providers. Example for Bloom: https://<bloom-server-host>:<http-port>?discoveryURL=https://webhost.com/public/discovery.json

  • Add information to Bloom’s discovery.json file located in your Bloom installation at the web root directory. Keep in mind that the discovery.json must be tailored to your SSO solution.

Bloom prioritizes in the following order, in case of conflicting data:

  1. discoveryURL

  2. neo4j.conf

  3. discovery.json

Deep links also work with SSO authentication, where available.

Installing Bloom in a Docker container

It is possible to install Bloom in a Docker container as well, using the standard Neo4j Enterprise Docker image. You can find all Neo4j Docker images here. For more information about the Neo4j Docker image, please see Operations Manual → Using the Neo4j Docker image.

Installing the Bloom plugin in a Docker container is only available with Neo4j Enterprise version 4.2.3 or later.

The Neo4j Docker image includes a startup script which automatically downloads and lets you configure the Bloom plugin at runtime, see Operations Manual → Configure Neo4j Labs plugins for more information.

Using the Bloom plugin requires a license, which can be provided as a shared volume in your Docker container:

docker run -it --rm \
  --publish=7474:7474 --publish=7687:7687 \
  -v $HOME/bloom.license:/licenses/bloom.license \
  --env NEO4J_AUTH=neo4j/test \
  --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
  --env NEO4JLABS_PLUGINS='["bloom"]' \
  neo4j:enterprise

Installing Bloom server in a database cluster

When setting up Bloom server in a database causal cluster, the Bloom plugin needs to be added to all the database instances, including core instances and read replicas.

In addition, if the cluster is also used to host the Bloom client, then pick any one instance within the cluster (all instances can serve Bloom) to be the designated Bloom-serving instance. Make sure HTTP or HTTPS is enabled and have users use that particular instance’s address in the URL. For example:

Neo4j 4.x:
http://<cluster-instance-address>:<http-port>/bloom/

https://<cluster-instance-address>:<https-port>/bloom/
bloom in a neo4j cluster

If the Bloom client connects to a read replica in a cluster setup, write operations such as editing of a perspective, editing properties or creating nodes and relationships, fail. This is only applicable in versions of Neo4j prior to 5.

Settings for Product Analytics

In the Settings drawer, you can control whether or not you want to share telemetry data from Bloom with Neo4j. However, these options are disabled if you run Bloom from Neo4j Desktop or Aura since consent settings are inherited from those systems. Additionally, when used with Neo4j v4.4 and later, consent settings can be specified in the neo4j.conf file. When used with Neo4j 5, you include client.allow_telemetry as such:

client.allow_telemetry=true|false

With Neo4j 4.4, instead include clients.allow_telemetry:

clients.allow_telemetry=true|false