WebServer

Maven Coordinates

To integrate web server, add the following dependency to your project’s pom.xml file:

Maven Dependency:

<dependency>
  <groupId>io.helidon.webserver</groupId>
  <artifactId>helidon-webserver-security</artifactId>
</dependency>

Usage

There are two steps to configure security with WebServer:

1. Create a security instance and register it with the server.
2. Protect server routes with optional security features.

Example using builders:

WebServer.builder()
        .addFeature(SecurityFeature.builder()1
                            .security(security)
                            .defaults(SecurityFeature.authenticate())
                            .build())
        .routing(r -> r
                .get("/service1", SecurityFeature.rolesAllowed("user"), this::processService1Request))2
        .build();

WebServer.builder()
        // This is step 1 - register security instance with web server processing
        // security - instance of security either from config or from a builder
        // securityDefaults - default enforcement for each route that has a security definition
        .addFeature(SecurityFeature.create(builder -> builder.config(config)))1
        .routing(r -> r
                .get("/service1", this::processService1Request))2
        .build();

security:
  web-server:1
      defaults:
        # defaults for paths configured in the section below
        authenticate: true
      paths:
        - path: "/service1/*"
          methods: ["GET"]
          roles-allowed: ["user"]
          # "authenticate: true" is implicit, as it is configured in defaults above

Security path methods loaded from configuration temporarily match both the configured token and, for a known method written in lowercase or mixed case, its standard uppercase form. For example, get matches get and GET, but does not match Get. An uppercase GET matches only GET; a custom method such as Follow remains exact and case-sensitive. Duplicate methods are ignored, and an absent or empty methods list continues to match all methods.

Loading a non-uppercase known method logs a warning. This compatibility will be removed in a future major version, when configuration will match only the exact token. Update ordinary method names to uppercase now. Programmatic builder method selectors already use exact, case-sensitive matching. See the upgrade guide for the known methods and other affected security configuration.

Note: defaults section in configuration is related to paths on WebServer configured below in paths section, it will not apply to any other path on the webserver.

Protecting Endpoints

There are several endpoints provided by Helidon services, such as:

• Health endpoint (/health)
• Metrics endpoint (/metrics)
• OpenAPI endpoint (/openapi)
• Configured static content (can use any path configured)

These endpoints are all implemented using Helidon WebServer and as such can be protected only through Security integration with WebServer.

The following section describes configuration of such protection using configuration files, in this case using a yaml file, as it provides a tree structure.

Configuring Endpoint Protection

The configuration is usually placed under security.web-server (this can be customized in Helidon).

The following shows an example we will explain in detail:

security:
  providers:
    - abac:1
    - provider-key:2
  web-server:
    defaults:
      authenticate: true3
    paths:
      - path: "/metrics/*"4
        roles-allowed: "admin"
      - path: "/health/*"5
        roles-allowed: "monitor"
      - path: "/openapi/*"6
        abac:
          scopes: ["openapi"]
      - path: "/static/*"7
        roles-allowed: ["user", "monitor"]

If you need to use a properties file, such as application.properties, you can convert the file by using index based numbers for arrays, such as:

security.providers.0.abac=
security.providers.1.provider-key.optional=false
security.web-server.defaults.authenticate=true
security.web-server.paths.0.path=/metrics/*
security.web-server.paths.0.roles-allowed=admin
security.web-server.paths.3.path=/static/*
security.web-server.paths.3.roles-allowed=user,monitor

Reference

• Helidon WebServer Security Integration