javadoc for authorizer (#17636) (#17642)

server/src/main/java/org/apache/druid/server/security/Access.java

@@ -28,7 +28,8 @@
 
 /**
  * Represents the outcome of verifying permissions to perform an {@link Action} on a {@link Resource}, along with any
- * policy restrictions.
+ * applicable policy restrictions. The restriction should only exist for {@link Action#READ} and
+ * {@link ResourceType#DATASOURCE}, i.e, reading a table.
  */
 public class Access
 {
@@ -40,9 +41,10 @@ public class Access
 
   private final boolean allowed;
   private final String message;
-  // A policy restriction on top of table-level read access. It should be empty if there are no policy restrictions
-  // or if access is requested for an action other than reading the table.
-  private final Optional<Policy> policy; // should this be a list?
+  /**
+   * A policy restriction on top of table-level read access.
+   */
+  private final Optional<Policy> policy;
 
   /**
    * @deprecated use {@link #allow()} or {@link #deny(String)} instead
@@ -101,6 +103,12 @@ public boolean isAllowed()
     return allowed;
   }
 
+  /**
+   * Returns an optional {@link Policy} restriction if permission is granted. Only applies to read table access.
+   * <p>
+   * An empty value indicates either no policy restrictions exist, or access is being requested for an action other than
+   * reading a table.
+   */
   public Optional<Policy> getPolicy()
   {
     return policy;

server/src/main/java/org/apache/druid/server/security/Authorizer.java

@@ -22,13 +22,9 @@
 import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
 
-@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
-@JsonSubTypes(value = {
-    @JsonSubTypes.Type(name = AuthConfig.ALLOW_ALL_NAME, value = AllowAllAuthorizer.class)
-})
 /**
  * An Authorizer is responsible for performing authorization checks for resource accesses.
- *
+ * <p>
  * A single instance of each Authorizer implementation will be created per node.
  * Security-sensitive endpoints will need to extract the identity string contained in the request's Druid-Auth-Token
  * attribute, previously set by an Authenticator. Each endpoint will pass this identity String to the
@@ -37,16 +33,22 @@
  * After a request is authorized, a new attribute, "Druid-Authorization-Checked", should be set in the
  * request header with the result of the authorization decision.
  */
+@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
+@JsonSubTypes(value = {
+    @JsonSubTypes.Type(name = AuthConfig.ALLOW_ALL_NAME, value = AllowAllAuthorizer.class)
+})
 public interface Authorizer
 {
   /**
    * Check if the entity represented by {@code identity} is authorized to perform {@code action} on {@code resource}.
+   * <p>
+   * If the action involves reading a table, the outcome could include {@link org.apache.druid.query.policy.Policy} restrictions.
+   * However, if the action does not involve reading a table, there must be no {@link org.apache.druid.query.policy.Policy} restrictions.
    *
-   * @param authenticationResult  The authentication result of the request
-   * @param resource  The resource to be accessed
-   * @param action    The action to perform on the resource
-   *
-   * @return An Access object representing the result of the authorization check. Must not be null.
+   * @param authenticationResult The authentication result of the request
+   * @param resource             The resource to be accessed
+   * @param action               The action to perform on the resource
+   * @return An {@link Access} object representing the result of the authorization check. Must not be null.
    */
   Access authorize(AuthenticationResult authenticationResult, Resource resource, Action action);
 }