Package io.vertx.mutiny.ext.auth.oauth2

Class OAuth2Auth

java.lang.Object
io.vertx.mutiny.ext.auth.authentication.AuthenticationProvider
io.vertx.mutiny.ext.auth.oauth2.OAuth2Auth
All Implemented Interfaces:
MutinyDelegate
public class OAuth2Auth extends AuthenticationProvider implements MutinyDelegate
Factory interface for creating OAuth2 based AuthenticationProvider instances.

NOTE: This class has been automatically generated from the original non Mutiny-ified interface.

Author:
Paulo Lopes
See Also:
  • OAuth2Auth

  • Field Details

  • Constructor Details

    • OAuth2Auth

      public OAuth2Auth(io.vertx.ext.auth.oauth2.OAuth2Auth delegate)
      Create a new instance of OAuth2Auth delegating to the given (non-null) instance of OAuth2Auth.

    • OAuth2Auth

      public OAuth2Auth(Object delegate)

  • Method Details

    • getDelegate

      public io.vertx.ext.auth.oauth2.OAuth2Auth getDelegate()
      Get the delegate instance.

      This method returns the instance on which this shim is delegating the calls. And so, give you access to the bare API.

      Specified by:
      getDelegate in interface MutinyDelegate
      Overrides:
      getDelegate in class AuthenticationProvider
      Returns:
      the delegate instance

    • jWKSet

      @CheckReturnValue public io.smallrye.mutiny.Uni<Void> jWKSet()
      Retrieve the public server JSON Web Key (JWK) required to verify the authenticity of issued ID and access tokens.

      Unlike the bare Vert.x variant, this method returns a Uni. The uni emits the result of the operation as item. If the operation fails, the uni emits the failure.

      Don't forget to subscribe on it to trigger the operation.

      Returns:
      A Uni representing the asynchronous result of this operation.
      See Also:
      • OAuth2Auth.jWKSet()

    • jWKSetAndAwait

      public void jWKSetAndAwait()
      Retrieve the public server JSON Web Key (JWK) required to verify the authenticity of issued ID and access tokens.

      Unlike the bare Vert.x variant, this method returns a Void. This method awaits indefinitely for the completion of the underlying asynchronous operation. If the operation completes successfully, the result is returned, otherwise the failure is thrown (potentially wrapped in a RuntimeException).

      See Also:
      • OAuth2Auth.jWKSet()

    • jWKSetAndForget

      public OAuth2Auth jWKSetAndForget()
      Retrieve the public server JSON Web Key (JWK) required to verify the authenticity of issued ID and access tokens.

      Unlike the bare Vert.x variant, this method ignores the Void result or any failure.

      Returns:
      The current instance to chain operations if needed.
      See Also:
      • OAuth2Auth.jWKSet()

    • refresh

      @CheckReturnValue public io.smallrye.mutiny.Uni<User> refresh(User user)
      Refresh the current User (access token).

      Unlike the bare Vert.x variant, this method returns a Uni. The uni emits the result of the operation as item. If the operation fails, the uni emits the failure.

      Don't forget to subscribe on it to trigger the operation.

      Parameters:
      user - the user (access token) to be refreshed.
      Returns:
      A Uni representing the asynchronous result of this operation.
      See Also:

    • refreshAndAwait

      public User refreshAndAwait(User user)
      Refresh the current User (access token).

      Unlike the bare Vert.x variant, this method returns a User. This method awaits indefinitely for the completion of the underlying asynchronous operation. If the operation completes successfully, the result is returned, otherwise the failure is thrown (potentially wrapped in a RuntimeException).

      Parameters:
      user - the user (access token) to be refreshed.
      Returns:
      The operation result
      See Also:

    • refreshAndForget

      public OAuth2Auth refreshAndForget(User user)
      Refresh the current User (access token).

      Unlike the bare Vert.x variant, this method ignores the User result or any failure.

      Parameters:
      user - the user (access token) to be refreshed.
      Returns:
      The current instance to chain operations if needed.
      See Also:

    • revoke

      @CheckReturnValue public io.smallrye.mutiny.Uni<Void> revoke(User user, String tokenType)
      Revoke an obtained access or refresh token. More info https://tools.ietf.org/html/rfc7009.

      Unlike the bare Vert.x variant, this method returns a Uni. The uni emits the result of the operation as item. If the operation fails, the uni emits the failure.

      Don't forget to subscribe on it to trigger the operation.

      Parameters:
      user - the user (access token) to revoke.
      tokenType - the token type (either access_token or refresh_token).
      Returns:
      A Uni representing the asynchronous result of this operation.
      See Also:
      • io.vertx.ext.auth.oauth2.OAuth2Auth#revoke(User, String)

    • revokeAndAwait

      public void revokeAndAwait(User user, String tokenType)
      Revoke an obtained access or refresh token. More info https://tools.ietf.org/html/rfc7009.

      Unlike the bare Vert.x variant, this method returns a Void. This method awaits indefinitely for the completion of the underlying asynchronous operation. If the operation completes successfully, the result is returned, otherwise the failure is thrown (potentially wrapped in a RuntimeException).

      Parameters:
      user - the user (access token) to revoke.
      tokenType - the token type (either access_token or refresh_token).
      See Also:
      • io.vertx.ext.auth.oauth2.OAuth2Auth#revoke(User, String)

    • revokeAndForget

      public OAuth2Auth revokeAndForget(User user, String tokenType)
      Revoke an obtained access or refresh token. More info https://tools.ietf.org/html/rfc7009.

      Unlike the bare Vert.x variant, this method ignores the Void result or any failure.

      Parameters:
      user - the user (access token) to revoke.
      tokenType - the token type (either access_token or refresh_token).
      Returns:
      The current instance to chain operations if needed.
      See Also:
      • io.vertx.ext.auth.oauth2.OAuth2Auth#revoke(User, String)

    • revoke

      @CheckReturnValue public io.smallrye.mutiny.Uni<Void> revoke(User user)
      Revoke an obtained access token. More info https://tools.ietf.org/html/rfc7009.

      Unlike the bare Vert.x variant, this method returns a Uni. The uni emits the result of the operation as item. If the operation fails, the uni emits the failure.

      Don't forget to subscribe on it to trigger the operation.

      Parameters:
      user - the user (access token) to revoke.
      Returns:
      A Uni representing the asynchronous result of this operation.
      See Also:
      • io.vertx.ext.auth.oauth2.OAuth2Auth#revoke(User)

    • revokeAndAwait

      public void revokeAndAwait(User user)
      Revoke an obtained access token. More info https://tools.ietf.org/html/rfc7009.

      Unlike the bare Vert.x variant, this method returns a Void. This method awaits indefinitely for the completion of the underlying asynchronous operation. If the operation completes successfully, the result is returned, otherwise the failure is thrown (potentially wrapped in a RuntimeException).

      Parameters:
      user - the user (access token) to revoke.
      See Also:
      • io.vertx.ext.auth.oauth2.OAuth2Auth#revoke(User)

    • revokeAndForget

      public OAuth2Auth revokeAndForget(User user)
      Revoke an obtained access token. More info https://tools.ietf.org/html/rfc7009.

      Unlike the bare Vert.x variant, this method ignores the Void result or any failure.

      Parameters:
      user - the user (access token) to revoke.
      Returns:
      The current instance to chain operations if needed.
      See Also:
      • io.vertx.ext.auth.oauth2.OAuth2Auth#revoke(User)

    • userInfo

      @CheckReturnValue public io.smallrye.mutiny.Uni<io.vertx.core.json.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

      Unlike the bare Vert.x variant, this method returns a Uni. The uni emits the result of the operation as item. If the operation fails, the uni emits the failure.

      Don't forget to subscribe on it to trigger the operation.

      Parameters:
      user - the user (access token) to fetch the user info.
      Returns:
      A Uni representing the asynchronous result of this operation.
      See Also:
      • io.vertx.ext.auth.oauth2.OAuth2Auth#userInfo(User)

    • userInfoAndAwait

      public io.vertx.core.json.JsonObject userInfoAndAwait(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

      Unlike the bare Vert.x variant, this method returns a JsonObject. This method awaits indefinitely for the completion of the underlying asynchronous operation. If the operation completes successfully, the result is returned, otherwise the failure is thrown (potentially wrapped in a RuntimeException).

      Parameters:
      user - the user (access token) to fetch the user info.
      Returns:
      The operation result
      See Also:
      • io.vertx.ext.auth.oauth2.OAuth2Auth#userInfo(User)

    • userInfoAndForget

      public OAuth2Auth userInfoAndForget(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

      Unlike the bare Vert.x variant, this method ignores the JsonObject result or any failure.

      Parameters:
      user - the user (access token) to fetch the user info.
      Returns:
      The current instance to chain operations if needed.
      See Also:
      • io.vertx.ext.auth.oauth2.OAuth2Auth#userInfo(User)

    • authenticate

      @CheckReturnValue public io.smallrye.mutiny.Uni<User> authenticate(io.vertx.ext.auth.authentication.Credentials credentials)
      Authenticate a user.

      The first argument is a Credentials object containing information for authenticating the user. What this actually contains depends on the specific implementation.

      Unlike the bare Vert.x variant, this method returns a Uni. The uni emits the result of the operation as item. If the operation fails, the uni emits the failure.

      Don't forget to subscribe on it to trigger the operation.

      Overrides:
      authenticate in class AuthenticationProvider
      Parameters:
      credentials - The credentials
      Returns:
      A Uni representing the asynchronous result of this operation.
      See Also:
      • AuthenticationProvider.authenticate(Credentials)

    • authenticateAndAwait

      public User authenticateAndAwait(io.vertx.ext.auth.authentication.Credentials credentials)
      Authenticate a user.

      The first argument is a Credentials object containing information for authenticating the user. What this actually contains depends on the specific implementation.

      Unlike the bare Vert.x variant, this method returns a User. This method awaits indefinitely for the completion of the underlying asynchronous operation. If the operation completes successfully, the result is returned, otherwise the failure is thrown (potentially wrapped in a RuntimeException).

      Overrides:
      authenticateAndAwait in class AuthenticationProvider
      Parameters:
      credentials - The credentials
      Returns:
      The operation result
      See Also:
      • AuthenticationProvider.authenticate(Credentials)

    • authenticateAndForget

      public OAuth2Auth authenticateAndForget(io.vertx.ext.auth.authentication.Credentials credentials)
      Authenticate a user.

      The first argument is a Credentials object containing information for authenticating the user. What this actually contains depends on the specific implementation.

      Unlike the bare Vert.x variant, this method ignores the User result or any failure.

      Overrides:
      authenticateAndForget in class AuthenticationProvider
      Parameters:
      credentials - The credentials
      Returns:
      The current instance to chain operations if needed.
      See Also:
      • AuthenticationProvider.authenticate(Credentials)

    • create

      public static OAuth2Auth create(Vertx vertx)
      Create a OAuth2 auth provider.
      Parameters:
      vertx - the Vertx instance
      Returns:
      the auth provider

    • create

      public static OAuth2Auth create(Vertx vertx, io.vertx.ext.auth.oauth2.OAuth2Options config)
      Create a OAuth2 auth provider
      Parameters:
      vertx - the Vertx instance
      config - the config
      Returns:
      the auth provider

    • missingKeyHandler

      public OAuth2Auth missingKeyHandler(Consumer<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:
      • OAuth2Auth#missingKeyHandler(Handler)

    • authorizeURL

      public String authorizeURL(io.vertx.ext.auth.oauth2.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.

    • endSessionURL

      public String endSessionURL(User user, io.vertx.core.json.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

      public 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

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

    • newInstance

      public static OAuth2Auth newInstance(io.vertx.ext.auth.oauth2.OAuth2Auth delegate)
      Creates a new instance of the OAuth2Auth.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class AuthenticationProvider

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class AuthenticationProvider

    • toString

      public String toString()
      Overrides:
      toString in class AuthenticationProvider