Users, roles and database permissions

Wiki / Operations

Configure the first administrator

Set the initial credentials in your database Compose service:

environment:
  GDB_INITIAL_USER: gdb
  GDB_INITIAL_PASSWORD: ${GDB_INITIAL_PASSWORD:?Set GDB_INITIAL_PASSWORD in .env}

The release image requires a bootstrap password of at least 12 characters. Keep the password in your local .env file. The Docker guide includes the complete setup. GDB_EXPLORER_DEFAULT_USER only prefills Explorer's login form; it does not change a database account.

Users, roles and grants persist in the protected system database. Once initialized, changing GDB_INITIAL_PASSWORD and recreating the container does not reset the account. Use security Cypher to change it. Website accounts and database users are separate.

Give a user access to one database

Connect as an administrator through a driver or Explorer. Run these statements separately, outside an explicit transaction. Supply $password as a driver parameter with a password of at least eight characters.

The example creates an additional database and requires a Commercial licence. On a one-database edition, skip CREATE DATABASE and use your configured home database name throughout. See licensing.

CREATE DATABASE analytics IF NOT EXISTS;
CREATE USER analyst SET PASSWORD $password CHANGE NOT REQUIRED;
CREATE ROLE analytics_reader;
GRANT ACCESS ON DATABASE analytics TO analytics_reader;
GRANT MATCH {*} ON GRAPH analytics TO analytics_reader;
GRANT ROLE analytics_reader TO analyst;
ALTER USER analyst SET HOME DATABASE analytics;

The analyst can read the whole analytics graph, but cannot write it, read another database without a grant, or administer users. A home database is a routing preference, not a graph permission. ACCESS alone permits selecting a database and calculating expressions, not reading its nodes.

New users receive only PUBLIC: home-database access and procedure execution subject to each procedure's required privileges. Omitting CHANGE NOT REQUIRED requires a password change before ordinary queries:

ALTER CURRENT USER SET PASSWORD FROM $oldPassword TO $newPassword;

Security commands use a supported subset of Neo4j Cypher syntax and are routed to system. Raw graph queries, imports, exports and restore on system are blocked even for administrators. Label, relationship-type, property and row restrictions are deferred; unsupported granular grants are rejected.

Manage roles and privileges

Use custom roles for database-specific access. Built-in role grants cover all user databases:

Grants combine across roles; an applicable DENY overrides a grant. REVOKE GRANT removes grants, REVOKE DENY removes denies, and plain REVOKE removes both. Built-in privileges can change subject to last-admin protection.

GRANT WRITE ON GRAPH analytics TO analytics_reader;
DENY WRITE ON GRAPH analytics TO analytics_reader;
REVOKE DENY WRITE ON GRAPH analytics FROM analytics_reader;
GRANT INDEX MANAGEMENT ON DATABASE analytics TO analytics_reader;
GRANT CONSTRAINT MANAGEMENT ON DATABASE analytics TO analytics_reader;
SHOW USERS;
SHOW ROLES WITH USERS;
SHOW USER analyst PRIVILEGES;
SHOW ROLE analytics_reader PRIVILEGES;
ALTER USER analyst SET STATUS SUSPENDED;
ALTER USER analyst SET STATUS ACTIVE;
ALTER USER analyst SET PASSWORD $replacement CHANGE NOT REQUIRED;
REVOKE ROLE analytics_reader FROM analyst;
DROP USER analyst IF EXISTS;
DROP ROLE analytics_reader IF EXISTS;

ALL DATABASE PRIVILEGES covers access and supported schema management, not graph reads/writes or lifecycle rights. DBMS management groups include DATABASE MANAGEMENT, USER MANAGEMENT, ROLE MANAGEMENT and PRIVILEGE MANAGEMENT. Individual create/drop/alter database and user actions, show users, create/drop/show roles, assign/remove roles, and assign/remove/show privileges are supported. For example: GRANT USER MANAGEMENT ON DBMS TO operators.

Names are case-sensitive and may be backtick-quoted. CREATE USER/ROLE supports IF NOT EXISTS. SHOW has fixed columns; YIELD/WHERE/RETURN modifiers, AS COMMANDS, CREATE OR REPLACE, renames, external identity providers and impersonation are not supported yet.

Procedures require execution permission and permission for their effects. Graph algorithms need graph read access; GDS projection/write/mutate operations also need write access. Maintenance requires EXECUTE ADMIN PROCEDURES. Imports, exports and file/URL loaders additionally need applicable LOAD, graph and schema privileges. Give LOAD ON ALL DATA only to trusted operators: host file/URL access is not isolated to a user's graph. Backup helpers have the same trust boundary. Licensing checks apply independently of RBAC.

Existing installations

The bootstrap administrator retains full privileges. Users provisioned through the legacy application API retain full administrator access on initial provisioning. Startup provisioning does not overwrite saved passwords or roles. New users created with Cypher start restricted as described above.

Before upgrading, preserve a backup of the complete stopped instance, including system. If an old installation used system for ordinary graph data, export and move that data using the old release first; initialization refuses a nonempty legacy system graph. Corrupt/incompatible security catalogs fail startup rather than silently creating an administrator. Do not delete system to reset a password or run an older server against a newly secured instance. See backup and recovery.

Last administrator protection

Every security change must leave an active user with all implemented user, role and privilege management permissions. The check considers effective grants and denies, not just a role named admin.

The last administrator cannot revoke their final admin role, drop it, remove its required permissions, add a blocking deny, or rely only on suspended or password-change-required replacements. Concurrent changes cannot both remove the final authority. Self-deletion and self-suspension are always blocked. An administrator can give up their role once another active administrator exists.

Keep a second administrator and a recoverable instance backup. This release has no offline password-reset CLI or online security-catalog export.

Lifetime and transport

Grants are re-evaluated on existing connections. Suspension, password rotation and deletion invalidate old credentials. Self-service password changes keep the changing connection and invalidate its other connections. PULL rechecks before releasing buffered results; COMMIT rechecks permissions and rolls back if rights were revoked. Already delivered rows cannot be recalled. Revocation can wait for a running statement. Idle transactions are cleaned up on their next request, reset or disconnect, rather than being remotely cancelled immediately.

system always uses resident memory with synchronous durable security writes, independently of user-database storage settings. Permission reads do no disk I/O or per-node checks. RBAC stays enabled, with no ENV bypass. See Repository reference: the RBAC introduction for an overview with examples.

Passwords use Argon2id with random salts. Without GDB_DATA, all state is volatile. There is no native TLS: keep Bolt on a trusted private network and provide encrypted transport at the deployment boundary. Put Explorer behind an HTTPS reverse proxy for remote access.

Related articles

Configuration | Database administration | Drivers | Explorer