Neo4j Single Sign-On (SSO) configuration
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.
Neo4j supports SSO authentication and authorization through identity providers implementing the OpenID Connect (OIDC) standard.
The following configurations are crafted for a Neo4j Browser served on
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:
SSO works in the following way:
The server (Neo4j DBMS) contacts the identity provider (Okta, Azure, Google, etc.) and fetches the JSON Web Keys (JWKs) from the provider.
The client (e.g., Bloom, Neo4j Browser, etc.) asks the user for credentials and contacts the identity provider.
The identity provider responds with a JSON Web Token (JWT), a JSON file containing fields (claims) relative to the user (email, audience, groups, etc.).
The client provides the server with the JWT, and the server verifies its signature with the JWKs.
Currently it is not possible to login to Cypher Shell using SSO authentication and authorization.
This example shows how to configure Okta for authentication and authorization using access tokens.
Configure the client with the appropriate redirect URI. You can skip the group assignments in this step:Figure 1. Okta OIDC client creationFigure 2. Okta OIDC client configuration
Take note of the Client ID and the Okta domain. You will need them later when configuring the Okta parameters and the Well-known OpenID Connect endpoint in the neo4j.conf file:Figure 3. Okta OIDC client configuration
Create groups in Okta, assign users to them (the user can be added to a group either on user creation or editing the group), and map them in the
neo4j.confto native groups:Figure 4. Okta OIDC server groups
Configure the default authorization server (the one that shows
api://defaultas audience) to return the
groupsclaim in access tokens:Figure 5. Okta OIDC authorization serverFigure 6. Okta OIDC server claims
Configure Neo4j to use Okta authentication by configuring the following settings in the neo4j.conf file:
dbms.security.authentication_providers=oidc-okta dbms.security.authorization_providers=oidc-okta dbms.security.oidc.okta.display_name=Okta dbms.security.oidc.okta.auth_flow=pkce dbms.security.oidc.okta.well_known_discovery_uri=https://dev-21056049.okta.com/oauth2/default/.well-known/openid-configuration dbms.security.oidc.okta.audience=api://default dbms.security.oidc.okta.claims.username=sub dbms.security.oidc.okta.claims.groups=groups dbms.security.oidc.okta.params=client_id=0oa3oq6uw3uSOBf8y5d7;response_type=code;scope=openid profile email dbms.security.oidc.okta.authorization.group_to_role_mapping= "engineers" = admin; \ "collaborators" = reader
token_type_authenticationare omitted, meaning access tokens are used instead.
Log in with your Okta SSO credentials using the email of an
engineerrole user that results in an
adminrole in the database:Figure 7. Okta OIDC successful login
This example shows how to configure AAD for authentication and authorization using ID tokens.
Log in to the Azure portal.
Navigate to Azure Active Directory > Overview.
From the Add dropdown menu, select App registration and fill in the following information to create your SSO application:Figure 8. Azure OIDC client creation
The redirect URI
http://localhost:7474/browser/?idp_id=azure&auth_flow_step=redirect_uriis the URI that will accept returned token responses after successful authentication.
After the successful app creation, on the app’s Overview page, find the Application (client) ID value and record it for later.
Navigate to Endpoints and take note of the domain. It will be used later when configuring the well-known OpenIDC connect endpoint in the neo4j.conf file.Figure 9. Azure OIDC client config
There are two options to follow at this stage. The first one is to create groups in the Azure AD console, assign users to them, and map them in the neo4j.conf to native roles. In this case, the groups claim in the JWT will contain the ID of the group, so you have to map that ID to the desired native role later on:
On the Active Directory page, navigate to Groups and then select New group.
Fill in the required information.Figure 10. Azure OIDC server groups
Configure the server to return
groupMembershipClaimsin identity tokens, modifying the Manifest of the registered application:Figure 11. Azure OIDC server claims
Another way to achieve the authorization of SSO is via the app’s home page. The previous step described how to create groups in the Azure AD console, but this has a caveat: you can only have a maximum of 200 groups in a JWT. Navigate to App roles and add the Neo4j roles to the Azure active directory. They will be later used when mapping the group ID to the desired native role in the neo4j.conf file.
You can choose to follow only the group method or the app roles. No need to perform both steps.Figure 12. Azure OIDC app roles config
Configure Neo4j to use Azure authentication by configuring the following settings in the neo4j.conf file:
dbms.security.authentication_providers=oidc-azure dbms.security.authorization_providers=oidc-azure dbms.security.oidc.azure.display_name=Azure dbms.security.oidc.azure.auth_flow=pkce dbms.security.oidc.azure.well_known_discovery_uri=https://login.microsoftonline.com/ce976899-299d-4a01-91e5-a5fee8f98626/v2.0/.well-known/openid-configuration dbms.security.oidc.azure.audience=c2830ff5-86d9-4e38-8a2b-9efad6f3d06d dbms.security.oidc.azure.claims.username=email dbms.security.oidc.azure.claims.groups=groups dbms.security.oidc.azure.params=client_id=c2830ff5-86d9-4e38-8a2b-9efad6f3d06d;response_type=code;scope=openid profile email dbms.security.oidc.azure.config=token_type_principal=id_token;token_type_authentication=id_token dbms.security.oidc.azure.authorization.group_to_role_mapping= "e8b6ddfa-688d-4ace-987d-6cc5516af188" = admin; \ "9e2a31e1-bdd1-47fe-844d-767502bd138d" = reader
Log in with your Azure SSO credentials using the email of an
engineerrole user that results in an
adminrole in the database:
Remember to always set an email in contact info, otherwise login may not work properly at this stage.
This example shows how to use Google OpenID Connect for authentication using ID tokens in conjunction with native authorization.
Configure the client and the redirect URI:Figure 14. Google OIDC client creationFigure 15. Google OIDC client configuration
SSO authorization does not work with Google, as the JWT returned by Google does not contain information about the groups that a user belongs to, and cannot be configured to. Therefore, it is recommended to use native (or another flavor) authorization by creating a native version of the user in Neo4j.
The role assigned to the email used to log in with SSO, in this case,
email@example.com, must have
GRANT ROLEpermissions in the database (
nativeauthentication temporarily enabled):
CREATE USER `firstname.lastname@example.org` SET PASSWORD 'pass'; GRANT ROLE admin to `email@example.com`;
Configure Neo4j to use Google authentication by configuring the following settings in the neo4j.conf file:
dbms.security.authentication_providers=oidc-google dbms.security.authorization_providers=native dbms.security.oidc.google.display_name=Google dbms.security.oidc.google.auth_flow=pkce dbms.security.oidc.google.well_known_discovery_uri=https://accounts.google.com/.well-known/openid-configuration dbms.security.oidc.google.audience=345461137297-v9brpjmgbvbm3d5s9fq65tktevosd3rn.apps.googleusercontent.com dbms.security.oidc.google.claims.username=email dbms.security.oidc.google.params=client_id=345461137297-v9brpjmgbvbm3d5s9fq65tktevosd3rn.apps.googleusercontent.com;response_type=code;scope=openid profile email dbms.security.oidc.google.token_params=client_secret=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 dbms.security.oidc.google.config=token_type_principal=id_token;token_type_authentication=id_token
Log in with your Google SSO credentials using the email address and get the
adminrole when doing so:Figure 16. Azure OIDC successful login
The native authentication is disabled to prevent someone from logging in to firstname.lastname@example.org with the set password.
Assuming the client (Neo4j Browser or Bloom) can be accessed through the public internet, always use
pkce auth-flow rather than
implicit because the latter requires the client’s secret to be available to the public client.
In general, if both flows are available, it is recommended to opt for
pkce because it is more secure than
Google uses the pkce flow, but identity providers sometimes also use a client secret to ensure the client asking for a token is the one using it (pkce does not guarantee that).
The client secret does not add any additional security as it is public but the
pkce flow provides sufficient security.
When getting the message
Failed to get credentials: Could not parse JWT of type "access_token" on Browser, it probably means the provider only accepts ID tokens.
Change to ID tokens in your neo4j.conf:
It is generally safer to use access tokens when possible due to being shorter-lived. If authorization permissions change on the identity provider, Neo4j will fail authorization. Neo4j Browser will try to reconnect and reflect the changed permissions faster than if ID tokens were used.
Apart from the logs available in logs/debug.log and logs/security.log in the Neo4j path, you can also use the web-development console in your web browser when doing the SSO authentication flow with Bloom or Neo4j Browser. However, this could reveal potential problems as the one presented below with an example identity provider and the Cross-Origin Request policy:
The solution involves adding the redirect domain to the list of allowed domains in the provider (in this case,
Was this page helpful?