Skip to main content
Version: Development

Neo4j database secrets engine

Neo4j is one of the supported plugins for the database secrets engine. This plugin generates dynamic credentials against a Neo4j 4+ cluster over the Bolt protocol, using the official Neo4j Go driver. It also supports Static Roles.

See the database secrets engine docs for more information about setting up the database secrets engine.

Unlike the SQL-style database plugins, creation_statements is a single JSON document listing pre-existing Neo4j role names to grant the new user, rather than a semicolon-separated list of statements. Under the hood the plugin issues Cypher against the cluster's system database: CREATE USER ... SET PASSWORD ... CHANGE NOT REQUIRED followed by one GRANT ROLE per listed role. Roles referenced by creation_statements must already exist on the cluster — this plugin does not create roles, only users and role grants.

Capabilities​

Plugin NameRoot Credential RotationDynamic RolesStatic RolesUsername Customization
neo4j-database-pluginYesYesYesYes

Setup​

  1. Enable the database secrets engine if it is not already enabled:

    $ bao secrets enable database
    Success! Enabled the database secrets engine at: database/

    By default, the secrets engine will enable at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

  2. Configure OpenBao with the proper plugin and connection information. The uri uses the Bolt protocol scheme (bolt://, neo4j://, bolt+s://, neo4j+s://, etc.):

    $ bao write database/config/neo4j \
        plugin_name="neo4j-database-plugin" \
        allowed_roles="reader" \
        uri="bolt://neo4j.example.com:7687" \
        username="neo4j" \
        password="password"
    Success! Data written to: database/config/neo4j

  3. Configure a role that maps a name in OpenBao to a Neo4j role-grant document to execute to create the database credential. The roles listed must already exist on the cluster:

    $ bao write database/roles/reader \
        db_name="neo4j" \
        creation_statements='{"roles":["reader"]}' \
        default_ttl="1h" \
        max_ttl="24h"
    Success! Data written to: database/roles/reader

Usage​

After the secrets engine is configured and a user/machine has an OpenBao token with the proper permission, it can generate credentials.

  1. Generate a new credential by reading from the /creds endpoint with the name of the role:

    $ bao read database/creds/reader
    Key                Value
    ---                -----
    lease_id           database/creds/reader/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
    lease_duration     1h
    lease_renewable    true
    password           SsnoaA-8Tv4t34f41baD
    username           v-token-reader-x7g2kf8s1a2b-1717000000

Neo4j-specific notes​

  • No native credential expiry: Neo4j has no VALID UNTIL clause on users, so lease expiry for dynamic roles is enforced purely by OpenBao revoking the lease (DROP USER ... IF EXISTS), not by the database itself.
  • Role names cannot be parameterized: Cypher does not support parameterizing identifiers, so role names from creation_statements are back-tick quoted when granted. Role names that themselves contain a back-tick are rejected.
  • Partial-failure cleanup: CREATE USER is not transactional with the subsequent GRANT ROLE statements. If any role grant fails (for example, the role does not exist), the plugin drops the just-created user before returning the error, so no half-configured user is left behind.
  • database targets user management, not application data: the database config field (default system) selects which database the CREATE USER / ALTER USER / DROP USER / GRANT ROLE statements run against — Neo4j 4+'s convention for user administration — not the database application queries run against.

API​

The full list of configurable options can be seen in the Neo4j database plugin API page.

For more information on the database secrets engine's HTTP API please see the Database secrets engine API page.