[RFC] Kerberos Support for Hugegraph

[hingu-8103]

Hi HugeGraph Dev Community,

I'd like to open a discussion on a proposed enhancement: Kerberos Support for Apache HugeGraph.

Motivation

In many enterprise environments, Kerberos is the standard authentication mechanism for SSO and
centralized identity management.
Adding native Kerberos support would make HugeGraph easier to adopt in Kerberos-first deployments
while keeping existing authentication flows intact.

Proposal

Introduce Kerberos support as an opt-in, additive capability across HugeGraph interfaces,
delivered in phases.
The implementation will use Java's built-in org.ietf.jgss.* (GSSAPI) and
javax.security.auth.* (JAAS), without adding new third-party dependencies.

Key Highlights

• Backward compatible: existing auth behavior remains unchanged unless Kerberos is enabled
• Phased delivery: REST first, then Gremlin WebSocket, Cypher API, and SDKs/toolkits
• Reusable foundation: server-side token validation and principal mapping are implemented once and reused
• Enterprise-friendly: fits existing Kerberos/SSO environments

Phase-wise Plan

Phase 1 — REST API:
Add Negotiate auth on the server and Kerberos support in the REST client.

Phase 2 — Gremlin WebSocket:
Add SASL GSSAPI support for Gremlin connections.

Phase 3 — Cypher API:
Add Kerberos handling for Cypher auth flow and client config.

Phase 4 — SDKs / Toolkits:
Add Kerberos support to language-specific clients and CLI tools.

---

RFC doc: Kerberos Auth Support for HugeGraph
I welcome feedback on scope, sequencing, and rollout expectations.

Best regards,
Dev Hingu

[hingu-8103]

Here's the link to the commit for PoC. (This PoC is generated with the help of github copilot).

[hingu-8103]

Hi @imbajin, Can you please provide your inputs for initiative ?
Thanks.

[imbajin]

Thanks for proposing this. Kerberos is a valid requirement in some enterprise, Hadoop, and Active Directory environments. However, the current community demand is not yet clear. This appears to be the only concrete Kerberos request in the HugeGraph repository, with limited feedback from potential users so far.^[8]

Therefore, we are open to exploring the capability, but we should avoid committing HugeGraph Core and all clients to a four-phase Kerberos roadmap before there is demonstrated adoption.

It would help if you could provide more concrete demand information:

• Which users or deployments currently require this capability?
• Why can the requirement not be addressed by an existing authentication gateway?
• Is the primary requirement REST, Gremlin WebSocket, or Cypher?
• Are the clients human SSO users, service accounts, or both?
• Which environments must be supported, such as MIT Kerberos or Active Directory?

Recommended architecture

Kerberos should be implemented as an external authentication plugin built on the existing HugeGraph authentication extension mechanism, with only a minimal generic compatibility change in Core.

Neo4j provides a useful reference. Its Kerberos implementation is distributed as a separate kerberos-add-on.jar. Neo4j Core exposes a generic authentication-provider SPI, while Kerberos-specific validation, keytab handling, configuration, and lifecycle remain inside the add-on. The plugin is installed and explicitly selected through configuration.^[6][7]

HugeGraph already has a similar foundation:

• auth.authenticator can select a custom authenticator implementation.^[2]
• The official documentation explicitly allows developers to implement HugeAuthenticator for integration with an external authentication system.^[1]
• HugeAuthenticator already extends TinkerPop's generic Authenticator SPI.^[3][5]
• TinkerPop's Authenticator accepts a generic credentials map and provides a separate stateful SASL negotiation interface.^[5]

We should reuse these existing extension points instead of adding Kerberos-specific parameters and methods throughout the authentication and authorization layers.

The remaining limitation is that the current REST AuthenticationFilter recognizes only Basic and Bearer. It rejects Negotiate before a custom authenticator can process it.^[4]

The Core adaptation should therefore be limited to a generic mechanism that allows an explicitly configured authenticator to declare and handle an additional HTTP authentication scheme:

AuthenticationFilter
|-- Basic       -> existing behavior
|-- Bearer      -> existing behavior
`-- other scheme
      `-- delegate only when the configured authenticator declares support
            `-- optional Kerberos plugin handles Negotiate

A Kerberos plugin could extend or delegate to StandardAuthenticator, preserving Basic and Bearer support while adding Negotiate.

Core boundaries

The HugeGraph Core change should meet the following constraints:

• Reuse auth.authenticator as the plugin configuration and loading mechanism.
• Add only a generic HTTP authentication-scheme capability to the existing authenticator SPI.
• Keep the SPI backward-compatible, preferably through a default method or an optional capability interface.
• Preserve the existing HugeAuthenticator.authenticate(username, password, token) signature.
• Do not add Kerberos-specific methods to AuthManager, StandardAuthManager, or StandardAuthManagerV2.
• Do not add Kerberos-specific initialization to GraphManager.
• Do not place JAAS, GSSAPI, keytab handling, principal mapping, or Kerberos configuration in Core.
• Reject unknown authentication schemes unless the configured authenticator explicitly declares support.
• Continue using HugeGraph's existing user, role, and authorization model after the plugin resolves an authenticated identity.
• Package the Kerberos implementation separately, ideally as an optional JAR that is not included or loaded by default.

When the plugin is absent, HugeGraph should not:

• Load any Kerberos classes.
• Initialize JAAS or GSSAPI.
• Read a keytab or Kerberos configuration.
• Change JVM-wide Kerberos properties.
• Add Kerberos-specific dependencies.
• Change existing Basic or Bearer behavior.
• Add measurable overhead to existing authenticated requests.

This is stronger isolation than adding an auth.kerberos.enabled=false option while keeping the implementation inside Core.

Concerns with the current PoC

The current PoC is useful for validating the idea, but it is too invasive for an optional feature:^[9]

• It changes a public HugeAuthenticator method signature.
• It adds a Kerberos-specific method to the central AuthManager interface.
• It modifies both StandardAuthManager implementations.
• It initializes Kerberos from GraphManager.
• It introduces static Kerberos state and JVM-wide configuration.
• It duplicates principal mapping in multiple authorization managers.
• It includes a UserAPI behavior change unrelated to Kerberos.
• The Negotiate path is not completely isolated by the enable switch.
• It does not include backward-compatibility or real Kerberos integration tests.

These changes create compatibility, security-review, and maintenance costs even for deployments that never use Kerberos. They do not yet satisfy the stated "opt-in and additive" requirement.

Suggested initial scope

Please revise the proposal around a smaller first phase:

1. Add only the minimal generic HTTP auth-scheme extension to the existing authenticator SPI.
2. Implement Kerberos REST authentication as a separate plugin.
3. Preserve all existing Basic and Bearer interfaces and behavior.
4. Keep Kerberos client helpers outside the default client artifact where possible.
5. Add regression tests proving that plugin-absent deployments behave exactly as before.
6. Add real Kerberos integration tests covering principal mapping, allowed realms, ticket expiry, replay handling, and SPNEGO negotiation.
7. Treat Gremlin, Cypher, and language-specific SDK support as separate follow-up proposals driven by concrete user demand.

Gremlin may later reuse TinkerPop's stateful SaslNegotiator SPI,^[5] but it should not be included in the first REST-focused change. Cypher and SDK support also introduce separate protocol, dependency, and maintenance concerns and should not be committed as part of the initial proposal.

In summary, the Kerberos use case is reasonable, but its necessity for the broader HugeGraph community is not yet demonstrated. We would support a lightweight plugin-oriented implementation that reuses auth.authenticator and adds only a small, generic, backward-compatible REST authentication SPI adaptation. We would not recommend merging the current cross-cutting implementation or committing to all four phases at this stage.

References

1. HugeGraph authentication configuration and custom HugeAuthenticator documentation
2. HugeGraph server configuration for auth.authenticator
3. HugeGraph HugeAuthenticator interface
4. HugeGraph REST AuthenticationFilter
5. Apache TinkerPop Authenticator SPI
6. Neo4j Kerberos Add-on deployment
7. Neo4j Kerberos Add-on usage
8. HugeGraph Kerberos RFC discussion
9. Current Kerberos PoC commit