Module io.helidon.security.integration.nima
Package io.helidon.security.integration.nima

Class SecurityFeature

java.lang.Object
io.helidon.security.integration.nima.SecurityFeature
All Implemented Interfaces:
Weighted, HttpFeature, HttpSecurity, ServerLifecycle, Comparable<Weighted>, Supplier<HttpFeature>
public final class SecurityFeature extends Object implements HttpSecurity, HttpFeature, Weighted
Integration of security into Web Server.

Methods that start with "from" are to register WebSecurity with WebServer - to create SecurityContext for requests:

Example: 

 // Web server routing builder - this is our integration point
 HttpRouting routing = HttpRouting.builder()
 // register the WebSecurity to create context (shared by all routes)
 .register(SecurityFeature.from(security))

Other methods are to create security enforcement points (gates) for routes (e.g. you are expected to use them for a get, post etc. routes on specific path). These methods are starting points that provide an instance of SecurityHandler that has finer grained methods to control the gate behavior.
Note that if any gate is configured, auditing will be enabled by default except for GET and HEAD methods - if you want to audit any method, invoke audit() to create a gate that will always audit the route. If you want to create a gate and not audit it, use SecurityHandler.skipAudit() on the returned instance.

Example: 

 // continue from example above...
 // create a gate for method GET: authenticate all paths under /user and require role "user" for authorization
 .get("/user[/{*}]", WebSecurity.rolesAllowed("user"))

  • Field Details

    • CONTEXT_ADD_HEADERS

      public static final String CONTEXT_ADD_HEADERS
      Security can accept additional headers to be added to security request. This will be used to obtain multivalue string map (a map of string to list of strings) from context (appropriate to the integration).
      See Also:

  • Method Details

    • create

      public static SecurityFeature create(Security security)
      Create a consumer of routing config to be HttpRouting.Builder.register(java.util.function.Supplier[]) registered} with web server routing to process security requests. This method is to be used together with other routing methods to protect web resources programmatically. Example: 
       .get("/user[/{*}]", WebSecurity.authenticate()
 .rolesAllowed("user"))
      Parameters:
      security - initialized security
      Returns:
      routing config consumer

    • create

      public static SecurityFeature create(Config config)
      Create a consumer of routing config to be HttpRouting.Builder.register(java.util.function.Supplier[]) registered} with web server routing to process security requests. This method configures security and web server integration from a config instance
      Parameters:
      config - Config instance to load security and web server integration from configuration
      Returns:
      routing config consumer

    • create

      public static SecurityFeature create(Security security, Config config)
      Create a consumer of routing config to be HttpRouting.Builder.register(java.util.function.Supplier[]) registered} with web server routing to process security requests. This method expects initialized security and creates web server integration from a config instance
      Parameters:
      security - Security instance to use
      config - Config instance to load security and web server integration from configuration
      Returns:
      routing config consumer

    • secure

      public static SecurityHandler secure()
      Secure access using authentication and authorization. Auditing is enabled by default for methods modifying content. When using RBAC (role based access control), just use rolesAllowed(String...). If you use a security provider, that requires additional data, use SecurityHandler.customObject(Object).

      Behavior:

      • Authentication: enabled and required
      • Authorization: enabled if provider configured
      • Audit: not modified (default: enabled except for GET and HEAD methods)
      Returns:
      SecurityHandler instance configured with authentication and authorization

    • authenticate

      public static SecurityHandler authenticate()
      If called, request will go through authentication process - defaults to false (even if authorize is true).

      Behavior:

      • Authentication: enabled and required
      • Authorization: not modified (default: disabled)
      • Audit: not modified (default: enabled except for GET and HEAD methods)
      Returns:
      SecurityHandler instance

    • audit

      public static SecurityHandler audit()
      Whether to audit this request - defaults to false for GET and HEAD methods, true otherwise. Request is audited with event type "request".

      Behavior:

      • Authentication: not modified (default: disabled)
      • Authorization: not modified (default: disabled)
      • Audit: enabled for any method this gate is registered on
      Returns:
      SecurityHandler instance

    • authenticator

      public static SecurityHandler authenticator(String explicitAuthenticator)
      Use a named authenticator (as supported by security - if not defined, default authenticator is used).

      Behavior:

      • Authentication: enabled and required
      • Authorization: not modified (default: disabled)
      • Audit: not modified (default: enabled except for GET and HEAD methods)
      Parameters:
      explicitAuthenticator - name of authenticator as configured in Security
      Returns:
      SecurityHandler instance

    • authorizer

      public static 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).

      Behavior:

      • Authentication: enabled and required
      • Authorization: enabled with explicit provider
      • Audit: not modified (default: enabled except for GET and HEAD methods)
      Parameters:
      explicitAuthorizer - name of authorizer as configured in Security
      Returns:
      SecurityHandler instance

    • rolesAllowed

      public static SecurityHandler rolesAllowed(String... roles)
      An array of allowed roles for this path - must have a security provider supporting roles.

      Behavior:

      • Authentication: enabled and required
      • Authorization: enabled
      • Audit: not modified (default: enabled except for GET and HEAD methods)
      Parameters:
      roles - if subject is any of these roles, allow access
      Returns:
      SecurityHandler instance

    • allowAnonymous

      public static SecurityHandler allowAnonymous()
      If called, authentication failure will not abort request and will continue as anonymous (defaults to false).

      Behavior:

      • Authentication: enabled and optional
      • Authorization: not modified (default: disabled)
      • Audit: not modified (default: enabled except for GET and HEAD methods)
      Returns:
      SecurityHandler instance

    • authorize

      public static SecurityHandler authorize()
      Enable authorization for this route.

      Behavior:

      • Authentication: enabled and required
      • Authorization: enabled if provider is present
      • Audit: not modified (default: enabled except for GET and HEAD methods)
      Returns:
      SecurityHandler instance

    • enforce

      public static SecurityHandler enforce()
      Return a default instance to create a default enforcement point (or modify the result further).

      Behavior:

      • Authentication: not modified (default: disabled)
      • Authorization: not modified (default: disabled)
      • Audit: not modified (default: enabled except for GET and HEAD methods)
      Returns:
      SecurityHandler instance

    • securityDefaults

      public SecurityFeature securityDefaults(SecurityHandler defaultHandler)
      Create a new web security instance using the default handler as base defaults for all handlers used. If handlers are loaded from config, than this is the least significant value.
      Parameters:
      defaultHandler - if a security handler is configured for a route, it will take its defaults from this handler
      Returns:
      new instance of web security with the handler default

    • setup

      public void setup(HttpRouting.Builder rules)
      Description copied from interface: HttpFeature
      Method to set up a feature.
      Specified by:
      setup in interface HttpFeature
      Parameters:
      rules - routing builder

    • authenticate

      public boolean authenticate(ServerRequest request, ServerResponse response, boolean requiredHint) throws UnauthorizedException
      Description copied from interface: HttpSecurity
      Authenticates the current request according to security configuration. When there is no security implementation present, and required hint is set to false this is a no-op.
      Specified by:
      authenticate in interface HttpSecurity
      Parameters:
      request - server request to read data for authentication
      response - server response
      requiredHint - whether authentication is expected
      Returns:
      whether you should continue with other tasks in this request, if false is returned, the response was already sent, and you should immediately return without modifying it
      Throws:
      UnauthorizedException - when authentication was expected but could not be resolved

    • authorize

      public boolean authorize(ServerRequest request, ServerResponse response, String... roleHint) throws ForbiddenException
      Description copied from interface: HttpSecurity
      Authorize the current request according to security configuration. When there is no security implementation present and there are no roles defined, this is a no-op; if roles are defined this method throws ForbiddenException by default.
      Specified by:
      authorize in interface HttpSecurity
      Parameters:
      request - server request to read data for authorization
      response - server response
      roleHint - the use should have at least one of the roles specified (only used when the security is configured to support roles)
      Returns:
      whether you should continue with other tasks in this request, if false is returned, the response was already sent, and you should immediately return without modifying it
      Throws:
      ForbiddenException - when authorization failed and this request cannot proceed

    • weight

      public double weight()
      Description copied from interface: Weighted
      Weight of this class (maybe because it is defined dynamically, so it cannot be defined by an annotation). If not dynamic, you can use the Weight annotation rather than implementing this interface as long as it is supported by the library using this Weighted.
      Specified by:
      weight in interface Weighted
      Returns:
      the weight of this service, must be a non-negative number