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 publisher 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)

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 publisher 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 publisher role is the simplest option because Enterprise Studio creates and manages the tool asset database schema on startup, which requires token creation, and constraint management privileges.

If granting publisher 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 publisher:

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 config.yaml.

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)

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.

When all steps are completed, proceed to Configuration.