Troubleshooting Single Sign-On SSO problems in Neo4j

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:

Capturing the JWT token in the Web Browser:

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 from 4.4.16

 dbms.security.logs.oidc.jwt_claims_at_debug_level_enabled=true

dbms.logs.security.level=DEBUG

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