Neo4j Browser Single Sign-On (SSO)

Browser provides basic support for some Single Sign On (SSO) providers under specific Enterprise environment configurations. Contact your Neo4j representative for additional assistance. Your organization needs an existing compatible SSO provider (local or external) already configured.

Supported providers at this time include OpenID Connect (OIDC) OAuth 2.0 providers Okta, KeyCloak, and Microsoft Azure AD. SSO has been tested on Neo4j 4.2.x and 4.3.x deployments. Browser supports two authorization flows:

  • Authorization Code flow with PKCE

  • Implicit flow

It is strongly advised to use PKCE to ensure security. Further information about OpenID Connect and OAuth can be found at

In addition to having an SSO provider already configured at your organization, configuring SSO for Browser and Neo4j requires a separate OAuth plugin, available from your Neo4j representative. With these prerequisites in place, two additional steps are required:

  1. The neo4j.conf file should be updated with the following information (be sure to avoid duplicate entries in the neo4j.conf file):,plugin-org.neo4j.auth.openid.OpenIdPlugin,plugin-org.neo4j.auth.openid.OpenIdPlugin

    Optionally, you may set extra logging for the OAuth2 plugin with these settings in the neo4j.conf file. The logs are found in the neo4j.log file. The :debug command contains logging from the SSO implementation and can be useful when debugging.

  2. Browser needs to be aware of the identity providers available for use. This is done by specifying a URL parameter discoveryURL that specifies a URL to a json file containing the SSO providers. Example for Browser: http://<browser-server-host>:<http-port>?discoveryURL=

    The discovery.json file must contain entries tailored to your organization’s specific SSO solution. Below is a reference discovery file for the ID provider (IDP) Keycloak containing one SSO provider and set up to be running on port 18080. It contains all the possible parameters you can provide. You most likely do not need all the parameters. If you are unsure, please consult your Neo4j representative to avoid misconfiguration.

    	// other discovery entries
    	// e.g. "bolt": "bolt://localhost:7687"
    	"sso_providers": [
    			"id": "keycloak-oidc",  // has to be unique in this file!
    			"name": "Keycloak", // displayed in UI
    			"auth_flow": "pkce",
          "auth_endpoint": "http://localhost:18080/auth/realms/myrealm/protocol/openid-connect/auth",
     			"token_endpoint": "http://localhost:18080/auth/realms/myrealm/protocol/openid-connect/token",
     			"well_known_discovery_uri": "http://localhost:18080/auth/realms/myrealm/.well-known/openid-configuration",
    			"params": {  // can be used for both the auth and the token request
    				"client_id": "account",
    				"redirect_uri": "http://<browser-server-host>:<http-port>?idp_id=keycloak-oidc&auth_flow_step=redirect_uri",
    				"response_type": "code",  // depends on the auth_flow
    				"scope": "openid groups"
    			"auth_params": { // optional
    				"param_p": "<extra parameter used only for the auth request>"
    			"token_params": { // optional
    				"client_secret": "<secret-here>", // this may be required by some Idp's and depended on the auth flow.
    				"param_p": "<extra parameter used only for the token request>"
    			"config": { // optional settings, these allow you to overwrite the defaults
    				"implicit_flow_requires_nonce": false, // Default: false; Desc: Specify if the implicit auth flow requries a nonce in the request
    				"principal": "preferred_username",  // Default: email, otherwise sub; Desc: Optional, in which token claim the user's principal is specified
    				"token_type_principal": "access_token" // Default: access_token; Desc: Which token type is decoded to acquire the specified principal
    				"token_type_authentication": "access_token" // Default: access_token; Desc: Which token type is used as password
    				"code_challenge_method": "S256" // Default is "S256" and it's the only supported method at this moment.

    redirect_uri MUST match exactly the redirect_uri specified in the IdP.

The following URL parameters support SSO in Browser:

Table 1. URL parameters
URL (search parameter) Syntax Example Description




Use to auto-redirect to SSO login page.




If the user arrives back to the client application with the URL param auth_flow_step=redirect_uri, this indicates that it is time to proceed in the auth process.




The user arrives with a URL param named idp_id, mapped to the information in the discovery data to figure out how to proceed.