Neo4j Aura with Azure SSO Integration

This application demonstrates how to connect to Neo4j Aura using Azure Single Sign-On (SSO) authentication.

Prerequisites

• Node.js installed
• An Azure account with an App Registration
• A Neo4j Aura database instance
• Required npm packages (see package.json)

Configuration

Before running the application, you need to configure the following parameters in connect-aura-azure.js:

Azure App Registration Parameters

Azure App Registration

• Use mobile and desktop application platform config
• Allow public client flows
• For my poc, I set redirect uri to localhost:3000 which allowed me to simulate auth to Azure and then obtain the id_token
• Added email and preferred_username as optional claims
• Added groups via the Add groups claim UI with Group ID format

Aura SSO Configuration

You would need to work with Aura Product Support team to enable SSO for your Aura instance. A sample configuration is provided below:

dbms.security.oidc.untonium-programmatic.display_name=<some_name_here>
dbms.security.oidc.untonium-programmatic.auth_flow=pkce
dbms.security.oidc.untonium-programmatic.well_known_discovery_uri=https://login.microsoftonline.com/<AZURE_TENANT_ID>/v2.0/.well-known/openid-configuration
dbms.security.oidc.untonium-programmatic.params=client_id=<AZURE_CLIENT_ID>;response_type=code;scope=openid profile email offline_access
dbms.security.oidc.untonium-programmatic.config=principal=sub;code_challenge_method=S256;token_type_principal=id_token;token_type_authentication=id_token
dbms.security.oidc.untonium-programmatic.claims.username=email
dbms.security.oidc.untonium-programmatic.claims.groups=groups
dbms.security.oidc.untonium-programmatic.authorization.group_to_role_mapping=<Azure Security Group Object ID my user is part of>=admin
dbms.security.oidc.untonium-programmatic.audience=<Azure_CLIENT_ID>

You would need to provide the AZURE_* parameters to the Aura Product Support team.

Neo4j Aura Parameters

const auraDbId = "YOUR_AURA_DB_ID";

const azureAppClientId = "YOUR_CLIENT_ID";
const azureAppTenantId = "YOUR_TENANT_ID";
const azureAppRedirectUri = "YOUR_REDIRECT_URI"; // e.g. "http://localhost:3000"

Neo4j Aura Parameters

const auraDbId = "YOUR_AURA_DB_ID";

Security Note

The current configuration has these values hardcoded. TODO: move to env variables

How It Works

1. The application uses PKCE (Proof Key for Code Exchange) for secure OAuth 2.0 authentication
2. When run, it will open your default browser for Azure login
3. After successful authentication, it will connect to your Neo4j Aura instance using the obtained token
4. A test query will be executed to verify the connection

Running the Application

1. Install dependencies:

npm install

2. Run the application:

node connect-aura-azure.js

Security Features

• Uses PKCE for enhanced OAuth security
• Implements Azure SSO for authentication
• Uses bearer token authentication for Neo4j Aura

Further Learning Resources

PKCE (Proof Key for Code Exchange)

• Auth0's Guide to Authorization Code Flow with PKCE - Comprehensive guide explaining PKCE implementation
• OAuth.com PKCE Playground - Interactive demo of PKCE flow
• OAuth 2.0 Security Best Practices - Official OAuth 2.0 documentation on PKCE

Understanding the Security Flow

1. Code Verifier Generation:
   • Random string between 43-128 characters
   • Uses A-Z, a-z, 0-9, and punctuation characters -._~
2. Code Challenge Creation:
   • SHA256 hash of the code verifier
   • Base64URL encoded for safe transmission
3. Security Benefits:
   • Prevents authorization code interception attacks
   • Protects against CSRF (Cross-Site Request Forgery)
   • Ensures only the original client can exchange the code for tokens

Implementation Details

The code in this repository implements PKCE by:

• Generating a cryptographically secure code verifier
• Creating a code challenge using SHA-256 hashing
• Implementing proper base64URL encoding for URL safety
• Verifying the code challenge during token exchange

For more details about the implementation, see the code comments in connect-aura-azure.js.

Azure MSAL Node.js Resources

Official Documentation

• MSAL Node.js SDK Documentation - Complete API reference
• Microsoft Identity Platform Overview - Overview of MSAL and authentication concepts
• MSAL Node GitHub Repository - Source code and samples

Key Features Used in This Project

1. PublicClientApplication - Used for implementing OAuth 2.0 flows
2. PKCE Authentication - Enhanced security for authorization code flow
3. Token Cache Management - Secure handling of access and refresh tokens
4. Azure AD Integration - Seamless connection with Azure Active Directory

Code examples and useful tutorials

• Authorization Code Flow with PKCE
• MSAL Node Samples
• Azure AD Authentication Best Practices

Interactive Login Flow

The application implements an interactive login flow using MSAL Node.js SDK. Here's how it works:

1. URL Generation

   const authCodeUrlParameters = {
     scopes,
     redirectUri,
     codeChallenge,
     codeChallengeMethod: "S256",
   };
   const authCodeUrl = await pca.getAuthCodeUrl(authCodeUrlParameters);

   The code generates a secure Azure login URL with PKCE parameters.

2. Browser Launch

   await open(authCodeUrl);

   Opens your default browser to the Azure login page.

3. Callback Handling

   const server = http
     .createServer(async (req, res) => {
       // Handle the Azure callback with authorization code
     })
     .listen(3000);

   • Starts a local server on port 3000
   • Waits for the Azure callback after successful login
   • Exchanges the authorization code for an ID token
   • Uses the ID token to connect to Neo4j Aura

The entire flow is handled in the getTokenInteractive() function in connect-aura-azure.js. After successful authentication, the token is used by connectToAura() to establish a secure connection to your Neo4j Aura database.

For more details about the implementation, see the code comments in connect-aura-azure.js.

MSAL Authentication Abstraction

The Microsoft Authentication Library (MSAL) significantly simplifies the OAuth2.0 implementation by abstracting complex authentication flows. Here's how:

1. Simple Configuration

   const config = {
     auth: {
       clientId: azureAppClientId,
       authority: `${baseAzureUrl}/${azureAppTenantId}`,
     },
   };
   const pca = new PublicClientApplication(config);

   Just provide basic app credentials, and MSAL handles the rest.

2. Automated URL Generation

   const authCodeUrl = await pca.getAuthCodeUrl(authCodeUrlParameters);

   MSAL automatically:

   • Constructs the proper OAuth2.0 authorization URL
   • Adds required protocol parameters
   • Includes PKCE challenge
   • Manages state parameters
   • Handles Azure AD endpoints

3. Token Acquisition

   const tokenResponse = await pca.acquireTokenByCode(tokenRequest);

   MSAL manages:

   • Token exchange
   • PKCE verification
   • Token validation
   • Token caching
   • Error handling

Without MSAL, we would need to implement all these OAuth2.0 and PKCE components manually, making the code much more complex and error-prone. MSAL ensures we follow security best practices while keeping the implementation clean and maintainable.