:description: Single Sign-On (SSO) for Neo4j Browser.

[role=enterprise-edition]
[[browser-sso]]
= Browser Single Sign-On

Neo4j Browser provides support for Single Sign-On (SSO) providers.
This is an Enterprise feature and requires specific configuration and a (self-hosted) Neo4j Server v4.4 and later.
Additionally, you need a compatible SSO provider (local or external) already configured.
For more information on the configuration, see link:https://neo4j.com/docs/operations-manual/current/authentication-authorization/sso-integration/#auth-sso-parameters[Operations Manual -> OIDC configuration settings^].

[NOTE]
====
For deployments other than with self-hosted Neo4j Server v4.4+, SSO can be configured with a separate OAuth plugin which requires engagement from Professional Services.
See link:https://neo4j.com/professional-services/[^] for more information about Professional Services.
====

Supported providers at this time include OpenID Connect (OIDC) OAuth 2.0 providers Google, Keycloak, Microsoft Azure AD, and Okta.

Browser supports two authorization flows:

* Authorization Code flow with PKCE.
* Implicit flow.

[IMPORTANT]
====
It is strongly advised to use PKCE to ensure security.
Further information about OpenID Connect and OAuth can be found at link:https://openid.net/connect/[https://openid.net/connect/^].
====

[IMPORTANT]
====
Security information should always be exchanged with encrypted transport, and therefore HTTPS should be used.
Mixed HTTP/HTTPS flows for single sign-on are not supported.
====

Once your SSO provider is configured, you need to configure Neo4j to use OpenID Connect.
This is done by updating the link:https://neo4j.com/docs/operations-manual/current/configuration/neo4j-conf/#neo4j-conf[`neo4j.conf`^] file according to the instructions in link:https://neo4j.com/docs/operations-manual/current/authentication-authorization/sso-integration/#auth-sso-configure-sso[Operations Manual -> Configure Neo4j to use OpenId Connect^].

Make sure to avoid duplicate entries in the `neo4j.conf` file.

Browser needs to be aware of the identity providers available for use.
When used with Neo4j v4.4+, this is specified the `neo4j.conf` file, as described above.

Deployments that use an earlier version of Neo4j require a separate OAuth plugin and assistance from Professional Services, as mentioned previously.
However, in such cases, the identity providers can be specified by a URL parameter `discoveryURL` that defines a URL to a .json file containing the SSO providers.

Example for Browser: +
`\https://<browser-server-host>:<http-port>?discoveryURL=https://webhost.com/public/discovery.json`

// [IMPORTANT]
// ====
// Browser will prioritize in the following order, in case of conflicting data:
// . `neo4j.conf`
// . `discoveryURL`
// ====

// 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.
//
// [source, properties]
// ----
// dbms.jvm.additional=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
// dbms.jvm.additional=-Dorg.apache.commons.logging.simplelog.showdatetime=true
// dbms.jvm.additional=-Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
// ----


// The following are instructions on how to use the PS plugin and can remain commented out until we know we don't need them anymore.
// updates to neo4j.conf
// [source, properties]
// ----
// dbms.security.auth_enabled=true
// dbms.security.authentication_providers=native,plugin-org.neo4j.auth.openid.OpenIdPlugin
// dbms.security.authorization_providers=native,plugin-org.neo4j.auth.openid.OpenIdPlugin
// plugins.auth.openid.configuration=https://login.org.com/.well-known/openid-configuration
// plugins.auth.openid.group_to_role_mapping=reader=reader;editor=editor;publisher=publisher;architect=architect;admin=admin
// plugins.auth.openid.claim.groups=groups
// plugins.auth.openid.claim.principal=preferred_username
// ----
// . 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:
// +
// [source, url, role="noheader"]
// ----
// http://<browser-server-host>:<http-port>?discoveryURL=http://webhost.com/public/discovery.json
// ----
// +
// 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 Neo4j Professional Services to avoid misconfiguration.
// +
// [source, parameters]
// ----
//
// {
// 	// 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.
// 			}
// 		}
// 	]
// }
// ----
// +
// [IMPORTANT]
// ====
// `redirect_uri` MUST match exactly the redirect_uri specified in the IdP.
// ====


// The following URL parameters support SSO in Browser:
//
// .URL parameters
// [cols="2,3,3,3", options=header]
// |===
// | URL (search parameter)   	| Syntax | Example | Description
// |`sso_redirect` | `sso_redirect=<idp_id>` 	| `sso_redirect=keycloak-oidc`	| Use to auto-redirect to SSO login page.
// |`auth_flow_step` | `auth_flow_step=<arg>`	| `auth_flow_step=redirect_uri`	| 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.
// |`idp_id` | `idp_id=<idp_id>`	| `idp_id=keycloak-oidc` 	| The user arrives with a URL param named idp_id, mapped to the information in the discovery data to figure out how to proceed.
// |===
