How to Configure Neo4j IAM Authentication

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up neo4j iam authentication by linking your graph database to your identity provider. This setup checks external user tokens and maps cloud groups to internal database roles. Most teams start by linking their main identity directory to the database server. They often map broad engineering groups to a single high-level database role. This quick fix speeds up onboarding for developers and data scientists. Still, broad role mappings give too many people write permissions on production graph

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up neo4j iam authentication by linking your graph database to your identity provider. This setup checks external user tokens and maps cloud groups to internal database roles. Most teams start by linking their main identity directory to the database server. They often map broad engineering groups to a single high-level database role. This quick fix speeds up onboarding for developers and data scientists. Still, broad role mappings give too many people write permissions on production graph data. A single bad query can change or delete critical nodes across the whole graph.

How neo4j iam authentication works in practice

The native login flow uses standard open identity protocols to check who is logging in. First, an admin registers the graph database as a client inside the identity provider. The identity provider gives back a discovery URL and a set of public keys. Next, the admin updates the database settings to trust tokens from that specific provider. When a user or app logs in, they first get a signed token. The database reads the token signature and checks it against the provider public keys. It also checks that the token has not expired and matches the right audience.

After the token check passes, the database reads the group claims inside the token. The database settings include a mapping rule that links external groups to internal roles. For example, a cloud group for analysts maps to a read-only database role. An admin group maps to a role that can create indexes and delete nodes. The user session then starts with the permissions of those mapped internal roles. If a user belongs to multiple groups, the database combines the permissions from each role.

Why role mapping needs careful planning

Group mapping makes user management much easier for security and platform teams. When someone leaves the company, you remove them from the central identity provider. They lose access to the graph database right away without manual database changes. You also avoid sharing static database passwords across developer laptops and build servers. Every login attempt creates a record in your central identity logs for audit checks.

Still, managing roles inside the graph database takes ongoing work from your team. Native database roles apply broad rules across labels, relationship types, and property keys. Teams often create a few coarse roles instead of maintaining dozens of strict ones. Developers asking for temporary debug access often get added to an admin group. Once they are in that group, they keep those high permissions for weeks. Auditing who has access requires checking both identity provider groups and database role rules.

Service-to-Service Authentication + AWS IAM Policies: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native login checks leave open

Native login setups only decide who can open a session with the database. Once the session starts, the identity provider has no visibility into the queries run. A user with a valid role can run any query allowed by that role. Native login checks cannot stop a destructive query if the role allows writes. They also cannot require a peer review before a user runs an update statement.

Sensitive data inside node properties also creates a challenge during live query sessions. A support engineer may need to inspect graph links to fix a customer issue. If their role allows reading customer nodes, every property comes back in clear text. Native identity integration does not rewrite sensitive fields like emails or phone numbers in results. Protecting card numbers or national IDs requires extra rules outside the basic login flow.

Check database and API queries on the wire

Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev sits inline in the wire protocol beside those services as an open-source proxy, a sidecar for your Postgres or API. On every query an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run, and hoop.dev data masking rewrites matched sensitive values in responses in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.

Frequently asked questions

Can I use both external identity tokens and local database users?

Yes, the database allows you to turn on external identity providers alongside local login checks. Many teams keep one local admin account for emergency recovery if the provider goes down.

How does the database know which role to give an external user?

The database reads the group claim inside the user token during the login step. It matches that group name to an internal database role using your mapping rules.

What happens when an external identity token expires during a session?

The database checks token validity when a session starts and when tokens refresh. Once the token expires and cannot refresh, the database closes the active user session.

The query runs. The emails stay hidden.