Single sign-on integration

Neo4j supports multiple OIDC identity providers at the same time, as such each provider configuration must be assigned a prefix to differentiate it from others. In the configuration examples below the provider-specific prefix is represented by <provider>, which should be replaced with a name representing your provider. For example, if you are using Okta as your identity provider you might use okta in the place of <provider> below.

The following configuration settings are important to consider when configuring single sign-on. For a more detailed overview of the single sign-on configuration options, see Configuration settings. Some of these settings can also be updated while the database is running, see Dynamic settings for more information on how to do this. Altering any of these settings causes users to re-authenticate as their permissions may have changed as a result.

First, you configure Neo4j to use OpenID Connect as an authentication and authorization provider in the neo4j.conf file.

Before identity provider managed groups can be used with Neo4j, you have to decide on an approach for mapping identity provider groups to Neo4j roles. The simplest approach is to create identity provider groups with the same names as Neo4j roles. If you decide to go this way, no mapping configuration is necessary. Assuming, however, that identity provider groups do not directly map 1:1 to the desired Neo4j roles, it is necessary to map the identity provider groups to the Neo4j built-in and custom-defined roles. To do that, you need to know what privileges the Neo4j roles have, and based on these privileges, create the mapping to the groups defined in the identity provider. The map must be formatted as a semicolon-separated list of key-value pairs, where the key is a comma-separated list of the identity provider group names and the value is a comma-separated list of the corresponding role names. For example, group1=role1;group2=role2;group3=role3,role4,role5;group4,group5=role6.

This option allows users 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). In the configuration examples below, we are using mysso as our provider name. It is recommended to use a name describing the provider that is being integrated.

Production environments should always use an SSL certificate issued by a Certificate Authority for secure access to the identity provider. However, there are scenarios, for example in test environments, where you may want to use a self-signed SSL certificate on the identity provider server.

To configure a self-signed SSL certificate used on an identity provider server, enter the details of a Java keystore containing the relevant certificates using server.jvm.additional in neo4j.conf. The path to the certificate file MyCert.jks is an absolute path to the Neo4j server.

While setting up an OIDC integration, it is sometimes necessary to perform troubleshooting. In these cases, it can be useful to view the claims contained in the JWT supplied by the identity provider. To enable the logging of these claims at DEBUG level in the security log, set dbms.security.logs.oidc.jwt_claims_at_debug_level_enabled to be true and the security log level to DEBUG.