Docs Feedback modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc (ref: 5.x)

[ZipingL]

Docs Feedback: OIDC SSO Redirect URI is Incompatible with Multi-Tenant Azure AD Apps

Reference:
File: modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc

Documentation: Neo4j SSO Configuration Tutorial (5.x) — Register the Application

---

Problem

The Neo4j documentation instructs users to register the following redirect URI in Azure AD for Neo4j Browser SSO:
https://neo4j.com/docs/operations-manual/5/tutorial/tutorial-sso-configuration/#_register_the_application

http://localhost:7474/browser/?idp_id=azure&auth_flow_step=redirect_uri

While we have verified that this is technically possible for a single-tenant SPA registration, the documentation critically fails to mention that this approach completely fails for multi-tenant applications. When an app is configured to support multiple organizational directories, Azure AD's security validation becomes stricter and correctly forbids registering redirect URIs with query parameters. See below of the documentation which details the steps.

This makes the documentation's guidance a blocker for any enterprise or SaaS use case that requires multi-tenant support for guests or federated users. The result is that for any common multi-tenant setup, the documented approach is not possible. Azure rejects the URI with the following error:

Furthermore, even in the single-tenant case where it is allowed, using the redirect_uri to pass application state is an insecure anti-pattern. The correct and secure method for this is the state parameter provided by the OAuth 2.0 and OIDC specifications.

• The Standard Method (using state): The client (Neo4j Browser) should generate a unique, opaque value for the state parameter to maintain context between the request and the callback. This is the industry standard for preventing Cross-Site Request Forgery (CSRF) attacks.

• The Neo4j Browser Method (insecure and limited): By embedding metadata like idp_id directly into the redirect_uri, Neo4j Browser not only breaks compatibility with multi-tenant applications but also misuses a critical security parameter, forcing users into a less secure, single-tenant-only configuration.

---

Impact

• Google OIDC works only because Google is more lenient regarding query parameters in redirect URIs.
• The documented method is incompatible with multi-tenant Azure AD configurations, a common enterprise requirement.
• Even when a valid URI like /browser/oauth/callback is registered and set in neo4j.conf, Neo4j Browser appears to ignore this and still sends the invalid query-parameter-based URI, causing authentication to fail.
• This forces users into a brittle, non-standard OIDC integration.

---

Steps to Reproduce

1. Register a single-tenant Azure AD App with the redirect URI .../?idp_id=azure&auth_flow_step=redirect_uri. Observe that Azure accepts this URI.
2. Now, change the application to be multi-tenant ("Accounts in any organizational directory").
3. Attempt to save the same redirect URI. Observe that Azure rejects it, proving the documented method is incompatible with multi-tenancy.

---

Expected Behavior

• Neo4j Browser and its documentation should align with OAuth 2.0/OIDC best practices by using a static, query-free redirect_uri (e.g., https://<host>:7474/browser/oauth/callback) and leveraging the state parameter for passing application context, ensuring compatibility with all tenancy models.

---

Request

• Please update the documentation to explicitly state that the current method is only compatible with single-tenant applications and will fail for multi-tenant setups.
• Please confirm if this behavior in Neo4j Browser is a known bug and provide a timeline for a fix that aligns with modern security standards.
• Provide a clear and reliable workaround for users who need to integrate with Azure AD for SSO in a multi-tenant environment.

---

Environment

• Neo4j 5.x self-hosted
• Azure AD App Registration
• OIDC with PKCE flow