Package io.vertx.ext.auth.oauth2

## Interface OAuth2Auth

- All Superinterfaces:
    `AuthenticationProvider`

      public interface OAuth2Auth
      extends AuthenticationProvider

  Factory interface for creating OAuth2 based `AuthenticationProvider` instances.
  Author:
    Paulo Lopes

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `authorizeURL​(OAuth2AuthorizationURL url)` | The client sends the end-user's browser to this endpoint to request their authentication and consent.
    `void` | `close()` | Releases any resources or timers used by this instance.
    `static OAuth2Auth` | `create​(Vertx vertx)` | Create a OAuth2 auth provider.
    `static OAuth2Auth` | `create​(Vertx vertx, OAuth2Options config)` | Create a OAuth2 auth provider
    `default String` | `endSessionURL​(User user)` | The logout (end-session) endpoint is specified in OpenID Connect Session Management 1.0.
    `String` | `endSessionURL​(User user, JsonObject params)` | The logout (end-session) endpoint is specified in OpenID Connect Session Management 1.0.
    `Future<Void>` | `jWKSet()` | Retrieve the public server JSON Web Key (JWK) required to verify the authenticity of issued ID and access tokens.
    `OAuth2Auth` | `missingKeyHandler​(Handler<String> handler)` | Handled to be called when a key (mentioned on a JWT) is missing from the current config.
    `Future<User>` | `refresh​(User user)` | Refresh the current User (access token).
    `default Future<Void>` | `revoke​(User user)` | Revoke an obtained access token.
    `Future<Void>` | `revoke​(User user, String tokenType)` | Revoke an obtained access or refresh token.
    `Future<JsonObject>` | `userInfo​(User user)` | Retrieve profile information and other attributes for a logged-in end-user.

    - ### Methods inherited from interface io.vertx.ext.auth.authentication.AuthenticationProvider

      `authenticate`

- - ### Method Detail

    - #### create

          static OAuth2Auth create​(Vertx vertx)

      Create a OAuth2 auth provider.
      Parameters:
        `vertx` - the Vertx instance
      Returns:
        the auth provider

    - #### create

          static OAuth2Auth create​(Vertx vertx,
                                   OAuth2Options config)

      Create a OAuth2 auth provider
      Parameters:
        `vertx` - the Vertx instance
        `config` - the config
      Returns:
        the auth provider

    - #### jWKSet

          Future<Void> jWKSet()

      Retrieve the public server JSON Web Key (JWK) required to verify the authenticity of issued ID and access tokens.
      Returns:
        Future result.

    - #### missingKeyHandler

          OAuth2Auth missingKeyHandler​(Handler<String> handler)

      Handled to be called when a key (mentioned on a JWT) is missing from the current config. Users are advised to call `jWKSet()` but being careful to implement some rate limiting function.

      This method isn't generic for several reasons. The provider is not aware of the capabilities of the backend IdP in terms of max allowed API calls. Some validation could be done at the key id, which only the end user is aware of.

      A base implementation for this handler is:

             // are we already updating the jwks?
             private final AtomicBoolean updating = new AtomicBoolean(false);

             // default missing key handler, will try to reload with debounce
             oauth2.missingKeyHandler(keyId -> {
               if (updating.compareAndSet(false, true)) {
                 // Refreshing JWKs due missing key
                 jWKSet(done -> {
                   updating.compareAndSet(true, false);
                   if (done.failed()) {
                     done.cause().printStackTrace();
                   }
                 });
               }
             });

      This handler will purely debounce calls and allow only a single request to `jWKSet()` at a time. No special handling is done to avoid requests on wrong key ids or prevent to many requests to the IdP server. Users should probably also account for the number of errors to present DDoS the IdP.

      Returns:
        Future result.
      See Also:
        `missingKeyHandler(Handler)`

    - #### authorizeURL

          String authorizeURL​(OAuth2AuthorizationURL url)

      The client sends the end-user's browser to this endpoint to request their authentication and consent. This endpoint is used in the code and implicit OAuth 2.0 flows which require end-user interaction.
      Parameters:
        `url` - Base URL with path together with other parameters to be included in the final URL.
      Returns:
        the url to be used to authorize the user.

    - #### refresh

          Future<User> refresh​(User user)

      Refresh the current User (access token).
      Parameters:
        `user` - the user (access token) to be refreshed.
      Returns:
        future result
      See Also:
        `userInfo(User)`

    - #### revoke

          Future<Void> revoke​(User user,
                              String tokenType)

      Revoke an obtained access or refresh token. More info https://tools.ietf.org/html/rfc7009.
      Parameters:
        `user` - the user (access token) to revoke.
        `tokenType` - the token type (either access_token or refresh_token).
      Returns:
        future result

    - #### revoke

          default Future<Void> revoke​(User user)

      Revoke an obtained access token. More info https://tools.ietf.org/html/rfc7009.
      Parameters:
        `user` - the user (access token) to revoke.
      Returns:
        future result

    - #### userInfo

          Future<JsonObject> userInfo​(User user)

      Retrieve profile information and other attributes for a logged-in end-user. More info https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
      Parameters:
        `user` - the user (access token) to fetch the user info.
      Returns:
        future result

    - #### endSessionURL

          String endSessionURL​(User user,
                               JsonObject params)

      The logout (end-session) endpoint is specified in OpenID Connect Session Management 1.0. More info: https://openid.net/specs/openid-connect-session-1_0.html.
      Parameters:
        `user` - the user to generate the url for
        `params` - extra parameters to apply to the url
      Returns:
        the url to end the session.

    - #### endSessionURL

          default String endSessionURL​(User user)

      The logout (end-session) endpoint is specified in OpenID Connect Session Management 1.0. More info: https://openid.net/specs/openid-connect-session-1_0.html.
      Parameters:
        `user` - the user to generate the url for
      Returns:
        the url to end the session.

    - #### close

          void close()

      Releases any resources or timers used by this instance. Users are expected to call this method when the provider isn't needed any more to return the used resources back to the platform.