Package io.vertx.ext.web.openapi.router

## Interface Security

-     public interface Security

  An authentication handler factory. This class will hold factories for creating `AuthenticationHandler` objects.

  Handlers will be used when creating the router. This class will configure the handlers to some extent:

  - `APIKeyHandler` - api key handlers will be configured from the document to avoid setup mistakes
  - `BasicAuthHandler` - nothing is required to be configured, they will be used as is
  - `DigestAuthHandler` - nothing is required to be configured, they will be used as is
  - `JWTAuthHandler` - nothing is required to be configured, they will be used as is. Note that for scopes you may need to configure the provider to locate the claims in the right place
  - `OAuth2AuthHandler` can be used in two forms: `oauth2` or `openIdConnect`. When using `oauth2` the function will receive the openapi configuration and it is the function implementor responsibility to configure the handler correctly. For `openIdConnect` mode the asynchronous function can be used to use the discovery mechanism.
  And extra note on `OAuth2AuthHandler` callback. The callback is optional and if not provided the default behavior is to validate tokens as bearer tokens. When specified the callback must be an absolute path relative to the root of the router.
  Author:
    Paulo Lopes

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `RouterBuilder` | `apiKeyHandler​(APIKeyHandler handler)` | Configure the `APIKeyHandler` to be used when creating the router.
    `RouterBuilder` | `httpHandler​(BasicAuthHandler handler)` | Configure the `BasicAuthHandler` to be used when creating the router.
    `RouterBuilder` | `httpHandler​(DigestAuthHandler handler)` | Configure the `DigestAuthHandler` to be used when creating the router.
    `RouterBuilder` | `httpHandler​(JWTAuthHandler handler)` | Configure the `JWTAuthHandler` to be used when creating the router.
    `RouterBuilder` | `oauth2Handler​(String callback, Function<SecurityScheme,​OAuth2AuthHandler> factory)` | Configure the `OAuth2AuthHandler` to be used when creating the router.
    `default RouterBuilder` | `oauth2Handler​(Function<SecurityScheme,​OAuth2AuthHandler> factory)` | Configure the `OAuth2AuthHandler` to be used when creating the router.
    `Future<RouterBuilder>` | `openIdConnectHandler​(String callback, Function<String,​Future<OAuth2AuthHandler>> factory)` | Configure the `OAuth2AuthHandler` to be used when creating the router.
    `default Future<RouterBuilder>` | `openIdConnectHandler​(Function<String,​Future<OAuth2AuthHandler>> factory)` | Configure the `OAuth2AuthHandler` to be used when creating the router.

- - ### Method Detail

    - #### apiKeyHandler

          RouterBuilder apiKeyHandler​(APIKeyHandler handler)

      Configure the `APIKeyHandler` to be used when creating the router.
      Parameters:
        `handler` - the handler to be used
      Returns:
        caller builder

    - #### httpHandler

          RouterBuilder httpHandler​(BasicAuthHandler handler)

      Configure the `BasicAuthHandler` to be used when creating the router.
      Parameters:
        `handler` - the handler to be used
      Returns:
        caller builder

    - #### httpHandler

          RouterBuilder httpHandler​(DigestAuthHandler handler)

      Configure the `DigestAuthHandler` to be used when creating the router.
      Parameters:
        `handler` - the handler to be used
      Returns:
        caller builder

    - #### httpHandler

          RouterBuilder httpHandler​(JWTAuthHandler handler)

      Configure the `JWTAuthHandler` to be used when creating the router.
      Parameters:
        `handler` - the handler to be used
      Returns:
        caller builder

    - #### oauth2Handler

          RouterBuilder oauth2Handler​(String callback,
                                      Function<SecurityScheme,​OAuth2AuthHandler> factory)

      Configure the `OAuth2AuthHandler` to be used when creating the router.
      Parameters:
        `callback` - the callback path to be used to validate tokens
        `factory` - the handler factory that will receive the configuration and return the handler
      Returns:
        caller builder

    - #### oauth2Handler

          default RouterBuilder oauth2Handler​(Function<SecurityScheme,​OAuth2AuthHandler> factory)

      Configure the `OAuth2AuthHandler` to be used when creating the router. In this mode the callback is not used and will not handle `authorization_code` flows.
      Parameters:
        `factory` - the handler factory that will receive the configuration and return the handler
      Returns:
        caller builder

    - #### openIdConnectHandler

          Future<RouterBuilder> openIdConnectHandler​(String callback,
                                                     Function<String,​Future<OAuth2AuthHandler>> factory)

      Configure the `OAuth2AuthHandler` to be used when creating the router.
      Parameters:
        `callback` - the callback path to be used to validate tokens
        `factory` - the handler factory that will receive the `openIdConnect` discovery url and return the handler
      Returns:
        caller builder

    - #### openIdConnectHandler

          default Future<RouterBuilder> openIdConnectHandler​(Function<String,​Future<OAuth2AuthHandler>> factory)

      Configure the `OAuth2AuthHandler` to be used when creating the router. In this mode the callback is not used and will not handle `authorization_code` flows.
      Parameters:
        `factory` - the handler factory that will receive the `openIdConnect` discovery url and return the handler
      Returns:
        caller builder