Neo4j Enterprise version 4.4+ added support for OpenID Connect (OIDC), which allows for integration with many identity providers including Okta, Microsoft Azure Active Directory, Keycloak and Google.

Users will be allowed to log in through an OIDC compliant identity provider by offering a token from the provider instead of a username and password. Typically, these tokens take the form of a signed JSON Web Token (JWT). 

JSON Web Token (JWT) is an open standard used for authentication and authorization purposes, allowing users to authenticate once and receive a token that they can use to access multiple systems without having to log in again. JWTs can also be used to transmit information about the user, such as their role or permissions.

Neo4j receives a JWT from the identity provider containing claims representing the database username (e.g. email), and the Neo4j roles.

While troubleshooting SSO integration issues with Neo4j, it is useful to capture and analyse the JWT token. You can use a combination of browser developer tools and online decoder tools. Here are the steps:

Decoding the JWT

When using the "new" Neo4j Browser

As current users are aware, the Neo4j Browser has been through a substantial user interface and feature update. This new browser was introduced as an opt-in "preview" in many recent versions of Neo4j 5.x, 2025.x and Aura. As of June, 2025, the new (a.k.a., preview) Neo4j Browser has become the default experience. The previous Neo4j Browser has been dubbed the "classic" or "legacy" version and is now become an opt-in version.

When using the current Neo4j Browser, a simple way to decode the JWT provided by an SSO provider is to paste and execute a JavaScript snippet in your web browser's Console after attempting to login using SSO.

1. Open your web browser's developer tools ( Right click on the the page and Select Inspect or alternatively  press "Ctrl + Shift + I" on Windows, or "Cmd + Option + I" on Mac)
2. Go to the Console tab.
3. Paste the following code into the Console

jwt=JSON.parse(atob(JSON.parse(sessionStorage.getItem('nx.v1.nx.currentConnection')).authToken.credentials.split('.')[1]));for (const k in jwt) {const v = jwt[k];console.log(`${k}: ${v}`)}

This statement will decode the key/value pairs representing the claims contained in the JWT.
If you also need to decode the dates associated with the JWT, you can execute the following JavaScript snippet after executing the first statement.

iat = new Date(jwt.iat * 1000);console.log('Issued: ' + iat.toLocaleDateString() + ' ' + iat.toLocaleTimeString() + '\nExpires: ' + exp.toLocaleDateString() + ' ' + exp.toLocaleTimeString() + '\nDuration: ' + (exp - iat)/(60 * 1000) + 'min')

Capturing and decoding the JWT token from the Web Browser

This method will work with both the new and classic Neo4j Browser experiences.

1. Open Neo4j Browser web application.
2. Open your web browser's developer tools ( Right click on the the page and Select Inspect or alternatively  press "Ctrl + Shift + I" on Windows, or "Cmd + Option + I" on Mac)
3. Go to the Network tab.
4. Check the "Preserve log" checkbox in Chrome (or Persist logs in FireFox)
5. In Neo4j Browser choose  Authentication type  SSO and login through you Identity provider.
6. In the filter of the Network tab in the developer tools, type "token"
7. Right click on id_token and select copy value.

Chrome: go to Preview

 

 Firefox: go to Response

 

Analyzing the JWT token:

1. Use jwt.io to decode the copied id_token and see the content. Just paste the id_token in the left section of the jwt.io screen.
2. The payload will be decoded in right section of the screen. It contains the user information and its groups:

 

As an example, in the JWT below you can check different claims like the token creation, expiration time, user information and most importantly groups information. Missing group information in the JWT will lead into group to role mapping issues in Neo4j.

 

When the groups claim is not passed in the token, the user will be logged successfully however the group to role mapping in Neo4j will not work.  An empty roles list will be seen in security.log:

DEBUG {OidcRealm: oidc-keycloak}: Successfully authenticated user 'super' roles '[]'

To solve this problem, the IdP provider should be configured to pass the groups information in the JTW token.  In Azure AD, for example, the server needs to be configured to return the AD Group Object IDs in the JWT identity tokens. To do this, setgroupMembershipClaimstoSecurityGroupin the Manifest of the registered application. More detail here. 

Configuring Keycloak SSO with Neo4j is explained in this KB article .

 

Neo4j Enterprise version 4.4.16 update:

From Neo4j version 4.4.16, a new configuration setting called dbms.security.logs.oidc.jwt_claims_at_debug_level_enabled was introduced. The parameter works when the security log level is set to DEBUG. This will enable logging the JWT response from the Id Provider to Neo4j security.log.

To enable this logging add the following parameters to your neo4j.conf:

#debugging claims available from Neo4j 4.4.16

 dbms.security.logs.oidc.jwt_claims_at_debug_level_enabled=true

# The jwt debug setting works with security.log in DEBUG mode. 

# Neo4j V4.4 use: dbms.logs.security.level=DEBUG 

# To set the security log to DEBUG in  Neo4j V5 refer to this article .

dbms.logs.security.level=DEBUG

 

You can check the setting using this Cypher on your Neo4j Browser or Cypher-shell:

CALL dbms.listConfig() YIELD name, value WHERE name CONTAINS "jwt" RETURN name,value;

 

Example of a sanitized extract from Neo4j security.log showing JWT claims sent by Azure IdP:

Further reading:

Understanding the "JWT is not valid for this realm" error when configuring SSO on Neo4j