# Users, roles and database permissions

[Wiki](../README.md) / [Operations](README.md)

## Configure the first administrator

Set the initial credentials in your database Compose service:

```yaml
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](docker.md)
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](licensing.md).

```cypher
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:

```cypher
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:

| Role | Initial permissions |
|---|---|
| `reader` | Access, graph read/traverse and ordinary schema inspection |
| `editor`, `publisher` | Reader permissions plus graph writes; token-name restrictions are deferred |
| `architect` | Read/write plus index and constraint management |
| `admin` | All implemented graph, database and DBMS permissions |
| `PUBLIC` | Held automatically by every user; cannot be dropped or explicitly assigned/removed |

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.

```cypher
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;
```

| Scope | Supported privileges |
|---|---|
| `ON GRAPH name`, `ON GRAPH *`, `ON HOME GRAPH` | `MATCH {*} `, `READ {*} `, `TRAVERSE`, `WRITE`, `ALL GRAPH PRIVILEGES` |
| `ON DATABASE name`, `ON DATABASE *`, `ON HOME DATABASE` | `ACCESS`; `CREATE INDEX`, `DROP INDEX`, `SHOW INDEX`, `INDEX MANAGEMENT`; equivalent constraint actions; `ALTER DATABASE`; `ALL DATABASE PRIVILEGES` |
| `ON DBMS` | Database, user, role and privilege management; `EXECUTE PROCEDURE <pattern>`, `EXECUTE ADMIN PROCEDURES`, `ALL DBMS PRIVILEGES` |
| `ON ALL DATA` | `LOAD` |

`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](backups.md#security-state-and-permissions).

## 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
[the RBAC introduction](https://galactusdb.com/blog/galactus-db-rbac) for an overview with examples.

Passwords use Argon2id with random salts. Without `GDB_DATA`, all state is
volatile. Configure a certificate for [encrypted connections](#encrypted-connections),
or keep Bolt on a trusted private network. Put Explorer behind an HTTPS reverse
proxy for remote access.

## Encrypted connections

Set `GDB_TLS_CERT` and `GDB_TLS_KEY` to a PEM certificate chain (leaf first) and
its private key, and the server accepts TLS on the Bolt port, for native Bolt
and for Bolt over WebSocket. Clients connect with `bolt+s://` (certificate
verified) or `bolt+ssc://` (encrypted, certificate not verified).

With a certificate configured, plaintext connections are refused.
`GDB_TLS_REQUIRED=false` serves encrypted and plaintext clients on the same
port, for a migration. TLS 1.2 and 1.3 are offered; client certificates are not
requested. The files are read at startup: restart after renewing them.

Explorer connects to a TLS-only database with a `bolt+s://` or `bolt+ssc://`
address. For a private certificate authority, or a self-signed certificate you
want verified, set `GDB_EXPLORER_CA_FILE` to a PEM file of the authority.
Explorer's own web page is plain HTTP: put a TLS terminator in front of it.

## Related articles

[Configuration](configuration.md) | [Database administration](databases.md) | [Drivers](../integrations/bolt.md) | [Explorer](../explorer/README.md)
