Single Sign-On (SSO)

AuraDB Virtual Dedicated Cloud AuraDB Business Critical AuraDS Enterprise

Single Sign-On (SSO) enables organization owners and 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.

SSO levels

Users with either the Organization admin or the Organization owner role can configure SSO at both the organization-level and project-level.

  • Organization-level: Allows org admins to control how users log in when they are trying to access the organization. It is a log-in method for the Aura console.

  • Project-level: Impacts new database instances created within that project. It ensures users logging in with SSO have access to the database instances within the project. It depends on RBAC if the user can access and view or modify data within the instances themselves. For this level, the role mapping may be used to grant users different levels of access based on a role in their IdP. It does not give access to edit the project settings, for example to edit the project name, network access, or to edit the instance settings such as to rename an instance, or pause and resume.

Log-in methods

Log-in methods are different for each SSO level. Administrators can configure a combination of one or more of the log-in methods.

Supported log-in methods at the organization-level:

  • Email/password

  • Okta

  • Microsoft Entra ID

  • Google SSO (not Google Workspace SSO)

At the organization-level, admins can disable email/password and Google SSO if one other custom SSO provider is configured.

Supported log-in methods at the project-level:

  • User/password

  • Okta

  • Microsoft Entra ID

At the project-level, admins cannot disable user/password.

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. From the Organization settings, go to 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 project-level, or both.

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

A screenshot of the SSO configuration
Figure 1. SSO configuration

Log-in link

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

Role mapping

Role mapping applies to all new instances created within the selected project. To configure role mapping for an individual instance, contact support.

Individual instance-level

Support can assist with SSO configurations at instance-level including:

  • Role mapping specific to a database instance

  • Create custom claims besides groups

  • Updating SSO on already running instances

If you require support assistance, visit Customer Support and raise a support ticket including the following information:

  1. The Project ID of the projects you want to use SSO for. Click on the project settings to copy the ID.

  2. The name of your IdP

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 Settings > 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 Org 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 as needed:

    1. For organization-level SSO, no additional settings needed.

    2. For project-level SSO, enter role mappings if applicable.

  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 Project-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. Select Next.

  5. For Grant type select Authorization Code.

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

  7. Save.

  8. In the Aura console, go to Organization Settings > 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 Org 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 Okta.

  11. For Client ID enter the Okta Client ID.

  12. For Client Secret enter the Client Secret.

  13. Select discovery method:

    1. For Discovery URI take the domain from your Okta portal which should be something like 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.

  14. Configure any additional settings as needed:

    1. For organization-level SSO, no additional settings needed.

    2. For project-level SSO, enter role mappings if applicable.

  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 Project-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 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 via Aura console invites and access management like with any other organization.

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.