Prerequisites

Before deploying Enterprise Studio, complete the steps on this page to prepare your environment.

Acquire a license key

Enterprise Studio requires a valid license to start. You obtain a license key file from your Neo4j account representative. You then reference this file in config.yaml via license.path (see Configuration → Minimal example).

Configure a Neo4j database for Enterprise Studio

Before deploying Enterprise Studio, you need to configure your Neo4j deployment(s) so that Enterprise Studio can authenticate and authorize users, store internal tool assets, and read data.

Requirements:

  • Neo4j Enterprise Edition 5.26 LTS, 2025.01 or later

  • A service account with the architect role on the Neo4j deployment hosting the tool asset database

  • The HTTP connector enabled on each Neo4j deployment that users will connect to (enabled by default; see Operations Manual → HTTP connector)

  • For Neo4j clusters accessed in reverse proxy mode: session affinity on the load balancer in front of the cluster’s HTTP endpoints (see Set up communication to a Neo4j cluster)

To configure Neo4j for Enterprise Studio, complete the following steps:

1. Create a service account

Enterprise Studio needs a dedicated service account to connect to the tool asset database. Create a user on the Neo4j deployment that will host the tool asset database, and grant it full read/write access:

CREATE USER `tools_service` SET PASSWORD 'changeme' SET PASSWORD CHANGE NOT REQUIRED;
GRANT ROLE architect TO `tools_service`;

Replace 'changeme' with a strong unique password. Do not use the example value in production, default credentials are a common source of security incidents.

The architect role is the most straightforward option because Enterprise Studio creates and manages the tool asset database schema on startup, which requires token creation, and constraint management privileges.

If granting architect is too broad for your environment, you can create a custom role with only the privileges Enterprise Studio requires:

Minimum privileges for the service account

On the Neo4j deployment hosting the tool asset database, run:

CREATE ROLE `studio_service_role` IF NOT EXISTS;

// Read/write access to the tool asset database
GRANT ACCESS ON DATABASE `tools-storage` TO `studio_service_role`;
GRANT MATCH {*} ON GRAPH `tools-storage` TO `studio_service_role`;
GRANT WRITE ON GRAPH `tools-storage` TO `studio_service_role`;

// Schema management on the tool asset database.
// Required at runtime: Enterprise Studio reconciles its constraints and
// indexes on every startup, so these are needed even for a pre-created database.
GRANT CONSTRAINT MANAGEMENT ON DATABASE `tools-storage` TO `studio_service_role`;
GRANT INDEX MANAGEMENT ON DATABASE `tools-storage` TO `studio_service_role`;
GRANT NAME MANAGEMENT ON DATABASE `tools-storage` TO `studio_service_role`;

Then assign the role to the service account instead of architect:

GRANT ROLE `studio_service_role` TO `tools_service`;

Replace tools-storage with the database name you set in assetStore.default.database .

This role does not include any DBMS-level privilege such as CREATE DATABASE: the tool asset database must be created ahead of time (see step 2). The schema-management privileges above are still required at runtime, because Enterprise Studio ensures its constraints and indexes on every startup.

Make note of the credentials. You will need them when configuring Enterprise Studio.

If Enterprise Studio reports database errors at startup, verify that the service account credentials are correct, that authentication is enabled in neo4j.conf, and that the Neo4j server is reachable from the machine running Enterprise Studio.

2. Set up the tool asset database

Enterprise Studio stores its internal data (queries, dashboards, Perspectives, and sharing metadata) in a dedicated Neo4j database called the tool asset database. This database can be placed in an existing DBMS or have its own dedicated machine.

The tool asset database must exist before you start Enterprise Studio. Create it using name that you set in assetStore.default.database or in config.yaml:

CREATE DATABASE `tools-storage`;

This lets the service account run with least privilege, without the DBMS-level CREATE DATABASE privilege (see step 1).

If you point Enterprise Studio at an existing non-empty database, the existing data is ignored.

3. Grant required privileges

Enterprise Studio requires certain privileges for users to enable sharing and tool functionality. Run the following on each Neo4j deployment that users will connect to:

GRANT SHOW CONSTRAINTS ON DATABASES * TO reader;
GRANT SHOW INDEXES ON DATABASES * TO reader;
GRANT SHOW ROLE ON DBMS TO reader;
GRANT SHOW USER ON DBMS TO reader;

SHOW INDEXES and SHOW CONSTRAINTS are required for Bloom to function. SHOW ROLE and SHOW USER are required for tool asset sharing.

4. Configure SSO (optional)

SSO affects Enterprise Studio in two independent ways, and you can set up either one on its own:

  • The service account that Enterprise Studio uses to reach the tool asset database can authenticate with a token from your identity provider instead of a username and password.

  • Regular users signing in through SSO need a local user record before they can be listed individually as sharing recipients.

Service account with SSO

To let the service account authenticate with a token, prepare your identity provider and Neo4j as follows:

  1. Register a confidential client for Enterprise Studio in your identity provider and enable the client credentials grant. Add the client to the group that your Neo4j OIDC provider maps to a database role, and make note of its token endpoint, client ID, and client secret.

  2. Configure an OIDC provider in neo4j.conf that trusts your identity provider, and map the client’s group claim to a database role that holds the privileges the service account needs (the same privileges listed in Create a service account). Neo4j verifies and decodes the token; Enterprise Studio only passes it through. For the full walkthrough, see Configuring Neo4j SSO.

With both in place, point Enterprise Studio at the token endpoint of your identity provider. See Configuration → OIDC authentication.

Regular users with SSO

If you use SSO without requiring local users in your deployment, Enterprise Studio will not be able to list these federated users as individual recipients for sharing resources. While it is still possible to share resources with these users via their assigned roles, individual user sharing is unavailable because Neo4j lacks a local directory record for them.

To allow Enterprise Studio to discover and list individual SSO users, you can mandate that every externally authenticated user has a corresponding local user record inside the database. To require that a local user exists for users logging in through SSO, add this setting to your neo4j.conf:

dbms.security.require_local_user=true

See Operations Manual → Configuration settings for more information about this setting.

Set up communication to a Neo4j cluster

This section is relevant for Enterprise Studio deployments that communicate with Neo4j clusters.

First, decide on a protocol for the deployment uri:

  • http(s) — the preferred method, uses reverse proxy, browsers do not access the database directly. Needs additional setup, as described below.

  • bolt — browsers connect to the database directly. Easier to set up, but the database must be reachable from end users' browsers. See Configuration → Direct client query.

If bolt is chosen, no further setup is required. If http(s) is selected, session affinity must be configured.

Session affinity

In reverse proxy mode, Enterprise Studio forwards queries to Neo4j as Query API requests over HTTP. The tools use explicit transactions, which span multiple HTTP requests. An explicit transaction is held by the cluster member that started it, and all subsequent requests in that transaction must reach the same member. Self-managed Neo4j clusters do not route these requests automatically. If a load balancer distributes them across members, requests fail with the following error:

{
  "errors": [{
    "code": "Neo.ClientError.Request.Invalid",
    "message": "Transaction with Id: \"2b41f8\" was not found. It may have timed out and therefore rolled back or the routing header 'neo4j-cluster-affinity' was not provided."
  }]
}

Failures are intermittent and depend on which member each request reaches.

Session affinity (sticky sessions) must be configured on the load balancer or Service that distributes HTTP traffic between Enterprise Studio and the cluster members.

Kubernetes deployments

To configure session affinity for Neo4j clusters running on Kubernetes, see Operations Manual → Neo4j clusters and session affinity.

Other environments

For clusters outside Kubernetes, configure session affinity on the load balancer or proxy in front of the cluster’s HTTP endpoints:

  1. Select a source IP-based balancing method (also called IP hash, source hashing, or sticky sessions), so that all requests from one Enterprise Studio instance reach the same cluster member.

  2. Apply the configuration to the HTTP(S) ports of all cluster members (default 7474/7473).

To verify the setup, connect to the deployment from Enterprise Studio and run queries. Without session affinity, requests fail intermittently with the error above.

When all steps are completed, proceed to Configuration.