Skip to content

[doc](auth) Add guide for writing a custom authorization plugin#4009

Open
arpitjain099 wants to merge 1 commit into
apache:masterfrom
arpitjain099:docs/custom-access-controller
Open

[doc](auth) Add guide for writing a custom authorization plugin#4009
arpitjain099 wants to merge 1 commit into
apache:masterfrom
arpitjain099:docs/custom-access-controller

Conversation

@arpitjain099

Copy link
Copy Markdown

Doris has supported external authorization through the AccessControllerFactory / CatalogAccessController SPI since #40750, with Apache Ranger as the reference implementation, but there is no page documenting the SPI itself. Today anyone who wants to back Doris authorization with a different system (OPA, OpenFGA, an in-house entitlement service) has to reverse-engineer it from the Ranger code.

This adds admin-manual/auth/authorization/custom.md alongside the existing internal and Ranger authorization docs, and links it into the sidebar. It covers:

  • the two interfaces you implement, CatalogAccessController and AccessControllerFactory, with the actual method signatures and the parts worth knowing up front (the hasGlobal default overloads, checkColsPriv throwing AuthorizationException instead of returning a boolean, and masking/row-filter returning empty by default)
  • the two ways Doris discovers a factory: the classpath META-INF/services file for an in-tree plugin, and the external plugin directory for a standalone jar
  • how a controller is selected and configured, for both the internal catalog (access_controller_type + authorization_config_file_path) and external catalogs (access_controller.class + access_controller.properties.*)
  • a minimal skeleton to start from, plus a pointer to the Ranger integration as the worked example

All interface signatures and config keys were checked against the current fe-core source. This also gives external-authorizer work like the OpenFGA controller in #65685 a place to point its readers.

Notes on versions and languages: the page is added to the current (dev) docs and in English first. The SPI has existed since 3.0, so this can be backported to the 3.x and 4.x versioned docs and translated to Chinese / Japanese as follow-ups. Happy to fold those into this PR instead if you would prefer them together.

Versions

  • dev
  • 4.x
  • 3.x
  • 2.1 or older (not covered by version/language sync gate)

Languages

  • Chinese
  • English
  • Japanese candidate translation needed

Docs Checklist

  • Checked by AI
  • Test Cases Built
  • Updated required version and language counterparts, or explained why not
  • If only one language changed, confirmed whether source/translation counterparts need sync

Document the AccessControllerFactory and CatalogAccessController SPI that
lets a third-party authorization system plug into Doris. The framework has
been public since apache/doris#40750 and backs the Ranger integration, but
the docs site had no page on how to write a controller of your own.

The page covers the two interfaces and their methods, classpath and
external-jar registration, the access_controller_type / access_controller
config knobs for internal and external catalogs, a skeleton, the Ranger
reference implementation, and the one-controller-per-JVM guidance from
apache/doris#65570. Registered in the Authorization sidebar section.

Signed-off-by: Arpit Jain <arpitjain099@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant