Configuration

Enterprise Studio is configured through a config.yaml file. This file is included as a template in the binary distribution package, or built dynamically when using Docker or Kubernetes. Any setting can also be supplied with a NES_* environment variable; see Environment variable overrides.

Minimal example

This is an illustrative minimal configuration that uses basic authentication for the asset store. For production, use OIDC authentication instead, as described in OIDC authentication.

Enterprise Studio validates its configuration at startup and exits immediately if any required setting is missing. Ensure your configuration contains at least the following settings before first launch:

Config file (config.yaml)

version: 1
kind: neo4j-enterprise-studio-config

license:
  path: /licenses/nes.license          (1)

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687    (2)
    database: tools-storage            (3)
    authentication:
      basic:
        username: my-service-user      (4)
        password: my-service-password  (5)

neo4jDeployments:
  mydeployment:                        (6)
    name: My Neo4j                     (7)
    uri: http://my-neo4j-host:7474     (8)

1	Path to the Enterprise Studio license file. A valid license is required for Enterprise Studio to start.
2	URI of the Neo4j instance where Enterprise Studio stores its internal data.
3	Database on that instance to use for storage.
4	Service account user for asset storage.
5	Password for that user. For production, use a Secrets Manager (`passwordFrom`) or an environment variable; see Security → Secrets management.
6	Unique identifier for this deployment (letters and digits only).
7	Human-readable label for the deployment.
8	Endpoint of the Neo4j instance that end users query through Enterprise Studio.

Environment file

The same minimal configuration can be expressed as an environment file (.env):

NES_server_port=8080
NES_license_path=/licenses/nes.license
NES_assetStore_default_uri=neo4j://my-neo4j-host:7687
NES_assetStore_default_database=tools-storage
NES_assetStore_default_authentication_basic_username=my-service-user
NES_assetStore_default_authentication_basic_password=my-service-password
NES_neo4jDeployments_mydeployment_name=My Neo4j
NES_neo4jDeployments_mydeployment_uri=http://my-neo4j-host:7474

Pass this file to Docker with the --env-file flag:

docker run -p 8080:8080 --env-file .env \
  -v /your/path/to/licenses:/licenses \
  neo4j/enterprise-studio

See Environment variable overrides for the full naming scheme.

Asset store

Enterprise Studio persists tool assets (dashboards, saved queries, Perspectives) in a dedicated Neo4j database. It connects to this database with a dedicated service account, configured under assetStore.default:

database: Name of the database used for storage. This database must already exist — create it before starting Enterprise Studio (see Prerequisites → Set up the tool asset database).
authentication: Authentication method the server uses to connect to the storage database. Configure exactly one method block: basic (username/password), oidc (OAuth 2.0 client-credentials grant), or none (no authentication).

Basic authentication

The service account signs in with a Neo4j username and password:

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage
    authentication:
      basic:
        username: tools_service
        password: secret

See Prerequisites → Create a service account for creating this user and granting it the required privileges. For supplying the password outside the configuration file, see Security → Secrets management.

OIDC authentication

The service account can authenticate with a bearer token instead of a username and password. Enterprise Studio requests the token from your identity provider using the OAuth 2.0 client credentials grant, so no interactive login takes place. It fetches the token when the server starts and refreshes it automatically before it expires.

This requires a confidential client in your identity provider and a matching OIDC provider in neo4j.conf. See Prerequisites → Service account with SSO for setting these up.

With that in place, point assetStore.default.authentication.oidc at the token endpoint of your identity provider:

assetStore:
  default:
    uri: neo4j+s://my-neo4j-host:7687                   (1)
    database: tools-storage
    authentication:
      oidc:
        tokenUrl: https://idp.example.com/oauth2/token  (2)
        clientId: studio-storage-sa                     (3)
        clientSecret: change-me                         (4)
        scopes: []                                      (5)

1	Use an encrypted scheme such as `neo4j+s://` or `bolt+s://` to encrypt the bearer token.
2	Token endpoint of your identity provider. It must use `https`. For Keycloak the format is `https://<host>/realms/<realm>/protocol/openid-connect/token`, and for Microsoft Entra ID it is `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`.
3	Client ID of the confidential client you registered.
4	Client secret. Supply this through an environment variable rather than the file, as shown below.
5	Scopes requested when the token is fetched. This is optional and depends on the provider. Keycloak in client credentials mode needs none, while Microsoft Entra ID expects `[api://<neo4j-app-id>/.default]`.

Supply the client secret through the environment so it is never written to disk:

export NES_assetStore_default_authentication_oidc_clientSecret="your-client-secret"

When you override scopes with an environment variable, pass it as a JSON array, for example NES_assetStore_default_authentication_oidc_scopes='["openid"]'.

To resolve values from Secrets Manager, see Secrets Manager.

For OIDC-based authentication to the storage database, see the OIDC fields in the reference.

Neo4j deployments

A deployment represents a Neo4j instance that end users connect to through Enterprise Studio. At least one deployment must be defined.

By default, Enterprise Studio proxies queries to Neo4j on behalf of the user. In this mode, uri must point to the Neo4j HTTP API (typically port 7474 for HTTP or 7473 for HTTPS), because the server translates user queries into HTTP API requests:

HTTPS (default proxy mode)

neo4jDeployments:
  production:
    name: Production Graph
    uri: https://neo4j-prod:7473

Bolt (direct client query mode)

neo4jDeployments:
  production:
    name: Production Graph
    uri: neo4j+s://neo4j-prod:7687

In proxy mode, uri points to the Neo4j HTTP API (port 7474 / 7473). In direct client query mode, uri uses the Bolt protocol (port 7687). If a deployment uri points to a Neo4j cluster, the HTTP endpoint must provide session affinity, or transactions fail intermittently with Transaction with Id … was not found errors. See Prerequisites → Set up communication to a Neo4j cluster.

Direct client query

Alternatively, you can let the user’s browser connect directly to Neo4j by enabling directClientQuery. In this mode, uri must use a Bolt scheme (neo4j://, neo4j+s://, bolt://, or bolt+s://) because the browser communicates with Neo4j over the Bolt protocol (typically port 7687). You must also provide a publicUri that is reachable from the end user’s browser:

neo4jDeployments:
  production:
    name: Production Graph
    uri: neo4j+s://neo4j-prod:7687
    directClientQuery:
      enabled: true
      publicUri: neo4j+s://neo4j.example.com:7687

uri: Internal URI used by the server. Not required to be publicly accessible.
directClientQuery.publicUri: Public URI that end-user browsers connect to directly. Must be reachable from the user’s network.

Authentication methods

By default, end users can sign in to a deployment with either username/password (basic) or single sign-on through an OIDC identity provider (oidc). Use authentication to restrict which methods are offered in the connection form:

neo4jDeployments:
  production:
    name: Production Graph
    uri: http://neo4j-prod:7474
    authentication:
      basic:
        enabled: false  (1)

1	Disable username/password sign-in.

Each method is enabled by default when omitted.

Authorization

Map Neo4j database users or roles to Enterprise Studio roles to control who can administer or create content. When roleMapping is omitted, Enterprise Studio grants studioAdmin to the Neo4j admin role and studioCreator to the Neo4j PUBLIC role. See Administration for a full walkthrough of role assignment by database role, username, or SSO.

neo4jDeployments:
  production:
    name: Production Graph
    uri: http://neo4j-prod:7474
    authorization:
      roleMapping:
        - role: studioAdmin
          members:
            - kind: databaseRole
              name: admin
        - role: studioCreator
          members:
            - kind: databaseRole
              name: PUBLIC

Server

By default, Enterprise Studio listens on HTTP port 8080.

server:
  port: 9090                            (1)
  https:
    enabled: true                       (2)

1	Change the listen port.
2	Enable HTTPS. Requires TLS certificates; see TLS below.

TLS

Clients send their Neo4j credentials (username/password or bearer token) to Enterprise Studio on every request. Without TLS, those credentials travel in cleartext and can be intercepted. Always serve Enterprise Studio over HTTPS in production, either by enabling server.https.enabled or by terminating TLS at a trusted reverse proxy or load balancer in front of it.

When server.https.enabled is false, Enterprise Studio prints a reminder at startup. See Security → TLS encryption for guidance.

When server.https.enabled is true, place certificate files in the directory specified by server.https.certificates.baseDirectory (default: certificates/https relative to the installation home). These settings configure inbound HTTPS only; outbound trust to Neo4j is separate — see Security → TLS encryption and Binary deployment.

server:
  https:
    enabled: true
    certificates:
      baseDirectory: /etc/studio/certs  (1)
      privateKey: private.key           (2)
      publicCertificate: public.crt     (3)

1	Absolute or relative path to the certificate directory.
2	Unencrypted PKCS#8 PEM private key file.
3	PEM public certificate file.

See TLS encryption for a step-by-step guide.

Tools

Individual tools can be disabled if not needed:

tools:
  dashboards:
    enabled: true
  bloom:
    enabled: true
  query:
    enabled: false

Set enabled to false to hide a tool from the UI. All tools are enabled by default.

Enterprise Studio reads tool configuration only at startup. Restart the server after changing any tools.*.enabled setting for the change to take effect.

Logging

logs:
  level: info
  format: json

level: Log verbosity. One of debug, info, warn, or error.
format: Log output format. Use json (recommended for production) or pretty (human-readable, useful during development).

Secrets Manager

Enterprise Studio can resolve asset storage credentials (username, password) and the OIDC clientSecret from an external Secrets Manager at runtime, instead of storing them in plaintext in config.yaml.

To set up Secrets Manager:

Enable a provider under secretsManager.
For each sensitive field, set exactly one of the literal or the *From reference (username/usernameFrom, password/passwordFrom, clientSecret/clientSecretFrom).

Each secretRef needs a type (aws, azure, or gcp) and a name (the secret identifier in that provider). Use a separate secret for each field (usernameFrom, passwordFrom, clientSecretFrom). The secret value must be the credential string itself — Enterprise Studio does not parse JSON key/value objects.

Enterprise Studio uses the cloud provider’s default credential chain. Do not put cloud access keys in config.yaml. How you supply those credentials depends on where you run Enterprise Studio — see Binary, Docker, and Kubernetes.

See the configuration reference for all settings.

This describes a third-party service; this guidance is based on the information available at the time of writing and may not always reflect the current state of the third party.

AWS Secrets Manager

Enable secretsManager.aws, set the Region, and set secretRef.name to the secret name or ARN in AWS Secrets Manager.

Store each credential as a plaintext SecretString, see AWS documentation for more information:

In the AWS console, select Other type of secret, then the Plaintext tab, and enter only the username or password (not key/value pairs).
With the CLI, pass a plain string, for example --secret-string 'my-service-password'.

Do not store the value as a JSON object (key/value pairs) or as SecretBinary. Enterprise Studio uses the entire SecretString as the credential and does not extract keys from JSON. Binary secrets are rejected.

Example AWS Secrets Manager configuration

secretsManager:
  aws:
    enabled: true
    region: eu-west-1                  (1)

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage
    authentication:
      basic:
        usernameFrom:
          secretRef:
            type: aws                  (2)
            name: nes-assetstore-username  (3)
        passwordFrom:
          secretRef:
            type: aws
            name: nes-assetstore-password

1	Required when AWS is enabled.
2	Must be `aws`.
3	Secret name or ARN. Value must be a plaintext `SecretString` (the username or password only).

For OIDC, use the same pattern with clientSecretFrom instead of passwordFrom.

Enterprise Studio uses the AWS SDK default credential chain. See Authentication and access control for AWS Secrets Manager.

Azure Key Vault

Enable secretsManager.azure, set the vault URL, and set secretRef.name to the secret name in Azure Key Vault.

Key Vault secrets are a single string value. Store the username, password, or client secret as that value (for example with az keyvault secret set --name nes-assetstore-password --value 'my-service-password'). Enterprise Studio uses the secret value as returned — it does not parse JSON objects.

Example Azure Key Vault configuration

secretsManager:
  azure:
    enabled: true
    vaultUrl: https://contoso.vault.azure.net/  (1)

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage
    authentication:
      basic:
        usernameFrom:
          secretRef:
            type: azure               (2)
            name: nes-assetstore-username  (3)
        passwordFrom:
          secretRef:
            type: azure
            name: nes-assetstore-password

1	Required when Azure is enabled. Vault URI from the Azure portal or CLI.
2	Must be `azure`.
3	Key Vault secret name. The secret value must be the credential string itself.

Enterprise Studio uses DefaultAzureCredential. Grant the identity permission to get secrets — for example the Key Vault Secrets User role. See Authenticate Go apps to Azure.

Google Cloud Secret Manager

Enable secretsManager.gcp, set the project ID, and set secretRef.name to the secret ID in Secret Manager. Enterprise Studio reads the latest version of the named secret.

Store each credential as the secret version payload — typically UTF-8 text that is only the username, password, or client secret (for example echo -n 'my-service-password' | gcloud secrets versions add nes-assetstore-password --data-file=-). Enterprise Studio uses the full payload as the credential string and does not parse JSON objects.

Example Google Cloud Secret Manager configuration

secretsManager:
  gcp:
    enabled: true
    project: my-project               (1)

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage
    authentication:
      basic:
        usernameFrom:
          secretRef:
            type: gcp                 (2)
            name: nes-assetstore-username  (3)
        passwordFrom:
          secretRef:
            type: gcp
            name: nes-assetstore-password

1	Required when GCP is enabled. Google Cloud project ID.
2	Must be `gcp`.
3	Secret ID (not the full resource name). Enterprise Studio resolves `projects/<project>/secrets/<name>/versions/latest`. The payload must be the credential string itself.

Enterprise Studio uses Application Default Credentials (ADC). Grant the identity Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) on the secrets it must read.

Environment variable overrides

Any setting in config.yaml can be overridden by setting an environment variable. Use them to adjust values per environment without modifying the file. For passwords and OIDC client secrets in production, use a cloud Secrets Manager when available; otherwise use environment variables — see Security → Secrets management.

To derive the environment variable name from a config path:

Start with the prefix NES_
Replace each . with _
Keep camelCase as-is

Table 1. Examples
Config path	Environment variable
`assetStore.default.uri`	`NES_assetStore_default_uri`
`assetStore.default.authentication.basic.password`	`NES_assetStore_default_authentication_basic_password`
`assetStore.default.authentication.oidc.clientSecret`	`NES_assetStore_default_authentication_oidc_clientSecret`
`server.port`	`NES_server_port`
`server.https.enabled`	`NES_server_https_enabled`
`neo4jDeployments.mydeployment.uri`	`NES_neo4jDeployments_mydeployment_uri`

Deployment IDs must contain only letters and digits (a-z, A-Z, 0-9). This keeps them safe to use directly in NES_neo4jDeployments_<id>_… environment variable names.

For example, to override the asset storage URI and server port:

export NES_assetStore_default_uri="neo4j://my-host:7687"
export NES_server_port="9090"

Environment variables override values in config.yaml at runtime: they do not modify the file on disk. See the Docker deployment page for a complete example using environment variables.