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) is hosted by your own web server, while the Bloom server plugin is still installed on the Neo4j database (whether single instance or clustered setup). The Bloom client connects to the Neo4j database, either via serving a json file containing the Neo4j database discovery URL, or by using a connectURL parameter. This is described in detail further on.

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. The Bloom plugin is still required to be installed on the Neo4j database server, see Installing server plugin for more information. Follow the steps below to set up the Bloom client:

  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 not include a discovery.json file, but one needs to be created when needed in order 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.

Another way to connect Bloom to a Neo4j server is to use a connectURL parameter. The server address need to be properly URL escaped and in the following format: https://[bloom-hosted-location]/index.html?connectURL=[database.server.address].

For an instance hosted in Aura, for example, the connectURL could look like this:

https://bloom.neo4j.io/index.html?connectURL=neo4j%2Bs%3A%2F%2Fcf0e20ef.databases.neo4j.io

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.

Supported providers at this time include OpenID Connect (OIDC) OAuth 2.0 providers:

  • Google

  • Keycloak

  • Microsoft Azure AD

  • Okta

Bloom supports authorization code flow with PKCE.

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.

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 NEO4J_PLUGINS='["bloom"]' \ (1)
  neo4j:enterprise
1 this was previously NEO4JLABS_PLUGINS which is deprecated in Neo4j 5 and to be removed in a future version.

Installing Bloom server in a database cluster

When setting up Bloom server in a database cluster, the Bloom plugin needs to be added to all servers hosting the database, including both primary and secondary (if any) hostings.

In addition, if the cluster is also used to host the Bloom client, then pick any one server within the cluster 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:

http://<cluster-instance-address>:<http-port>/bloom/

https://<cluster-instance-address>:<https-port>/bloom/

If you intend to use the Graph Data Science Library with Bloom in a database cluster, Bloom must connect to a server in the cluster that has the GDS Library plugin.

This can be achieved by connecting to the Bloom plugin on the server that has the GDS Library plugin installed to host Bloom, or by specifying the appropriate server in the cluster with a connectURL parameter.

The server that has GDS installed is likely hosting the database in secondary mode and thus any write operations need to be routed to a database primary in the cluster. For this to be possible, server-side routing needs to be enabled, please see Operations Manual → Server-side routing and Graph Data Science Manual → GDS with Neo4j cluster for more information.

For more information about Neo4j clusters, see Operations Manual → Clustering.

bloom in a neo4j cluster

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