Configuring Neo4j Single Sign-On (SSO)
Enterprise Edition

Neo4j supports SSO authentication and authorization through identity providers implementing the OpenID Connect (OIDC) standard. This page features detailed examples of how to configure Single Sign-On (SSO) for several identity providers. It also presents frequently asked questions and solutions to common problems encountered when configuring SSO.

The following configurations are crafted for a Neo4j Browser served on http://localhost:7474/ (the default URL when starting the database on localhost).

Therefore, when reproducing them in the identity providers, you must modify the redirect URI to include the URI serving your Neo4j Browser application. For example:

http://localhost:7474/browser/?idp_id=<provider>&auth_flow_step=redirect_uri

SSO works in the following way:

  1. The server (Neo4j DBMS) contacts the identity provider (Okta, Entra ID, Google, etc.) and fetches the JSON Web Keys (JWKs) from the provider.

  2. The client (e.g., Bloom, Neo4j Browser, etc.) asks the user for credentials and contacts the identity provider.

  3. The identity provider responds with a JSON Web Token (JWT), a JSON file containing fields (claims) relative to the user (email, audience, groups, etc.).

  4. The client provides the server with the JWT, and the server verifies its signature with the JWKs.

  5. Optionally, you can control the authentication and authorization on a user level by setting dbms.security.require_local_user to true in the neo4j.conf file and the auth providers for the users, which authentication and authorization you want to control, using Cypher. This setting mandates that users with the relevant auth provider attached to them must exist in the database before they can authenticate and authorize with that auth provider. For information on how to modify or create users in this mode, see Manage users.
    This mode allows you the following using Cypher:

    1. Suspend SSO users.

    2. Set a home database for an SSO user.

    3. Set a user-friendly name for an SSO user (rather than relying on the external identifier).

    4. Set a password for an SSO user.

    5. Set a password change requirement for an SSO user.

For further information and examples, see Configure SSO at the user level using auth providers.

JWTs must always contain a value for sub even when using a different claim for username. It is the only claim guaranteed to be unique and stable. Other claims, such as email or preferred_username are less secure and may change over time. They should not be used for authentication. Neo4j may assign permissions to a user based on this username value in a hybrid authorization configuration. Thus, changing the username claim from sub is not recommended.

Okta

The following examples show how to configure Okta for authentication and authorization using access tokens and ID tokens. It assumes that you are using Okta Developer Edition Service. For the complete guide on how to customize tokens returned from Okta with a groups claim, see the Okta official documentation.

Configure the client

  1. From the left-hand side of the Okta dashboard, navigate to Applications and click Create App Integration.

  2. Select OIDC - OpenID Connect for Sign-in method and Single-Page Application for Application type. Because Neo4j Browser is a single-page application, this is the recommended configuration.

  3. Click Next.

  4. Configure the client with the appropriate redirect URI.

    1. Add a name for the app integration.

    2. Add the Sign-in redirect URIs, for example, http://localhost:7474/browser/?idp_id=okta&auth_flow_step=redirect_uri. This URI will accept returned token responses after successful authentication.

  5. Add the Sign-out redirect URIs, for example, http://localhost:7474/.

  6. In the Assignments section, select Skip group assignment for now.

  7. Click Save.

  8. Take note of the Client ID. You will need it later when configuring the Okta parameters and the Well-known OpenID Connect endpoint in the neo4j.conf file.

Assign Okta groups to the application

  1. From the left-hand side of the Okta dashboard, navigate to Dashboard → Directory → Groups, and click Add Group.

  2. Add a name for the group, for example, engineers, and click Save.