bitflicker64 commented on code in PR #3273: URL: https://github.com/apache/hugegraph/pull/3273#discussion_r4487960967
########## docker/hgRangerIntegration/README.md: ########## @@ -0,0 +1,831 @@ +# HugeGraph Ranger Plugin — Integration Test Guide + +## Prerequisites + +- Docker and Docker Compose installed +- Maven 3.5+ and Java 17 +- HugeGraph source cloned, on branch `RangerPlugin` + +--- + +## Step 1 — No manual build needed + +`docker-compose.yml` builds the `hugegraph` image straight from source via +`Dockerfile.hugegraph`, which runs: + +```bash +mvn package -pl hugegraph-server/hugegraph-dist -am -DskipTests -Dwith-ranger-plugin +``` + +`-Dwith-ranger-plugin` bundles the shaded `hugegraph-ranger-plugin-<version>-plugin.jar` +(the one with Ranger's runtime deps, not the ~44 KB thin jar) directly into the +distribution's `lib/`. There's nothing to build or mount by hand — `docker compose up` +(Step 2 below) does it all. + +That one property gates the plugin in two places, both opt-in: + +- `hugegraph-server/pom.xml` — declares `hugegraph-ranger-plugin` as a module, so + without the flag it is not in the reactor and is never compiled. This is also what + keeps Ranger's dependency tree out of + `install-dist/scripts/dependency/known-dependencies.txt` and `release-docs/LICENSE`. +- `hugegraph-server/hugegraph-dist/pom.xml` — adds the shaded jar to the distribution. + +So a plain `mvn package` omits the plugin entirely and standalone HugeGraph builds are +unaffected. The flip side: any command that selects the module with `-pl` **must** pass +the flag too, or Maven fails with `Could not find the selected project in the reactor`. + +If you want to build the distribution standalone (outside Docker) — e.g. to inspect +`lib/` or run HugeGraph directly on the host — use the same command from the repo root: + +```bash +mvn clean package -pl hugegraph-server/hugegraph-dist -am -DskipTests -Dwith-ranger-plugin +``` + +This produces `hugegraph-server/apache-hugegraph-server-<version>/` with the plugin already +in `lib/`. + +--- + +## Step 2 — Docker Compose Stack + +The `docker-compose.yml` defines the stack with 4 services: + +**Services:** +- `ranger-db` — PostgreSQL 14 (Ranger Admin metadata store) +- `ranger-solr` — Solr 8.11 (audit backend for Ranger Admin) +- `ranger` — Apache Ranger 2.9.0 on Java 17 (policy server), built from `Dockerfile.ranger` +- `hugegraph` — HugeGraph built from this checkout (graph database with Ranger plugin) + +**Key files:** +- `Dockerfile.hugegraph` — builds HugeGraph with Ranger plugin, audit directory +- `Dockerfile.ranger` — Ranger Admin on Java 17 with the thin plugin jar baked onto its classpath +- `ranger-hugegraph-security.xml` — plugin-side Ranger config +- `rest-server.properties` — HugeGraph REST server config +- `solr-init.sh` — creates the `ranger_audits` Solr core on startup + +The Ranger Admin password is `rangerR0cks!`: the `apache/ranger:2.9.0` image uses +`RANGER_DB_PASSWORD` from `docker-compose.yml` for the `admin` login as well as the DB user. + +> **Test stack only:** `Dockerfile.ranger` sets +> `ranger.admin.allow.unauthenticated.download.access=true`, so the HugeGraph plugin can +> download policies without Ranger credentials. Ranger 2.9 rejects that by default +> (`Unauthenticated access not allowed` in the HugeGraph log). Production deployments must +> authenticate the plugin to Ranger Admin (Kerberos or JWT) instead. + +--- + +## Step 3 — Start the Stack + +```bash +# Start the full stack (builds the hugegraph and ranger images from source on first run) +docker compose -f docker/hgRangerIntegration/docker-compose.yml up -d +``` + +The Solr and Ranger Admin containers take a few minutes to initialise. Check status: + +```bash +docker compose -f docker/hgRangerIntegration/docker-compose.yml ps +# ranger-db - healthy +# ranger-solr - healthy (Solr core created, audit backend ready) +# ranger - healthy (Ranger Admin with Solr audit enabled) +# hugegraph - healthy (with Ranger plugin) +``` + +**What happens during startup:** +1. PostgreSQL starts and initializes the Ranger Admin database +2. Solr starts and `solr-init.sh` creates the `ranger_audits` core +3. Ranger Admin starts and configures Solr as the audit backend +4. HugeGraph starts and loads the Ranger plugin + +If any container fails, check logs with `docker compose logs <service>`. + +--- + +## Step 4 — Register the HugeGraph Service in Ranger Admin + +These steps are one-time setup. Run them after Ranger Admin is healthy. + +**Ranger Admin credentials: `admin` / `rangerR0cks!`** + +### 4a. Register the service definition + +```bash +curl -s -u admin:rangerR0cks! \ + -X POST http://localhost:6080/service/plugins/definitions \ + -H "Content-Type: application/json" \ + -d @hugegraph-server/hugegraph-ranger-plugin/src/main/resources/ranger-servicedef-hugegraph.json +``` + +Expected: HTTP 200 with a JSON body containing `"name": "hugegraph"`. + +If you see `service def with the name[hugegraph] already exists` the definition is already registered — continue with 4b. + +### 4b. Create a HugeGraph service instance + +```bash +curl -s -u admin:rangerR0cks! \ + -X POST http://localhost:6080/service/plugins/services \ + -H "Content-Type: application/json" \ + -d '{ + "name": "hugegraph", + "displayName": "HugeGraph", + "description": "Local HugeGraph test instance", + "type": "hugegraph", + "isEnabled": true, + "configs": { + "username": "admin", + "password": "admin", + "hugegraph.url": "http://hugegraph:8080" + } + }' +``` + +Expected: HTTP 200 with a JSON body containing `"id"`. Confirm: +```bash +curl -s -u admin:rangerR0cks! \ + http://localhost:6080/service/plugins/services/name/hugegraph | python3 -m json.tool | grep '"id"' +``` + +### 4c. Verify Ranger Admin can load the plugin class + +Nothing to deploy. `Dockerfile.ranger` bakes the thin `hugegraph-ranger-plugin` jar into +the Ranger image under +`ews/webapp/WEB-INF/classes/ranger-plugins/hugegraph/`, which is where Ranger Admin +looks for a service definition's `implClass`. That class, `RangerHugeGraphService`, +backs both the **Test Connection** button and the policy editor's **resource +autocomplete** (Graph Space -> Graph -> Resource Type -> Label). Both log in to HugeGraph +with the service's `username`/`password`; **Test Connection** lists the graphs of the +`DEFAULT` graphspace and fails if HugeGraph rejects those credentials (HTTP 401/403). + +Confirm it with the exact call the autocomplete makes. `lookupResource/hugegraph` takes +the service *instance* name from step 4b, so run that step first: + +```bash +curl -s -u admin:rangerR0cks! \ + -X POST http://localhost:6080/service/plugins/services/lookupResource/hugegraph \ + -H "Content-Type: application/json" \ + -d '{"userInput":"","resourceName":"graph","resources":{"graphspace":["DEFAULT"]}}' +``` + +Expected: `["hugegraph"]`. + +If it returns `"service" is null`, the `hugegraph` service instance does not exist yet — +run step 4b. + +If it returns `[]`: + +```bash +# is the jar in the image? +docker exec ranger ls \ + /opt/ranger/admin/ews/webapp/WEB-INF/classes/ranger-plugins/hugegraph/ + +# did the class fail to load? +docker logs ranger 2>&1 | grep -iE "hugegraph|ClassNotFound" + +# is implClass still set on the service definition? +curl -s -u admin:rangerR0cks! \ + http://localhost:6080/service/plugins/definitions/name/hugegraph \ + | grep -o '"implClass":"[^"]*"' +``` + +A stack created before the jar was baked in still runs the stock image — rebuild it: + +```bash +docker compose -f docker/hgRangerIntegration/docker-compose.yml up -d --build ranger +``` + +Resource fields are plain text inputs, so an empty autocomplete never blocks policy +creation: you can always type `DEFAULT`, `hugegraph`, `vertex` and so on by hand. + +--- + +## Step 5 — Create Test Users in HugeGraph + +```bash +# Create user "bob" with password "bobpass" +curl -u admin:admin \ +-X POST http://localhost:8080/graphspaces/DEFAULT/auth/users \ +-H "Content-Type: application/json" \ +-d '{"user_name": "bob", "user_password": "bobpass"}' + +# Create user "alice" with password "alicepass" +curl -u admin:admin \ +-X POST http://localhost:8080/graphspaces/DEFAULT/auth/users \ +-H "Content-Type: application/json" \ +-d '{"user_name": "alice", "user_password": "alicepass"}' +``` + +--- + +## Step 6 — Create Ranger Policies + +Ranger only accepts policies for users it knows about. Without this, the policy below +is rejected with `User name: bob specified in policy does not exist in ranger admin`, +and every login by `bob` or `alice` then fails with `Authentication failed` because +Ranger grants them nothing. Register both users in Ranger Admin first: + +```bash +for u in bob alice; do + curl -s -u admin:rangerR0cks! \ + -X POST http://localhost:6080/service/xusers/secure/users \ + -H "Content-Type: application/json" \ + -d "{\"name\": \"$u\", \"firstName\": \"$u\", \"password\": \"${u}Ranger1\", + \"userRoleList\": [\"ROLE_USER\"], \"status\": 1}" | grep -o '"name":"[^"]*"' +done +``` + +Expected: `"name":"bob"` and `"name":"alice"`. These Ranger-side passwords only satisfy +Ranger's password rules and are never used; HugeGraph still checks `bobpass` and +`alicepass` from Step 5. + +> **Important:** Ranger rejects two separate policies with overlapping resource patterns +> (`graphspace/*`, `graph/*`, etc. match the same space). Bob, Alice, and HugeGraph's +> `admin` user must all be in a **single combined policy** with separate `policyItems` +> entries. + +> **Why `resource-type: ["*"]`?** The Ranger plugin checks permissions using +> `ResourceType.ALL` at login time to build the user's role. The policy must cover `"*"` +> (wildcard) so that `"all"` matches. Using `["vertex"]` would not match and the user +> would be denied everything. + +> **Why include `admin`?** `HugeGraphAuthProxy` still calls into the Ranger authorizer +> for the `admin` role so that admin's actions land in Ranger's audit log — but it +> discards the verdict, so admin is never actually denied regardless of policy. Without +> a matching policy, admin's actions are audited as `Result: Denied` (harmless, but +> confusing to read). Add `admin` to this policy so Ranger's own verdict is `Allowed` +> and the audit trail reflects that admin genuinely has access, not just that it was +> let through unconditionally. + +```bash +curl -s -u admin:rangerR0cks! \ + -X POST http://localhost:6080/service/plugins/policies \ + -H "Content-Type: application/json" \ + -d '{ + "name": "hugegraph-access", + "service": "hugegraph", + "isEnabled": true, + "isAuditEnabled": true, + "resources": { + "graphspace": {"values": ["*"], "isExcludes": false, "isRecursive": false}, + "graph": {"values": ["*"], "isExcludes": false, "isRecursive": false}, + "resource-type": {"values": ["*"], "isExcludes": false, "isRecursive": false}, + "label": {"values": ["*"], "isExcludes": false, "isRecursive": false} + }, + "policyItems": [ + { + "users": ["bob"], + "groups": [], + "accesses": [{"type": "read", "isAllowed": true}], + "conditions": [], + "delegateAdmin": false + }, + { + "users": ["alice"], + "groups": [], + "accesses": [{"type": "admin", "isAllowed": true}], + "conditions": [], + "delegateAdmin": false + }, + { + "users": ["admin"], + "groups": [], + "accesses": [ + {"type": "read", "isAllowed": true}, + {"type": "write", "isAllowed": true}, + {"type": "delete", "isAllowed": true}, + {"type": "execute", "isAllowed": true}, + {"type": "admin", "isAllowed": true} + ], + "conditions": [], + "delegateAdmin": false + } + ] + }' +``` + +Expected: HTTP 200 with `"id"` in the response. + +Wait ~30 seconds for HugeGraph to pull the new policies from Ranger Admin. + +Confirm admin's actions are now audited as allowed, not just let through: + +```bash +curl -s -o /dev/null -w "%{http_code}\n" -u admin:admin \ + http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/propertykeys +# Expected: 200 + +curl -s -u admin:rangerR0cks! \ + "http://localhost:6080/service/assets/accessAudit?requestUser=admin&sortBy=eventTime&descending=true&pageSize=5" \ + | python3 -m json.tool | grep -E '"eventTime"|"accessResult"' +# Expected: accessResult 1 (Allowed) for the most recent entries +``` + +--- + +## Step 7 — Run the Smoke Tests + +All tests use the REST API (`/graphspaces/DEFAULT/graphs/hugegraph/...`) rather than the +Gremlin endpoint, which has serialization issues in this deployment. + +### Setup — create schema and real graph data + +The read tests below (Test 1, Test 3) only exercise the per-request Ranger check +(`checkResourceAuthorizer`) if there is actual data to iterate — an empty result set never +reaches the authorizer for a real element. Create schema and a couple of elements as +**alice** (admin) before running the read tests, using fixed (`CUSTOMIZE_STRING`) vertex +IDs so later tests can address them directly. + +```bash +# Vertex labels — CUSTOMIZE_STRING lets us assign ids explicitly below +curl -s -o /dev/null -w "%{http_code}\n" -u alice:alicepass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels \ + -H "Content-Type: application/json" \ + -d '{"name":"person","id_strategy":"CUSTOMIZE_STRING"}' +# Expected: 201 + +curl -s -o /dev/null -w "%{http_code}\n" -u alice:alicepass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels \ + -H "Content-Type: application/json" \ + -d '{"name":"software","id_strategy":"CUSTOMIZE_STRING"}' +# Expected: 201 + +# Edge label "likes" from person -> software +curl -s -o /dev/null -w "%{http_code}\n" -u alice:alicepass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/edgelabels \ + -H "Content-Type: application/json" \ + -d '{"name":"likes","source_label":"person","target_label":"software"}' +# Expected: 201 + +# Vertices with fixed ids "p1" (person) and "s1" (software) +curl -s -o /dev/null -w "%{http_code}\n" -u alice:alicepass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices \ + -H "Content-Type: application/json" \ + -d '{"label":"person","id":"p1","properties":{}}' +# Expected: 201 + +curl -s -o /dev/null -w "%{http_code}\n" -u alice:alicepass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices \ + -H "Content-Type: application/json" \ + -d '{"label":"software","id":"s1","properties":{}}' +# Expected: 201 + +# Edge "p1 -likes-> s1" +curl -s -o /dev/null -w "%{http_code}\n" -u alice:alicepass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges \ + -H "Content-Type: application/json" \ + -d '{"label":"likes","outV":"p1","outVLabel":"person","inV":"s1","inVLabel":"software","properties":{}}' +# Expected: 201 +``` + +### Test 1 — Bob can read vertices ✅ + +```bash +curl -s --compressed -u bob:bobpass \ + http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices +``` + +Expected: a `vertices` array containing `p1` (label `person`) and `s1` (label `software`). +Because these are now real elements, the underlying `FilterIterator` in +`HugeGraphAuthProxy.verifyElemPermission` calls `checkResourceAuthorizer()` per element, +consulting Ranger with the real `graphspace/graph/resource-type/label` — see the audit +verification at the end of this step. + +### Test 2 — Bob cannot create a schema ❌ + +```bash +curl -s -o /dev/null -w "%{http_code}\n" -u bob:bobpass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels \ + -H "Content-Type: application/json" \ + -d '{"name":"nope","id_strategy":"DEFAULT"}' +``` + +Expected: `403` + +This does **not** exercise the Ranger per-request check — it demonstrates the local +`RolePerm.match()` gate. Bob's HugeGraph role only grants `READ`, so +`HugeGraphAuthProxy.verifyResPermission()` (`HugeGraphAuthProxy.java:1197`) rejects the +`WRITE` attempt before `matched` is ever `true`, and the code at +`HugeGraphAuthProxy.java:1213-1216` (`if (matched && RESOURCE_AUTHORIZER != null && ...)`) +short-circuits — Ranger is never consulted at all for this call. Confirm this by checking +the audit log after this request: there should be **no** new entry for it, since +`RangerHugeGraphPlugin.isAllowed()` was never invoked. + +### Test 3 — Bob can also read edges ✅ + +Bob's policy covers `resource-type: ["*"]` which includes edges, so this succeeds either +way. Because the `likes` edge created in Setup is a real element, this request is also +checked against Ranger with the *real* resource-type/label being accessed (`edge`/`likes` +here), not just the coarse `ResourceType.ALL` grant fetched once at login — see Test 3b +below for a case that actually depends on this distinction, since this test would pass +either way. + +```bash +curl -s -o /dev/null -w "%{http_code}\n" -u bob:bobpass \ + http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges +``` + +Expected: `200`, with the `likes` edge from `p1` to `s1` in the `edges` array. + +### Test 3b — Fine-grained per-label denial ❌ (regression test for real enforcement) + +Keep bob's wildcard `label: ["*"]` read grant in place — it is what lets him pass the +coarse `ResourceType.ALL`/`*` role check done once at login +(`RangerAuthManager.mergeRangerRole`). Ranger policies are additive/allow-list: a policy +that grants read on `label: ["person"]` only adds a grant, it never implies "deny read on +every other label." So **narrowing** bob's grant to `person` only (replacing the wildcard) +does not produce a person/software split — it makes Ranger deny read for *every* label, +including `person`, because bob then has no grant at all that matches the coarse +`ResourceType.ALL` check, and `HugeGraphAuthProxy.verifyResPermission()` rejects him at the +local `RolePerm.match()` gate before the per-element Ranger check is ever consulted. + +To get an actual split, add a second, higher-priority policy with an explicit +**`denyPolicyItems`** entry scoped to `label: ["software"]`, while leaving bob's wildcard +allow grant untouched. Ranger evaluates deny policies with priority over allow policies for +a matching resource, so: the coarse per-login check still grants bob `READ` (nothing denies +`resource-type: ALL`/`*`), and the per-element check on the real label then denies +`software` specifically while `person` still matches only the allow. + +```bash +# 1. Get the combined policy id (created in Step 6) +POLICY_ID=$(curl -s -u admin:rangerR0cks! \ + "http://localhost:6080/service/plugins/policies?serviceName=hugegraph&policyName=hugegraph-access" \ + | python3 -m json.tool | grep '"id"' | head -1 | grep -o '[0-9]*') +echo "Policy id: $POLICY_ID" + +# 2. Add a deny policy for bob's read on label "software" only. Bob's wildcard read +# grant in hugegraph-access (id=$POLICY_ID) is left untouched — this is additive. +curl -s -u admin:rangerR0cks! \ + -X POST http://localhost:6080/service/plugins/policies \ + -H "Content-Type: application/json" \ + -d '{ + "name": "hugegraph-bob-deny-software", + "service": "hugegraph", + "isEnabled": true, + "isAuditEnabled": true, + "policyPriority": 1, + "resources": { + "graphspace": {"values": ["*"], "isExcludes": false, "isRecursive": false}, + "graph": {"values": ["*"], "isExcludes": false, "isRecursive": false}, + "resource-type": {"values": ["*"], "isExcludes": false, "isRecursive": false}, + "label": {"values": ["software"], "isExcludes": false, "isRecursive": false} + }, + "policyItems": [ + { + "users": ["admin"], + "groups": [], + "accesses": [ + {"type": "read", "isAllowed": true}, + {"type": "write", "isAllowed": true}, + {"type": "delete", "isAllowed": true}, + {"type": "execute", "isAllowed": true}, + {"type": "admin", "isAllowed": true} + ], + "conditions": [], + "delegateAdmin": false + } + ], + "denyPolicyItems": [ + { + "users": ["bob"], + "groups": [], + "accesses": [{"type": "read", "isAllowed": true}], + "conditions": [], + "delegateAdmin": false + } + ] + }' +# Expected: 200 with "id" in the response + +# 3. Wait for policy refresh (default poll interval: 30s) +sleep 35 + +# 4. Bob reading vertex "p1" (label "person") — still allowed. Note the vertex id must be +# URL-encoded (%22p1%22) — a literal quote in the path 500s with a URISyntaxException +# rather than exercising the permission check at all. +curl -s -o /dev/null -w "%{http_code}\n" -u bob:bobpass \ + http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices/%22p1%22 +# Expected: 200 + +# 5. Bob reading vertex "s1" (label "software") — now denied +curl -s -o /dev/null -w "%{http_code}\n" -u bob:bobpass \ + http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices/%22s1%22 +# Expected: 403 +``` + +Confirm the denial reached the real per-request check (not a local-role rejection, since +bob's base role still grants `READ` generally) by checking the audit log for a `result: 0` +entry with `resource` containing `.../vertex/software` and `reqUser: bob`: + +```bash +docker exec hugegraph tail -n 20 /var/log/ranger/audit/hugegraph_ranger_audit.log +``` + +**Cleanup:** delete the `hugegraph-bob-deny-software` policy before continuing to Test 4, +so later steps that expect bob to read any label are not affected by this deny rule. + +```bash +DENY_POLICY_ID=$(curl -s -u admin:rangerR0cks! \ + "http://localhost:6080/service/plugins/policies?serviceName=hugegraph&policyName=hugegraph-bob-deny-software" \ + | python3 -m json.tool | grep '"id"' | head -1 | grep -o '[0-9]*') +curl -s -u admin:rangerR0cks! -X DELETE \ + "http://localhost:6080/service/plugins/policies/$DENY_POLICY_ID" -o /dev/null -w "%{http_code}\n" +# Expected: 204 +sleep 35 +``` + +### Test 4 — Alice can do everything ✅ + +```bash +# Create a new vertex label as alice — "person2", not "person" (that name was +# already taken by the Setup step above; reusing it 400s with ExistedException, +# a schema-validation error unrelated to Ranger) +curl -s -o /dev/null -w "%{http_code}\n" -u alice:alicepass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels \ + -H "Content-Type: application/json" \ + -d '{"name":"person2","id_strategy":"DEFAULT"}' +``` + +Expected: `201` + +```bash +# Alice can also read vertices +curl -s --compressed -u alice:alicepass \ + http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices +``` + +Expected: `{"vertices":[]}` + +### Test 5 — Unknown user is rejected ❌ + +Use a protected endpoint — `/versions` is public and always returns 200. + +```bash +curl -s -o /dev/null -w "%{http_code}\n" -u nobody:wrongpass \ + http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices +``` + +Expected: `401` + +### Verify audit entries reflect the real request (do this after Tests 1-4) + +After running the smoke tests above, check the audit log and confirm each entry's +`resource`/`access`/`action` fields (see [Audit logs](#audit-logs) below) match the operation +that was actually performed, not a generic placeholder: + +```bash +docker exec hugegraph tail -n 20 /var/log/ranger/audit/hugegraph_ranger_audit.log +``` + +For example, after Test 1 (bob reading vertices), look for an entry with +`"reqUser":"bob"`, `"access":"read"`, `"action":"read"`, and `"resource"` containing +`hugegraph/vertex` (not the stale `*/*/all/*` / null-access-type values). Test 2's denial +(bob's schema create) does **not** produce a corresponding audit entry at all — as noted +in Test 2, that request never reaches `RangerHugeGraphPlugin.isAllowed()`. For a denial +that *does* reach Ranger, see Test 3b, which confirms a `"result":0` entry for the +per-label deny. + +--- + +## Step 8 — Verify Policy Caching + +Test that HugeGraph continues to serve Ranger policies even if Ranger Admin goes down (uses local cache). + +```bash +# Stop Ranger Admin +docker compose -f docker/ranger-integration/docker-compose.yml stop ranger + +# Bob can still read vertices (served from local cache) +curl -s --compressed -u bob:bobpass \ + http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices +``` + +Because the per-request check now consults `RangerBasePlugin.isAccessAllowed()` directly +against the locally cached policy (not just the once-at-login role fetch), this also confirms +per-request enforcement itself keeps working while Ranger Admin is down — check the audit log +(`docker exec hugegraph tail -n 5 /var/log/ranger/audit/hugegraph_ranger_audit.log`) for a fresh entry +with real `resource`/`access` values even with Ranger Admin stopped. + +```bash +# Bring Ranger Admin back +docker compose -f docker/ranger-integration/docker-compose.yml start ranger +``` + +--- + +## Step 9 — Test Dynamic Policy Update + +Verify that a policy change in Ranger Admin takes effect without restarting HugeGraph. + +Because Ranger rejects overlapping resource patterns, all users share one policy +(`hugegraph-access`, id=22 from Step 7). To add write access for bob, update that +policy via `PUT` rather than creating a new one. + +```bash +# 1. Confirm bob currently cannot write schema +curl -s -o /dev/null -w "%{http_code}\n" -u bob:bobpass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels \ + -H "Content-Type: application/json" \ + -d '{"name":"testlabel","id_strategy":"DEFAULT"}' +# Expected: 403 + +# 2. Get the policy id +POLICY_ID=$(curl -s -u admin:rangerR0cks! \ + "http://localhost:6080/service/plugins/policies?serviceName=hugegraph&policyName=hugegraph-access" \ + | python3 -m json.tool | grep '"id"' | head -1 | grep -o '[0-9]*') +echo "Policy id: $POLICY_ID" + +# 3. Update the policy — add write access for bob alongside existing read +curl -s -u admin:rangerR0cks! \ + -X PUT "http://localhost:6080/service/plugins/policies/$POLICY_ID" \ + -H "Content-Type: application/json" \ + -d "{ + \"id\": $POLICY_ID, + \"name\": \"hugegraph-access\", + \"service\": \"hugegraph\", + \"isEnabled\": true, + \"isAuditEnabled\": true, + \"resources\": { + \"graphspace\": {\"values\": [\"*\"], \"isExcludes\": false, \"isRecursive\": false}, + \"graph\": {\"values\": [\"*\"], \"isExcludes\": false, \"isRecursive\": false}, + \"resource-type\": {\"values\": [\"*\"], \"isExcludes\": false, \"isRecursive\": false}, + \"label\": {\"values\": [\"*\"], \"isExcludes\": false, \"isRecursive\": false} + }, + \"policyItems\": [ + { + \"users\": [\"bob\"], \"groups\": [], + \"accesses\": [{\"type\": \"read\", \"isAllowed\": true}, {\"type\": \"write\", \"isAllowed\": true}], + \"conditions\": [], \"delegateAdmin\": false + }, + { + \"users\": [\"alice\"], \"groups\": [], + \"accesses\": [{\"type\": \"admin\", \"isAllowed\": true}], + \"conditions\": [], \"delegateAdmin\": false + }, + { + \"users\": [\"admin\"], \"groups\": [], + \"accesses\": [ + {\"type\": \"read\", \"isAllowed\": true}, + {\"type\": \"write\", \"isAllowed\": true}, + {\"type\": \"delete\", \"isAllowed\": true}, + {\"type\": \"execute\", \"isAllowed\": true}, + {\"type\": \"admin\", \"isAllowed\": true} + ], + \"conditions\": [], \"delegateAdmin\": false + } + ] + }" + +# 4. Wait for policy refresh (default: 30 seconds) +sleep 35 + +# 5. Retry — bob can now create schema +curl -s -o /dev/null -w "%{http_code}\n" -u bob:bobpass \ + -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels \ + -H "Content-Type: application/json" \ + -d '{"name":"testlabel","id_strategy":"DEFAULT"}' +# Expected: 201 +``` + +--- + +## Observability + +### Plugin startup log + +```bash +docker logs hugegraph | grep -i ranger +# Should show: +# RangerHugeGraphPlugin started for service 'hugegraph' +# RangerHugeGraphAuthenticator initialised, Ranger service=hugegraph +``` + +### Policy reload log + +```bash +docker logs hugegraph | grep -i "policy" +``` + +### Check local policy cache + +```bash +docker exec hugegraph ls /tmp/ranger/cache/hugegraph/ +# hugegraph_hugegraph.json ← cached policy file +``` + +### Audit logs + +**Ranger Admin audit:** Logged to Solr. View via Ranger Admin UI (Audit tab) or query Solr directly: + +```bash +# Query Solr for recent audit events +curl -s 'http://localhost:8983/solr/ranger_audits/select?q=*:*&rows=10' | jq .response.docs[] + +# Check Solr collection status +curl -s 'http://localhost:8983/solr/admin/cores?action=STATUS&core=ranger_audits' | jq .status.ranger_audits +``` + +**HugeGraph plugin audit:** Logged to file. View from the HugeGraph container: + +```bash +docker exec hugegraph tail -f /var/log/ranger/audit/hugegraph_ranger_audit.log +``` + +Each request is now checked against Ranger with the real graphspace/graph/resource-type/label +being accessed (not a hardcoded wildcard), and the audited access type is populated correctly. +For example, bob reading a vertex with label `person` in graph `hugegraph`/graphspace `DEFAULT` +produces an audit entry like: + +```json +{"repo":"hugegraph","sess_exprtime":1725106832,"access":"read","reqUser":"bob","cliIP":"172.21.0.1","action":"read","resource":"DEFAULT/hugegraph/vertex/person","result":1,"agent":"curl","policy":22,"role":"ROLE_SEARCHER"} +``` + +Before the per-request enforcement fix, every entry showed `"access":""`/`"action":null` and a +generic `"resource":"*/*/all/*"` regardless of what was actually accessed. The Ranger Admin +UI's Audit tab shows the same underlying fields under its "Access Type" and "Resource Path" +columns, so use those to confirm real values are now flowing through, e.g. +`Resource Path=DEFAULT/hugegraph/vertex/person`, `Access Type=read`. + +**Note on "Resource Type":** unlike Resource Path and Access Type, the audited `resType` / +"Resource Type" column will **always** read `label`, never `vertex`/`edge`/`schema`. This is +not a bug in the plugin — `RangerDefaultAuditHandler` populates `resType` from +`RangerAccessResource.getLeafName()`, which Ranger derives from the service definition's +*deepest configured resource level name* (`ranger-servicedef-hugegraph.json` defines +`graphspace → graph → resource-type → label`, so `label` is always the leaf). HugeGraph's own +notion of resource type (`VERTEX`/`EDGE`/`SCHEMA`/...) is carried instead in the third segment +of the `resource` / "Resource Path" field (`.../vertex/person` above) — that is the field to +check when validating that the real resource type reached Ranger, not "Resource Type". + +The `result` field indicates: `1` = allowed, `0` = denied (`RangerDefaultAuditHandler` maps +`RangerAccessResult.getIsAllowed()` to `1`/`0` respectively). + +**v1 limitation:** bulk traversal / iterator-based reads (e.g. paging through many vertices or Review Comment: Minor: this paragraph still says elements beyond the audit rate fall back to the local `RolePermission` match, but `checkResourceAuthorizer()` now asks Ranger for every non-admin check and rate-limits only the audit record. Update it to say Ranger decides every element and only auditing is sampled. ########## hugegraph-server/hugegraph-ranger-plugin/src/main/java/org/apache/hugegraph/ranger/RangerAuthManager.java: ########## @@ -0,0 +1,767 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.hugegraph.ranger; + +import java.util.Date; +import java.util.List; +import java.util.Map; +import java.util.Set; + +import javax.security.sasl.AuthenticationException; + +import org.apache.hugegraph.auth.AuthManager; +import org.apache.hugegraph.auth.HugeAccess; +import org.apache.hugegraph.auth.HugeAuthenticator; +import org.apache.hugegraph.auth.HugeBelong; +import org.apache.hugegraph.auth.HugeDefaultRole; +import org.apache.hugegraph.auth.HugeGroup; +import org.apache.hugegraph.auth.HugePermission; +import org.apache.hugegraph.auth.HugeProject; +import org.apache.hugegraph.auth.HugeTarget; +import org.apache.hugegraph.auth.HugeUser; +import org.apache.hugegraph.auth.ResourceType; +import org.apache.hugegraph.auth.RolePermission; +import org.apache.hugegraph.auth.SchemaDefine.AuthElement; +import org.apache.hugegraph.auth.UserWithRole; +import org.apache.hugegraph.id.Id; +import org.apache.hugegraph.util.JsonUtil; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * AuthManager implementation that: + * <ul> + * <li>Delegates all identity-management operations (users, groups, tokens) to + * the underlying {@link AuthManager} (StandardAuthManager / + * StandardAuthManagerV2).</li> + * <li>Intercepts {@link #validateUser} / {@link #rolePermission} to merge + * Ranger policy decisions into the returned {@link RolePermission}.</li> + * </ul> + * + * <h3>Ranger → RolePermission mapping</h3> + * <pre> + * Ranger access type │ HugePermission + * ────────────────────┼──────────────── + * read │ READ + * write │ WRITE + * delete │ DELETE + * execute │ EXECUTE + * admin │ ADMIN + * </pre> + */ +public class RangerAuthManager implements AuthManager { + + private static final Logger LOG = + LoggerFactory.getLogger(RangerAuthManager.class); + + private final AuthManager delegate; + private final RangerHugeGraphPlugin rangerPlugin; + + public RangerAuthManager(AuthManager delegate, + String serviceName, + String rangerConfigFile) { + this.delegate = delegate; + this.rangerPlugin = new RangerHugeGraphPlugin(serviceName, rangerConfigFile); + this.rangerPlugin.init(); + } + + /** + * The underlying Ranger plugin instance, used by + * {@link RangerHugeGraphAuthenticator#setup} to register real per-request + * enforcement via {@code HugeGraphAuthProxy.setResourceAuthorizer}. + */ + public RangerHugeGraphPlugin rangerPlugin() { + return this.rangerPlugin; + } + + // ------------------------------------------------------------------ + // Authentication helpers + // ------------------------------------------------------------------ + + /** + * Authenticate by username+password or token, then enrich the returned + * role with Ranger policy grants. Called from + * {@link RangerHugeGraphAuthenticator#authenticate}. + */ + public UserWithRole authenticate(String username, String password, + String token) { + UserWithRole base = (token != null && !token.isEmpty()) ? + delegate.validateUser(token) : + delegate.validateUser(username, password); + return enrichWithRanger(base); + } + + @Override + public UserWithRole validateUser(String username, String password) { + return enrichWithRanger(delegate.validateUser(username, password)); + } + + @Override + public UserWithRole validateUser(String token) { + return enrichWithRanger(delegate.validateUser(token)); + } + + @Override + public RolePermission rolePermission(AuthElement element) { + RolePermission base = delegate.rolePermission(element); + if (base == null) { + base = RolePermission.none(); + } + if (RolePermission.isAdmin(base)) { + return base; + } + String name = (element instanceof HugeUser) ? + ((HugeUser) element).name() : + element.id().asString(); + // admin is a trusted bootstrap identity (same bypass as + // HugeGraphAuthProxy.verifyResPermission() and + // RangerHugeGraphAuthenticator.authenticate()) — no Ranger policy is + // expected to exist for it, so never probe Ranger on its behalf. + if (HugeAuthenticator.USER_ADMIN.equals(name)) { + return RolePermission.admin(); + } + return mergeRangerRole(base, name); + } + + // ------------------------------------------------------------------ + // Private: Ranger enrichment + // ------------------------------------------------------------------ + + private UserWithRole enrichWithRanger(UserWithRole base) { + if (base == null || base.username() == null) { + return base; + } + // userId() is null when authentication failed (wrong password or unknown user). + // Do not grant Ranger permissions to unauthenticated identities. + if (base.userId() == null) { + return base; + } + RolePermission role = base.role(); + if (role != null && RolePermission.isAdmin(role)) { + return base; + } + // admin is a trusted bootstrap identity — never probe Ranger for it, + // otherwise every login logs a spurious Denied admin/*/*/all/* audit + // entry even though RangerHugeGraphAuthenticator.authenticate() + // overrides the role with ROLE_ADMIN right after this call returns. + if (HugeAuthenticator.USER_ADMIN.equals(base.username())) { + return new UserWithRole(base.userId(), base.username(), + RolePermission.admin()); + } + RolePermission enriched = mergeRangerRole( + role != null ? role : RolePermission.none(), + base.username()); + // No grants from either HugeGraph's own role or Ranger policy: reject the + // login outright rather than admitting a role with no permissions. + // + // This MUST be the HugeAuthenticator.ROLE_NONE instance, not a fresh + // RolePermission.none(). HugeAuthenticator.verifyRole() tests identity: + // return role != ROLE_NONE && role != null; + // so a newly built none() is not that reference, passes verifyRole() and + // logs the user in with an empty role. + if (isEffectivelyNone(enriched)) { + enriched = HugeAuthenticator.ROLE_NONE; + } + return new UserWithRole(base.userId(), base.username(), enriched); + } + + /** + * Query Ranger for {@code username} and merge any grants into {@code base}. + * + * <p>We check one broad wildcard request (graphspace=*, graph=*, type=ALL) + * for each permission level. Fine-grained resource checks are applied + * per-request inside {@link org.apache.hugegraph.auth.HugeGraphAuthProxy} + * via the normal {@link RolePermission} matching logic, so what we build + * here must satisfy that matching algorithm. + * + * <p>We can't call the protected {@code RolePermission.add()} from outside + * the package, so we build a JSON role string and deserialise it instead — + * this goes through the same public factory path used everywhere else. + */ + private RolePermission mergeRangerRole(RolePermission base, + String username) { + if (base == null) { + base = RolePermission.none(); + } + // Admin check first (cheapest) + if (rangerPlugin.isAllowed(username, "*", "*", + ResourceType.ALL, "*", + HugePermission.ADMIN)) { + return RolePermission.admin(); + } + + // Build a minimal JSON roles document from the Ranger grants, then + // deserialise into a RolePermission and merge with base via its JSON + // round-trip (the only public merge path available outside the pkg). + // Use "DEFAULT" as graphspace key — RolePerm.matchResource() does an + // exact key lookup for requiredResource.graphSpace(), which is "DEFAULT". + StringBuilder sb = new StringBuilder("{\"roles\":{\"DEFAULT\":{\"*\":{"); + boolean first = true; + HugePermission[] probedPerms = {HugePermission.READ, HugePermission.WRITE, + HugePermission.DELETE, HugePermission.EXECUTE}; + for (HugePermission perm : probedPerms) { + if (rangerPlugin.isAllowed(username, "*", "*", Review Comment: Important: this probe sends `*` for graph space, graph and label, and Ranger matches a `*` request value only against a policy that also lists `*` (`RangerDefaultResourceMatcher.getMatchType`), so an allow policy scoped to `graphspace=DEFAULT, graph=hugegraph` grants nothing here and a user whose grants live only in Ranger gets `ROLE_NONE` at login. Build the login role so that a graph- or label-scoped allow policy counts, for example by probing with `ResourceMatchingScope.SELF_OR_DESCENDANTS`, and add a test with such a policy. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
