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.
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:
-
Download the Bloom server package here.
-
Unzip the downloaded Bloom server package. Look for a web asset bundle in the form of
neo4j-bloom-<version>-assets.zip
. -
Unzip and setup the files in the bundle to be served from your web server.
-
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. -
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 |
For more information about Neo4j clusters, see Operations Manual → Clustering.
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