bharos opened a new pull request, #12365: URL: https://github.com/apache/gravitino/pull/12365
### What changes were proposed in this pull request? Documents the `X-Gravitino-Active-Roles` header, which shipped across #11966, #11967, and #12095 with no user-facing documentation. Adds an **Active Roles** section to `docs/security/access-control.md` covering: - the grammar — a role name, a comma-separated list, `ALL`, `NONE`, and an absent or empty value meaning `ALL`; - the matching rules — names are exact, `ALL` and `NONE` are recognized only in upper case, whitespace is trimmed and duplicates collapse; - what narrowing changes — it only ever subtracts, `DENY` stays global, ownership is untouched, and the narrowed set reaches direct checks, list filtering, and credential vending alike; - the two error classes, `400` for a malformed value and `403` for a role the caller does not hold, and why an unheld role is rejected rather than ignored; - how Spark, Trino 481+, and the Java client send the header, and that the two engine settings are catalog-level and static; - the scope limit to Gravitino's native authorization path, with a pointer to Authorization Pushdown. Also adds a short **Read or Write Scope** note to `docs/security/credential-vending.md`, since a narrowed caller that no longer holds `MODIFY_TABLE` is vended a read-only credential. The wording follows the implementation rather than the design document in one place: an unrecognized keyword is parsed as an ordinary role name and therefore returns `403`, not `400`. ### Why are the changes needed? The feature is complete and enforced on the native and Iceberg REST paths, but `X-Gravitino-Active-Roles` did not appear anywhere under `docs/`, so it was undiscoverable to users. Part of #11968, which also covers the remaining Iceberg REST and credential vending integration tests. ### Does this PR introduce _any_ user-facing change? Yes, documentation only. No behavior changes. ### How was this patch tested? Documentation only, no tests. Verified the Markdown renders correctly and that the relative links and the `#active-roles` anchor resolve. Every documented rule was checked against the implementation in `ActiveRolesParser`, `AuthenticationFilter`, `GravitinoInterceptionService`, and `IcebergTableOperationExecutor`. -- 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]
