Module io.helidon.webserver.security
Package io.helidon.webserver.security

Class SecurityHandler

java.lang.Object
io.helidon.webserver.security.SecurityHandler
All Implemented Interfaces:
RuntimeType.Api<SecurityHandlerConfig>, Handler, ServerLifecycle
public final class SecurityHandler extends Object implements Handler, RuntimeType.Api<SecurityHandlerConfig>
Handles security for web server. This handler is registered either by hand on router config, or automatically from configuration when integration done through SecurityFeature, or SecurityHttpFeature.create(io.helidon.common.config.Config).

  • Method Details

    • builder

      public static SecurityHandlerConfig.Builder builder()
      Create a new fluent API builder for security handler.
      Returns:
      a new builder

    • create

      public static SecurityHandler create(Consumer<SecurityHandlerConfig.Builder> consumer)
      Create a new instance, customizing its configuration.
      Parameters:
      consumer - consumer of configuration builder
      Returns:
      a new configured handler

    • create

      public static SecurityHandler create(Config config, SecurityHandler defaults)
      Create an instance from configuration.

      The config expected (example in HOCON format): 

       {
   #
   # these are used by SecurityHttpFeature when loaded from config, to register with WebServer
   #
   path = "/noRoles"
   methods = ["get"]

   #
   # these are used by this class
   #
   # whether to authenticate this request - defaults to false (even if authorize is true)
   authenticate = true
   # if set to true, authentication failure will not abort request and will continue as anonymous (defaults to false)
   authentication optional
   # use a named authenticator (as supported by security - if not defined, default authenticator is used)
   authenticator = "basic-auth"
   # an array of allowed roles for this path - must have a security provider supporting roles
   roles-allowed = ["user"]
   # whether to authorize this request - defaults to true (authorization is "on" by default)
   authorize = true
   # use a named authorizer (as supported by security - if not defined, default authorizer is used, if none defined, all is
   #   permitted)
   authorizer = "roles"
   # whether to audit this request - defaults to false, if enabled, request is audited with event type "request"
   audit = true
   # override for event-type, defaults to "request"
   audit-event-type = "unit_test"
   # override for audit message format, defaults to "%3$s %1$s \"%2$s\" %5$s %6$s requested by %4$s"
   audit-message-format = "Unit test message format"
   # override for audit severity for successful requests (1xx, 2xx and 3xx status codes),
   #   defaults to AuditEvent.AuditSeverity.SUCCESS
   audit-ok-severity = "AUDIT_FAILURE"
   # override for audit severity for unsuccessful requests (4xx and 5xx status codes),
   #   defaults to AuditEvent.AuditSeverity.FAILURE
   audit-error-severity = "INFO"

   #
   # Any other configuration - this all gets passed to a security provider, so check your provider's documentation
   #
   custom-provider {
      custom-key = "some value"
   }
 }
      Parameters:
      config - Config at the point of a single handler configuration
      defaults - Default values to copy
      Returns:
      an instance configured from the config (using defaults from defaults parameter for missing values)

    • handle

      public void handle(ServerRequest req, ServerResponse res)
      Description copied from interface: Handler
      Handle request. This method must not return before the response is completed. If the method does asynchronous operations, it must wait for them to complete before returning.
      Specified by:
      handle in interface Handler
      Parameters:
      req - request
      res - response

    • prototype

      public SecurityHandlerConfig prototype()
      Description copied from interface: RuntimeType.Api
      The prototype as it was received when creating this runtime object instance.
      Specified by:
      prototype in interface RuntimeType.Api<SecurityHandlerConfig>
      Returns:
      prototype object used to create this instance

    • queryParamHandlers

      public List<SecurityHandler.QueryParamHandler> queryParamHandlers()
      List of query parameter handlers.
      Returns:
      list of handlers

    • authenticator

      public SecurityHandler authenticator(String explicitAuthenticator)
      Use a named authenticator (as supported by security - if not defined, default authenticator is used). Will enable authentication.
      Parameters:
      explicitAuthenticator - name of authenticator as configured in Security
      Returns:
      new handler instance with configuration of this instance updated with this method

    • authorizer

      public SecurityHandler authorizer(String explicitAuthorizer)
      Use a named authorizer (as supported by security - if not defined, default authorizer is used, if none defined, all is permitted). Will enable authorization.
      Parameters:
      explicitAuthorizer - name of authorizer as configured in Security
      Returns:
      new handler instance with configuration of this instance updated with this method

    • rolesAllowed

      public SecurityHandler rolesAllowed(String... roles)
      An array of allowed roles for this path - must have a security provider supporting roles (either authentication or authorization provider). This method enables authentication and authorization (you can disable them again by calling skipAuthorization() and skipAuthentication() if needed).
      Parameters:
      roles - if subject is any of these roles, allow access
      Returns:
      new handler instance with configuration of this instance updated with this method

    • authenticationOptional

      public SecurityHandler authenticationOptional()
      If called, authentication failure will not abort request and will continue as anonymous (authentication is not optional by default). Will enable authentication.
      Returns:
      new handler instance with configuration of this instance updated with this method

    • authenticate

      public SecurityHandler authenticate()
      If called, request will go through authentication process - (authentication is disabled by default - it may be enabled as a side effect of other methods, such as rolesAllowed(String...).
      Returns:
      new handler instance with configuration of this instance updated with this method

    • skipAuthentication

      public SecurityHandler skipAuthentication()
      If called, request will NOT go through authentication process. Use this when another method implies authentication (such as rolesAllowed(String...)) and yet it is not desired (e.g. everything is handled by authorization).
      Returns:
      new handler instance with configuration of this instance updated with this method

    • customObject

      public SecurityHandler customObject(Object object)
      Register a custom object for security request(s). This creates a hard dependency on a specific security provider, so use with care.
      Parameters:
      object - An object expected by security provider
      Returns:
      new handler instance with configuration of this instance updated with this method

    • auditEventType

      public SecurityHandler auditEventType(String eventType)
      Override for event-type, defaults to "request".
      Parameters:
      eventType - audit event type to use
      Returns:
      new handler instance with configuration of this instance updated with this method

    • auditMessageFormat

      public SecurityHandler auditMessageFormat(String messageFormat)
      Override for audit message format, defaults to "%3$s %1$s \"%2$s\" %5$s %6$s requested by %4$s".
      Parameters:
      messageFormat - audit message format to use
      Returns:
      new handler instance with configuration of this instance updated with this method

    • authorize

      public SecurityHandler authorize()
      If called, request will go through authorization process - (authorization is disabled by default - it may be enabled as a side effect of other methods, such as rolesAllowed(String...).
      Returns:
      new handler instance with configuration of this instance updated with this method

    • skipAuthorization

      public SecurityHandler skipAuthorization()
      Skip authorization for this route. Use this when authorization is implied by another method on this class (e.g. rolesAllowed(String...) and you want to explicitly forbid it.
      Returns:
      new handler instance with configuration of this instance updated with this method

    • audit

      public SecurityHandler audit()
      Audit this request for any method. Request is audited with event type DEFAULT_AUDIT_EVENT_TYPE.

      By default audit is enabled as follows (based on HTTP methods):

      • GET, HEAD - not audited
      • PUT, POST, DELETE - audited
      • any other method (e.g. custom methods) - audited
      Calling this method will override the default setting and audit any method this handler is registered for.
      Returns:
      new handler instance with configuration of this instance updated with this method

    • skipAudit

      public SecurityHandler skipAudit()
      Disable auditing of this request. Will override defaults and disable auditing for all methods this handler is registered for.

      By default audit is enabled as follows (based on HTTP methods):

      • GET, HEAD - not audited
      • PUT, POST, DELETE - audited
      • any other method (e.g. custom methods) - audited
      Returns:
      new handler instance with configuration of this instance updated with this method

    • queryParam

      public SecurityHandler queryParam(String queryParamName, TokenHandler headerHandler)
      Add a query parameter extraction configuration.
      Parameters:
      queryParamName - name of a query parameter to extract
      headerHandler - handler to extract it and store it in a header field
      Returns:
      new handler instance