Single Sign-On (SSO)
AuraDB Business CriticalAuraDB Virtual Dedicated CloudAuraDS Enterprise

Single Sign-On (SSO) enables organization owners and organization admins to use your organization’s identity provider (IdP) to authenticate users so they can access the Aura console and Aura instances.

Aura supports SSO authentication and authorization using Microsoft Entra and Okta as IdPs, implementing the OpenID Connect (OIDC) protocol.

As the service provider, Neo4j Aura redirects authentication requests to the configured IdP using the OpenID Connect (OIDC) protocol. Aura also supports authenticating with Google as the identity provider. When a user attempts to log in, Aura generates a redirect URL with authentication parameters and sends the user to the IdP for authentication. After successful authentication, the IdP redirects the user back to Aura with a secure token, allowing Aura to establish an authenticated session.

Required roles

The person setting up SSO needs an Organization Owner or Organization Admin role. For information on how to assign roles see User management.

Login methods for Aura

Each Aura organization is configured with the following login methods that allow logging into the Aura Console (https://console.neo4j.io):

  • Email/password

  • Social Login

    • Google

    • Microsoft

    • Github

Additionally each organization can configure SSO. Note: An Organization with SSO enabled as a login method for the Aura Console can deactivate the login methods listed above.

Configuring SSO

Setting up SSO in Aura requires two key access control decisions. First, you must register your Identity Provider with Aura. Then, determine whether to enable SSO for Console access, Instance access, or both.

SSO levels

1. Aura Console SSO

  • Authenticates users so they can log into the Neo4j Aura Console UI (console.neo4j.io). The user is logging into the Management Plane.

  • Authentication: Enables users to log into the Aura Console via your Identity Provider (IdP) to manage the lifecycle of your instances.

  • It controls: How team members log in to manage billing, view metrics, create or delete projects, and provision new databases.

  • Authorization: Role management for projects, billing, and metrics is not currently handled via the IdP, and needs to be managed either via the UI or Aura API.

2. Instance SSO

  • Authenticates users or applications into individual Neo4j database instances (e.g., via Neo4j Browser, Bloom, or Drivers). The user is logging into the Data Plane.

  • Authentication: Enables authentication for users or applications directly into specific Neo4j DBMS/instances (e.g., via Neo4j Browser, Bloom, or drivers) within an Aura Project.

  • Authorization: It ensures that when someone connects to a database instance within a specific project, they authenticate against your Identity Provider (IdP). You can use IdP group-to-role mapping to assign RBAC database privileges (such as admin, architect, or reader) based on their SSO groups. This optional setting in the configuration dialog is called role mapping.

SSO Administration

To simplify administration, a single SSO configuration can be used for both the Aura Console and database instances by selecting the corresponding checkboxes during setup: "Use as login for the Organization" and "Use as login method for instances within Projects in this Org". These settings serve as the default for all instances within a project. Consequently, instances should be grouped into projects based on their shared SSO login requirements.

Instance SSO Overrides

Organization or project administrators can deviate from organization-wide defaults by applying overrides to individual instances. This is useful when a few instances require custom role mappings, while the organization-level configuration could remain empty. Currently, the fields available for override at the Instance level are Display Name and Role Mapping.

Display name

The Display Name is the label shown to users when they choose to login with SSO while connecting to an instance.

It only changes the name displayed in the Aura connection dialog shown when users connect to the instance (e.g. Neo4j Dev).

Display name
Figure 1. Instance connection dialog showing the customized SSO display name.

Legacy SSO Configurations

Historically, certain custom SSO configurations—such as Groups, Username, Scope, and Token parameters were managed via support tickets. While these configurations were previously not visible in the Organization settings page, they are now accessible and editable directly within the console.

Important notes

  • Configuration propagation: Applying edits to these SSO configurations will update all instances sharing that configuration.

  • Legacy state: Some legacy configurations may exist in an orphaned state. We recommend creating new configurations to utilize current SSO management capabilities where possible.

Setup requirements

Accessing Aura with SSO requires:

Aura requires the Authorization Code Flow, an OAuth2 authentication method that involves redirecting users to a publicly accessible IdP server for login.

To create an SSO Configuration, either a Discovery URI or a combination of Issuer, Authorization Endpoint, Token Endpoint, and JWKS URI is required.

Create a new SSO configuration

  1. Go to Organization settings > Security > Single Sign-On to set up a new SSO configuration.

  2. The checkboxes Use as a log in for the Organization and Use as login method for instances with projects in this Org define whether SSO should be only on organization-level, only on instance-level, or both.

  3. The required basic SSO configuration information can be retrieved from the IdP. Entering the Discovery URI pre-fills the fields. If this is not known these fields can be completed manually.

Custom configuration settings (optional)

In addition to the standard settings, you can optionally configure custom token settings. For more information, see Operations Manual → Configuration Settings

Most organizations can use the default values. Only modify these settings if required by your identity provider or authentication configuration.

If you use Attribute-Based Access Control (ABAC), Aura supports the following identity attributes: email, email_verified, name, preferred_username, and groups. Self-managed Neo4j deployments can use additional identity provider attributes. See Operations Manual > ABAC for more information.

Example setup

If you want users to authenticate with SSO for both the Aura Console and your database instances, make sure to select both of the following checkboxes during setup:

  • Use as login for the Organization

  • Use as login method for instances within Projects in this Org

A screenshot of the SSO configuration
Figure 2. SSO configuration form

Log-in link

After setting up SSO, the Organization SSO login link can be found in the organization summary page in the Aura console.

A screenshot of an example SSO set up
Figure 3. Successful SSO setup

Role mapping

The SSO option for group to role mapping can map a group from an SSO provider to any role defined in the instance. If the same SSO configuration for multiple instances is used, that same mapping applies. This access then applies to all newly created instances the user has access to.

Multiple group to role mappings can be defined, and multiple roles can be given to any SSO group. The role field can be a comma separated list.

For Azure and Microsoft Entra ID use the Object ID of the group, not the group name. For OIDC use the group name.

By default, role mappings apply to all instances that inherit the SSO configuration.

role mapping ui
Figure 4. Example role mapping in the Aura console

Updating SSO configurations

  • Changes made to an SSO configuration are automatically applied to running instances that inherit that configuration. So you do not need to reconfigure each instance individually.

  • If multiple instances require the same configuration, place them in a separate project and configure SSO at the project-level.

Instance-level SSO overrides

  • Overrides will still prevail if you have overrides. Only the overridden fields are frozen; everything else on that instance still updates.

  • Example: If role mapping is overridden on an instance and the linked SSO config’s username claim is updated, the instance will still receive this update when the configuration is applied. If the linked SSO config’s role mapping is edited, the instance override prevails.

Editing SSO configs at an organization-level or project-level does not change SSO configuration to instances that have overrides.

To view whether an instance inherits its SSO configuration or has an override, open the SSO Membership tab in the instance Inspect view.

override example
Figure 5. Override example

Microsoft Entra ID SSO

  1. In the Azure Portal, go to App Registrations and then New Registration.

  2. Add a name for the new app registration and select Register. Skip redirect URI’s for now.

  3. On the app overview page, take note of the Application (client) ID.

  4. Select the Client Credentials link to open the client credentials page.

  5. Create a new secret and copy the Value field, it won’t be visible after leaving the page.

  6. Go back to the App Overview page and open the App Endpoints and take note of the OpenID Connection metadata document URI

  7. Under Authentication in the left-hand navigation, setup redirect URLs:

    1. Adding a new Web platform

    2. Enter https://login.neo4j.com/login/callback as the redirect URI.

  8. In the Aura console, go to Organization > Security > Single Sign On > New configuration

  9. Select how you want the SSO configuration to be applied in Aura:

    1. Use as a log in method for the Organization applies to organization-level logins (which acts as a login to the Aura console).

    2. Use as a login method for instances within Projects in this Organization applies to the project-level and you can select specific projects within the organization (where login is on the instance).

    3. Or, select both.

  10. For IdP Type select Microsoft Entra ID.

  11. For Client ID enter the Application (client) ID from the Azure app.

  12. For Client Secret enter the client secret value (not secret id) from the secret you created in the Azure app.

  13. For Discovery URI enter the OpenID Connect metadata document URI.

  14. Configure any additional settings if required by your identity provider.

    1. Instance-level SSO: Optionally configure role mappings, token request scopes, username claims, group claims, and additional token parameters.

    2. Organization-level SSO: No additional configuration is available.

  15. Select Create

  16. Select the additional log in methods:

    1. For Organization-level testing it is recommended to keep the Email/password or Google log-in method enabled, so that if SSO fails, you can still access the Aura console and adjust the configuration.

    2. For instance-level testing the user/password login is always available on the instance, so if SSO isn’t working, the instance is still accessible.

Token request scopes

When requesting the token from Azure, the scopes Aura sends are:

  • openid access to a unique identifier to identify the user.

  • profile access to basic profile information.

  • email contains the user’s email address.

This will result in Azure asking for consent to display details related to these scopes. For more information, see OpenID Connect Scopes

Okta SSO

  1. In the Okta admin portal go to Applications and then Create App Integration.

  2. For Sign-in method select OIDC - OpenID Connect.

  3. For Application type select Web Application.

  4. For Sign-in redirect URIs add https://login.neo4j.com/login/callback as the redirect URI.

  5. Save.

  6. In the Aura console, go to Organization > Security > Single Sign On > New configuration.

  7. Select how you want the SSO configuration to be applied in Aura:

    1. Use as a log in method for the organization applies to organization-level logins (which acts as a login to the Aura console).

    2. Use as a login method for instances within Projects in this Organization applies to the project-level and you can select specific projects within the organization (where login is on the instance).

    3. Or, select both.

  8. For IdP Type select Okta.

  9. For Client ID enter the Okta Client ID.

  10. For Client Secret enter the Client Secret.

  11. Select discovery method:

    1. For Discovery URI take the domain from your Okta portal (for example https://dev-123-admin.okta.com/) and add .well-known/openid-configuration. The final URL should look similar to https://dev-123-admin.okta.com/.well-known/openid-configuration.

    2. Alternatively, you can select Manual Configuration and enter the values separately, including Issuer, Authorization Endpoint, Token Endpoint and JWKS URI.

  12. Configure additional settings if required by your identity provider.

    1. Instance-level SSO: Optionally configure role mappings, token request scopes, username claims, group claims, and additional token parameters.

    2. Organization-level SSO: No additional configuration is available.

  13. Select Create.

  14. Select the additional log in methods:

    1. For Organization-level testing it is recommended to keep the Email/password or Google log-in method enabled, so that if SSO fails, you can still access the Aura console and adjust the configuration.

    2. For instance-level testing the user/password login is always available on the instance, so if SSO isn’t working, the instance is still accessible.

FAQ

Can users get organization roles added to them in Aura console via SSO and a group to role mapping?

No, users must be granted the role on the organization (e.g. Owner, Admin, Member) via Aura console invites or the access management API.

For Microsoft Entra only: Why am I unable to connect to the instance after completing the SSO login, the connection is showing as unconnected?

Ensure that the email field is provided on your user in Microsoft Entra ID. If it already is, contact support for further assistance.

What happens if I enable/disable tool authentication on an instance

Enabling tool authentication will no longer allow Aura Console users to connect to an instance with instance SSO. Drivers and external tools remain unaffected. For more information see Tool authentication with Aura user.