[RFC] Apache Ranger Authorization Plugin for HugeGraph

[vaijosh]

Summary

This RFC proposes adding an optional hugegraph-ranger-plugin module that allows HugeGraph to delegate authorization decisions to Apache Ranger while continuing to use HugeGraph's native store for user identity and credentials.

Google document is available at https://docs.google.com/document/d/1j-OITmUTVrsMjTNiUuQVXCyt213lSkdevA50rj5xDr8/edit?usp=sharing

A working implementation is available at https://github.com/vaijosh/hugegraph/tree/RangerPlugin

---

Motivation

Currently, authorization in HugeGraph is enforced by HugeGraphAuthProxy, which checks operations against a RolePermission object produced by AuthManager (StandardAuthManager or StandardAuthManagerV2).

However, organizations using Apache Ranger to centralize access control across their Hadoop and data infrastructure (HDFS, Hive, HBase, Kafka, Solr) lack a supported way to bring HugeGraph under the same policy umbrella. Ranger provides attribute- and tag-based policies, group-based grants, explicit deny overrides, and centralized auditing.

We propose adding an opt-in Ranger plugin module so HugeGraph can delegate its permission decisions to Ranger out of the box.

---

Non-Goals

• No Authentication Changes: Does not alter StandardAuthenticator or password/JWT authentication (matchUser, loginUser).
• No Ranger UI Replication: Existing auth-entity REST APIs (createAccess, createBelong, createTarget, etc.) remain the local record-keeping path.
• No Sub-Resource Masking: Does not introduce granularity beyond HugeGraph's ResourceObject model (graph space / graph / resource type / label).

---

Architecture & Design Highlights

1. Two-Tier Enforcement Model

• Tier 1 (Login Level - Coarse): RangerAuthManager.authenticate() delegates credential validation to the local store and merges Ranger grants into RolePermission so per-session caching works unmodified.
• Tier 2 (Per-Request Level - Fine-Grained): Introduces a ResourceAuthorizer interface hook in hugegraph-core. When registered, verifyResPermission() evaluates requests against live Ranger policies.
  • Tier 2 can only narrow access already granted by Tier 1 local checks—never expand it.
  • Admin requests bypass denial checks (maintaining trust boundaries) but are still recorded in Ranger's audit log.
  • Bulk-Read Sampling: Iterator-based reads (paging through vertices/edges) are rate-limited per (username, graphSpace, graph, resourceType) to avoid excessive policy calls and log volume.

2. Ranger Resource Hierarchy

A 4-level resource hierarchy is introduced in Ranger for HugeGraph:

graphspace  (e.g., "DEFAULT", "*")
└─ graph    (e.g., "hugegraph", "*")
   └─ resource-type  (VERTEX, EDGE, SCHEMA, GREMLIN, …)
      └─ label        (vertex/edge label name, "*")

Access types directly map to HugeGraph's HugePermission enum (read, write, delete, execute, admin).

3. Plugin Components (hugegraph-ranger-plugin)

Built to bytecode target 8 for Ranger Admin compatibility:

• RangerHugeGraphAuthenticator: Drop-in auth.authenticator implementation.
• RangerAuthManager: Delegates identity operations and merges Ranger grants.
• RangerHugeGraphPlugin: Translates HugeGraph resource requests to Ranger access requests.
• RangerHugeGraphService: Runs inside Ranger Admin's JVM to power connectivity testing and autocomplete in the policy editor.

---

Configuration & Packaging

Configuration (rest-server.properties)

auth.authenticator=org.apache.hugegraph.ranger.RangerHugeGraphAuthenticator
auth.ranger.service_name=hugegraph
auth.ranger.config=/etc/ranger/hugegraph/ranger-hugegraph-security.xml

Build Integration

The plugin is fully opt-in via a Maven profile (-Dwith-ranger-plugin) in hugegraph-dist, ensuring core builds remain lightweight without pulling in Hadoop dependencies unless explicitly requested.

---

Open Questions for the Community

1. Dependency Packaging: Is embedding ranger-plugins-common (and its Hadoop dependency tree) as an opt-in Maven profile (-Dwith-ranger-plugin) acceptable, or should this plugin be maintained in a separate downstream repository?
2. Hook Placement: Should ResourceAuthorizer live in hugegraph-core (as implemented) or be moved to hugegraph-api alongside HugeGraphAuthProxy?

---

Next Steps

If the design direction is acceptable, we will open a Pull Request against master from the RangerPlugin branch.

We welcome your feedback and suggestions!