Interface Authorizer

All Superinterfaces:
AutoCloseable, Closeable, Configurable

@Evolving public interface Authorizer extends Configurable, Closeable
Pluggable authorizer interface for Kafka brokers. Startup sequence in brokers:
  1. Broker creates authorizer instance if configured in `authorizer.class.name`.
  2. Broker configures and starts authorizer instance. Authorizer implementation starts loading its metadata.
  3. Broker starts SocketServer to accept connections and process requests.
  4. For each listener, SocketServer waits for authorization metadata to be available in the authorizer before accepting connections. The future returned by start(AuthorizerServerInfo) for each listener must return only when authorizer is ready to authorize requests on the listener.
  5. Broker accepts connections. For each connection, broker performs authentication and then accepts Kafka requests. For each request, broker invokes authorize(AuthorizableRequestContext, List) to authorize actions performed by the request.
Authorizer implementation class may optionally implement @Reconfigurable to enable dynamic reconfiguration without restarting the broker.

Threading model:

  • All authorizer operations including authorization and ACL updates must be thread-safe.
  • ACL update methods are asynchronous. Implementations with low update latency may return a completed future using CompletableFuture.completedFuture(Object). This ensures that the request will be handled synchronously by the caller without using a purgatory to wait for the result. If ACL updates require remote communication which may block, return a future that is completed asynchronously when the remote operation completes. This enables the caller to process other requests on the request threads without blocking.
  • Any threads or thread pools used for processing remote operations asynchronously can be started during start(AuthorizerServerInfo). These threads must be shutdown during Closeable.close().

  • Method Details

    • start

      Map<Endpoint,? extends CompletionStage<Void>> start(AuthorizerServerInfo serverInfo)
      Starts loading authorization metadata and returns futures that can be used to wait until metadata for authorizing requests on each listener is available. Each listener will be started only after its metadata is available and authorizer is ready to start authorizing requests on that listener.
      Parameters:
      serverInfo - Metadata for the broker including broker id and listener endpoints
      Returns:
      CompletionStage for each endpoint that completes when authorizer is ready to start authorizing requests on that listener.
    • authorize

      List<AuthorizationResult> authorize(AuthorizableRequestContext requestContext, List<Action> actions)
      Authorizes the specified action. Additional metadata for the action is specified in `requestContext`.

      This is a synchronous API designed for use with locally cached ACLs. Since this method is invoked on the request thread while processing each request, implementations of this method should avoid time-consuming remote communication that may block request threads.

      Parameters:
      requestContext - Request context including request type, security protocol and listener name
      actions - Actions being authorized including resource and operation for each action
      Returns:
      List of authorization results for each action in the same order as the provided actions
    • createAcls

      List<? extends CompletionStage<AclCreateResult>> createAcls(AuthorizableRequestContext requestContext, List<AclBinding> aclBindings)
      Creates new ACL bindings.

      This is an asynchronous API that enables the caller to avoid blocking during the update. Implementations of this API can return completed futures using CompletableFuture.completedFuture(Object) to process the update synchronously on the request thread.

      Parameters:
      requestContext - Request context if the ACL is being created by a broker to handle a client request to create ACLs. This may be null if ACLs are created directly in ZooKeeper using AclCommand.
      aclBindings - ACL bindings to create
      Returns:
      Create result for each ACL binding in the same order as in the input list. Each result is returned as a CompletionStage that completes when the result is available.
    • deleteAcls

      List<? extends CompletionStage<AclDeleteResult>> deleteAcls(AuthorizableRequestContext requestContext, List<AclBindingFilter> aclBindingFilters)
      Deletes all ACL bindings that match the provided filters.

      This is an asynchronous API that enables the caller to avoid blocking during the update. Implementations of this API can return completed futures using CompletableFuture.completedFuture(Object) to process the update synchronously on the request thread.

      Refer to the authorizer implementation docs for details on concurrent update guarantees.

      Parameters:
      requestContext - Request context if the ACL is being deleted by a broker to handle a client request to delete ACLs. This may be null if ACLs are deleted directly in ZooKeeper using AclCommand.
      aclBindingFilters - Filters to match ACL bindings that are to be deleted
      Returns:
      Delete result for each filter in the same order as in the input list. Each result indicates which ACL bindings were actually deleted as well as any bindings that matched but could not be deleted. Each result is returned as a CompletionStage that completes when the result is available.
    • acls

      Returns ACL bindings which match the provided filter.

      This is a synchronous API designed for use with locally cached ACLs. This method is invoked on the request thread while processing DescribeAcls requests and should avoid time-consuming remote communication that may block request threads.

      Returns:
      Iterator for ACL bindings, which may be populated lazily.
    • aclCount

      default int aclCount()
      Get the current number of ACLs, for the purpose of metrics. Authorizers that don't implement this function will simply return -1.
    • authorizeByResourceType

      default AuthorizationResult authorizeByResourceType(AuthorizableRequestContext requestContext, AclOperation op, ResourceType resourceType)
      Check if the caller is authorized to perform theĀ given ACL operation on at least one resource of the given type. Custom authorizer implementations should consider overriding this default implementation because: 1. The default implementation iterates all AclBindings multiple times, without any caching by principal, host, operation, permission types, and resource types. More efficient implementations may be added in custom authorizers that directly access cached entries. 2. The default implementation cannot integrate with any audit logging included in the authorizer implementation. 3. The default implementation does not support any custom authorizer configs or other access rules apart from ACLs.
      Parameters:
      requestContext - Request context including request resourceType, security protocol and listener name
      op - The ACL operation to check
      resourceType - The resource type to check
      Returns:
      Return AuthorizationResult.ALLOWED if the caller is authorized to perform the given ACL operation on at least one resource of the given type. Return AuthorizationResult.DENIED otherwise.