[vaijosh]

Purpose of the PR

• close [Feature] Apache Ranger Authorization Plugin for HugeGraph #3272
• Introduce Apache Ranger-based authorization for HugeGraph to support centralized policy management and auditability, while continuing to use HugeGraph’s existing user/token identity model.

Main Changes

• Added a new module: hugegraph-server/hugegraph-ranger-plugin

  • RangerHugeGraphAuthenticator: plugs Ranger into HugeGraph auth flow via auth.authenticator.
  • RangerAuthManager: delegates identity CRUD/login to existing HugeGraph auth manager, then merges Ranger grants into RolePermission.
  • RangerHugeGraphPlugin: wraps RangerBasePlugin, maps HugeGraph resource/permission model to Ranger access requests, and enables audit result processing.
  • RangerHugeGraphService: Ranger Admin-side service for Test Connection and policy editor resource autocomplete (graphspace -> graph -> resource-type -> label).
  • RangerOptions: adds keys for auth.ranger.service_name and auth.ranger.config.
  • Added service/config resources:
    • ranger-servicedef-hugegraph.json
    • ranger-hugegraph-security.xml
  • Added unit tests in RangerHugeGraphPluginTest.

• Added end-to-end integration assets under docker/hgRangerIntegration

  • Dockerfile.hugegraph: builds HugeGraph image with Ranger plugin enabled.
  • Dockerfile.ranger: bakes thin HugeGraph Ranger service jar into Ranger Admin classpath.
  • docker-compose.yml: 4-service stack (Ranger Admin + Postgres + Solr + HugeGraph).
  • Audit bootstrap/config files (ranger-audits-conf/*, solr-init.sh, ranger-hugegraph-security.xml, rest-server.properties, hugegraph.properties).
  • Integration docs:
    • docker/hgRangerIntegration/README.md
    • docker/hgRangerIntegration/ranger-integration-test-guide.md

• Packaging/compatibility notes

  • Plugin module includes shaded packaging for runtime compatibility and dependency isolation.
  • Compiled for Java 8 target compatibility with Ranger Admin runtime.
  • Default HugeGraph behavior remains unchanged unless Ranger authenticator/config is explicitly enabled.

Verifying these changes

• Trivial rework / code cleanup without any test coverage. (No Need)
• Already covered by existing tests, such as (please modify tests here).
• Need tests and can be verified as follows:
  • Unit test (executed):
    • mvn -pl hugegraph-server/hugegraph-ranger-plugin -am -Dtest=RangerHugeGraphPluginTest -DfailIfNoTests=false test -DskipITs -DskipIntegrationTests -Drat.skip=true -Dcheckstyle.skip=true
    • Result: PASS (Tests run: 4, Failures: 0, Errors: 0, Skipped: 0)
  • Integration validation guide:
    • Follow docker/hgRangerIntegration/README.md or docker/hgRangerIntegration/ranger-integration-test-guide.md for policy enforcement, cache-refresh, dynamic policy update, and audit checks.

DDoes this PR potentially affect the following parts?

• Dependencies (add/update license info & regenerate_known_dependencies.sh)
• Modify configurations
• The public API
• Other affects (Docker-based Ranger integration test stack and setup docs)
• Nope

Documentation Status

• Doc - TODO: required documentation is pending; complete it before merging.
• Doc - Done: documentation is included here or linked below.
• Doc - No Need: no user-visible documentation is affected.

Documentation files in this PR or paired hugegraph-doc PR:

• docker/hgRangerIntegration/README.md
• hugegraph-server/hugegraph-ranger-plugin/src/main/resources/ranger-servicedef-hugegraph.json
• hugegraph-server/hugegraph-ranger-plugin/src/main/resources/ranger-hugegraph-security.xml

Visual overview

Proposed integration architecture, not a claim of verified policy enforcement or audit completeness.

Conceptual illustrations; not test, benchmark, security, or release-acceptance evidence.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.57%. Comparing base (0abd931) to head (f09a5d8).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3273      +/-   ##
============================================
+ Coverage     58.53%   58.57%   +0.03%     
- Complexity     2717     3091     +374     
============================================
  Files           779      779              
  Lines         69439    69470      +31     
  Branches       9577     9674      +97     
============================================
+ Hits          40647    40689      +42     
+ Misses        25101    25088      -13     
- Partials       3691     3693       +2     

Flag	Coverage Δ		*Carryforward flag
commons	96.37% <ø> (ø)
hstore	36.02% <7.50%> (-0.07%)	⬇️
pd	56.80% <ø> (ø)
server_hbase	42.63% <ø> (+0.08%)	⬆️	Carriedforward from dcfc2cd
server_memory	56.73% <100.00%> (+0.07%)	⬆️
server_rocksdb	43.02% <77.50%> (-0.08%)	⬇️
store	36.23% <ø> (ø)

*This pull request uses carry forward flags. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[bitflicker64]

Blocking: yes. Summary: The Ranger authorizer hook can be bypassed. When its rate limiter has no permit left it allows the request, so per-label deny policies stop working for list reads. Separately, init-store now creates the admin with the public default password pa for every built-in-auth install, whether or not Ranger is used. Within the plugin, the default-graph and default-role calls fail through reflection, Ranger grants never apply outside graph space DEFAULT, the pinned Ranger 2.4.0 has a critical CVE, and CI never builds the module. The branch also carries 37 commits already on master, replayed with new SHAs (#3140 to #3218), so GitHub shows 370 files. The PR conflicts with master (mergeStateStatus DIRTY). Rebasing onto current master would cut the diff down to the 31 files this PR really changes. Evidence: compared head 4057f3f with upstream 0a3e4ae (#3218, the last replayed commit). That diff is the full delta: 31 files, +8697/-9. I read every hand-written Java, POM, Dockerfile and compose file in it, plus the service definition and the integration README's policy model. I traced the callers in HugeGraphAuthProxy, HugeAuthenticator.RolePerm, GraphManager, AuthenticationFilter, GraphsAPI, GraphSpaceAPI and InitStore. Local repros: Guava RateLimiter.create(1000.0) granted 2 of 10000 back-to-back tryAcquire() calls, and a JDK 17 two-package repro showed that a reflective call on a package-private class throws IllegalAccessException. CI: dependency-review fails on GHSA-c87w-642h-m97h, which this PR introduces. dependency-check failed on a Maven Central 429, which is not caused by this PR.

[bitflicker64]

Blocking: yes. Summary: The rate-limiter bypass, the Ranger 2.4.0 CVE, the hard-coded Dockerfile version, the notebook and the Test Connection 401/403 handling are fixed at this head, and HugeGraphAuthProxyTest now covers the authorizer hook. A Ranger policy scoped to a graph space or graph still grants nothing at login, so Ranger-only users with such policies cannot log in, and the earlier comments on init-store, the reflective default-role calls, the DEFAULT-only role, CI never building the module, and the per-request probes still apply.

The earlier review comments below still apply at f02c8f4; this head does not fix them.

• Important: Blocking: yes. Summary: init-store.sh no longer asks for the admin password. Before this change the line called the private initAdminUser(), which reads the password from the console or stdin. It now passes auth.admin_pa, whose default is the public value pa. A bare-metal install that enables the built-in authenticator and does not set auth.admin_pa now gets an admin account with password pa, with no prompt and no warning. This affects every StandardAuthenticator user, not only Ranger users. Evidence: at 0a3e4ae5f (master's #3218, the base this PR replays) this line is auth.initAdminUser();, and that method calls this.initAdminUser(this.inputPassword()). ServerOptions.ADMIN_PA defaults to "pa", and the shipped conf/rest-server.properties leaves #auth.admin_pa=pa commented out. hugegraph-dist/docker/docker-entrypoint.sh (line 222) still documents that init-store reads the password from stdin. With this change, initAdminUser() and inputPassword() are dead code. Fix: use auth.admin_pa only when the file sets it explicitly (config.containsKey(ServerOptions.ADMIN_PA.name()) with a non-empty value, the same test InitStore.checkAdminBootstrapReachable uses), and otherwise keep the prompt. The Ranger stack sets auth.admin_pa=admin, so it would still work. (#3273 (comment))
• Important: Blocking: yes. Summary: With the Ranger authenticator enabled, every default-graph and default-role call fails with IllegalAccessException, so those REST endpoints return 500. The delegate is HugeGraphAuthProxy.AuthManagerProxy, a package-private inner class in org.apache.hugegraph.auth. getClass().getMethod(...) returns the method declared on that class, and Method.invoke from org.apache.hugegraph.ranger is refused. The affected callers reach this class through GraphManager.authManager(): GraphsAPI (setDefaultGraph, getDefaultGraph), GraphSpaceAPI and ManagerAPI (createDefaultRole, createSpaceDefaultRole, isDefaultRole, deleteDefaultRole). Evidence: RangerHugeGraphAuthenticator.setup() passes this.graph.authManager() as the delegate. With gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy, that is AuthManagerProxy, declared as class AuthManagerProxy implements AuthManager (HugeGraphAuthProxy.java line 1592). A two-package repro of the same shape on JDK 17 throws IllegalAccessException: class b.Main cannot access a member of class a.Outer$AuthManagerProxy with modifiers "public", while the direct interface call works. All of these methods are already declared on AuthManager at this head (AuthManager.java lines 259-281), so the reflection is not needed. Fix: call delegate.setDefaultGraph(...) and the others directly, mark them @Override, and remove callDelegate. (#3273 (comment))
• Important: Blocking: yes. Summary: The role built from the Ranger grants is keyed only under graph space DEFAULT. RolePerm.matchResource() looks up roles.get(requiredResource.graphSpace()) by exact key, so a user whose access comes only from Ranger is refused in every other graph space, even under a graphspace=* policy. The per-request authorizer never gets a say, because verifyResPermission consults it only after the local match has already passed. In a PD/HStore deployment with several graph spaces, Ranger cannot grant anything outside DEFAULT. Evidence: this line hard-codes {"roles":{"DEFAULT":{"*":{...}}}}. HugeAuthenticator.java line 438 is this.roles.get(requiredResource.graphSpace()), which returns false when the result is null. In HugeGraphAuthProxy.verifyResPermission the authorizer branch is guarded by if (matched && RESOURCE_AUTHORIZER != null). Fix: build the role for the graph space being accessed (or for every graph space the user can reach), and add a test where a Ranger-only user reads a graph in a graph space other than DEFAULT. (#3273 (comment))
• Important: Blocking: yes. Summary: The new module is built only with -Dwith-ranger-plugin, and no workflow passes that flag. CI never compiles the module, and RangerHugeGraphPluginTest never runs. The comment above names the trade-off, but it means the next change to AuthManager or HugeGraphAuthProxy can break RangerAuthManager without anyone noticing. The authorizer branch added to HugeGraphAuthProxy.verifyResPermission also has no test: no test registers a ResourceAuthorizer. A test that did would have caught the rate-limiter allow above. Evidence: git grep ranger -- .github/ at this head returns nothing, and every check run on this head builds only the default reactor. Fix: add a CI job (or a server-ci step) that builds and tests the module with -Dwith-ranger-plugin. Also add a HugeGraphAuthProxyTest case that registers an authorizer denying one label and checks that a burst of element reads filters out every element with that label. (#3273 (comment))
• Minor: Every authenticated REST request goes through this method, and enrichWithRanger() then makes up to five isAccessAllowed calls (ADMIN, READ, WRITE, DELETE and EXECUTE on */*/all/*). RangerHugeGraphPlugin.init() sets RangerDefaultAuditHandler, so each of these calls is audited. Ranger therefore gets up to five synthetic audit records per request, on top of the real per-resource checks. Evidence: AuthenticationFilter.filter() calls authenticate() on every non-whitelisted request, which reaches GraphManager.authenticate(), then RangerHugeGraphAuthenticator.authenticate(), then this method. The probes are in mergeRangerRole() (lines 202-228). Fix: cache the merged role per user for a short TTL, the way usersRoleCache does for the local role, or turn off auditing for these probe requests. (#3273 (comment))

[bitflicker64]

Blocking: yes. Summary: The earlier findings (rate-limiter allow, init-store default password, reflection, DEFAULT-only role, Ranger CVE, CI coverage, login probe) are fixed at this head, but RangerAuthManager drops the graph-space overloads of AuthManager, so graph-space auth APIs break and skip the space-manager check in PD mode. Two smaller issues sit in the Docker integration stack.

[bitflicker64]

Minor: ranger-db runs with POSTGRES_HOST_AUTH_METHOD: trust and publishes 5432 on every host interface, so anyone who reaches the host can rewrite Ranger policies and grant themselves HugeGraph access. Drop the ports entry (Ranger reaches the database over the compose network) or bind it to 127.0.0.1.

[vaijosh]

Addressed in recent commit