This article helps you configure Single Sign-On (SSO) in Neo4j through Keycloak.

It includes instructions for configuring both Neo4j and Keycloak to make this integration possible.

Keycloak is an Open Source Identity and Access Management solution for Applications and Services. It enables managing different identity providers (Open ID, Saml v2.0 and Social) along with various user federation providers (Kerberos, LDAP, AD) all in a centralized console.

Running Keycloak

Docker Images for Keycloak are available on the Redhat quay.io repository.

In this Lab, you can start Keycloak using this docker run command:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:19.0.2 start-dev

More information about running Keycloak in Docker can be found here:

http://www.mastertheboss.com/keycloak/keycloak-with-docker/

Now you can access the Keycloak admin console at http://localhost:8080/

Using the password passed to the Docker run command (admin/admin).

Configuring Keycloak

Let's create a realm. A realm manages a set of users, credentials, roles, and groups. A user belongs to, and logs into, a realm. Realms are isolated from one another and can only manage and authenticate the users that they control.

Create a Realm called "myCorp":

Create a public OpenId Connect client named "neo4j-client" within the myCorp realm:

Screen1:

Screen2:

Add your Neo4j browser valid redirect url:

http://localhost:7414/browser/?idp_id=keycloak&auth_flow_step=redirect_uri

http://localhost:7424/browser/?idp_id=keycloak&auth_flow_step=redirect_uri

http://localhost:7434/browser/?idp_id=keycloak&auth_flow_step=redirect_uri

Add web origin *

Create 3 groups "admin", "reader" and "analyst":

Create three users called "admin", "reader" and "analyst" and add them to the created groups admin, reader and analyst respectively:

Set a password for your users under Users>Credentials:

Create a client scope called "Groups" in Keycloak with the following setting:

Add a Groups mappers to the Groups client scope so the groups will be added to the JWT access  token:

Finally, add the newly created client scope called Groups to your Neo4j client:

The final Realm configuration export is attached to this article. Download link.

Configuring Neo4j

SSO is supported in Neo4j Enterprise edition from version 4.4.

Configure  Neo4j to use Keycloak OIDC provider. In neo4j.conf add:

# Keycloak

dbms.security.authentication_providers=oidc-keycloak,native

dbms.security.authorization_providers=oidc-keycloak,native

dbms.security.oidc.keycloak.display_name=keycloak

dbms.security.oidc.keycloak.auth_flow =pkce

dbms.security.oidc.keycloak.well_known_discovery_uri=http://127.0.0.1:8080/realms/myCorp/.well-known/openid-configuration

dbms.security.oidc.keycloak.params=client_id=neo4j-client;response_type=code;scope=openid email roles

dbms.security.oidc.keycloak.audience=account

dbms.security.oidc.keycloak.issuer=http://127.0.0.1:8080/realms/myCorp

dbms.security.oidc.keycloak.claims.username=preferred_username

# The claim to use for the database roles.

dbms.security.oidc.keycloak.claims.groups=groups

dbms.security.oidc.keycloak.authorization.group_to_role_mapping="/admin"=admin; "/analyst"=analyst;"/reader"=reader

dbms.security.oidc.keycloak.config=principal=preferred_username;token_type_principal=access_token;token_type_authentication=access_token

dbms.security.oidc.keycloak.auth_endpoint=http://127.0.0.1:8080/realms/myCorp/protocol/openid-connect/auth

dbms.security.oidc.keycloak.token_endpoint=http://127.0.0.1:8080/realms/myCorp/protocol/openid-connect/token

After restarting Neo4j, The browser will have Keycloak SSO added to the authentication methods.

Once SSO is chosen, the user will be redirected  to the Keycloak authentication page:

After providing your previously created Keycloak username and password, you will be redirected to the Neo4j browser again.

In Neo4j security.log check that the user is successfully connected and the roles are correctly mapped:

2023-01-0313:53:21.208+0000DEBUG {OidcRealm: oidc-keycloak}: Successfully authenticated user 'analyst' roles '[analyst]'
2023-01-0313:53:21.209+0000INFO [analyst]: logged in

2023-01-0315:58:30.083+0000DEBUG {OidcRealm: oidc-keycloak}: Successfully authenticated user 'admin' roles '[admin]'
2023-01-0315:58:30.083+0000INFO [admin]: logged in