Module one.jpro.platform.auth.core
Package one.jpro.platform.auth.core.oauth2

Class OAuth2AuthenticationProvider

java.lang.Object
one.jpro.platform.auth.core.oauth2.OAuth2AuthenticationProvider
All Implemented Interfaces:
AuthenticationProvider<Credentials>
Direct Known Subclasses:
OpenIDAuthenticationProvider
public class OAuth2AuthenticationProvider extends Object implements AuthenticationProvider<Credentials>
Provides an OAuth2-based AuthenticationProvider that supports various OAuth 2.0 flows (e.g., AUTH_CODE, PASSWORD, CLIENT, etc.). This class handles interaction with an OAuth2 authorization server, optionally starting a local HTTP server to capture callbacks for redirect-based flows.

Typical usage involves:

  1. Creating an instance with the desired OAuth2Options
  2. Directing the end-user to the authorization URL (authorizeUrl(OAuth2Credentials)) if needed
  3. Using authenticate(Credentials) to acquire a User object

This class can also handle optional tasks such as token introspection, token refresh, token revocation, user information retrieval, and logout.

  • Constructor Details

    • OAuth2AuthenticationProvider

      public OAuth2AuthenticationProvider(@Nullable @Nullable javafx.stage.Stage stage, @NotNull @NotNull OAuth2API api)
      Creates an OAuth2 authentication provider.

      This constructor sets up the internal HttpServer to handle redirect-based OAuth2 flows, especially if authorizeUrl(OAuth2Credentials) is used to open a browser flow.

      Parameters:
      stage - the JavaFX application stage (maybe null if you are running in a non-JavaFX environment)
      api - the OAuth2 API utility, which must not be null
      Throws:
      NullPointerException - if api is null
      IllegalArgumentException - if any mandatory option in OAuth2Options is invalid

    • OAuth2AuthenticationProvider

      public OAuth2AuthenticationProvider(@Nullable @Nullable javafx.stage.Stage stage, @NotNull @NotNull OAuth2Options options)
      Creates an OAuth2 authentication provider using the specified OAuth2Options.
      Parameters:
      stage - the JavaFX application stage (maybe null)
      options - the OAuth2 options used to configure OAuth2 interaction
      Throws:
      NullPointerException - if options is null
      IllegalArgumentException - if any mandatory option in OAuth2Options is invalid

  • Method Details

    • getOptions

      @NotNull public final @NotNull OAuth2Options getOptions()
      Returns the OAuth2Options used by this provider.
      Returns:
      the OAuth2 configuration options

    • authorizeUrl

      public CompletableFuture<String> authorizeUrl(@NotNull @NotNull OAuth2Credentials credentials)
      Generates an authorization URL based on the provided OAuth2Credentials, then prepares (and possibly starts) a local HTTP server to capture the OAuth2 authorization callback. The returned CompletableFuture completes with the authorization URL once the server is ready.

      You typically call this method when using OAuth2Flow.AUTH_CODE or other flows requiring user interaction in a web browser. If not running in a browser environment (i.e., WebAPI.isBrowser() is false), the method also ensures a fresh local HTTP server is created to handle the callback.

      Parameters:
      credentials - the OAuth2 credentials containing the flow configuration; must not be null
      Returns:
      a future that completes with the authorization URL once the local server is ready, or completes exceptionally if server setup fails
      Throws:
      NullPointerException - if credentials is null

    • authenticate

      public CompletableFuture<User> authenticate(@NotNull @NotNull Credentials credentials)
      Authenticates a user based on the given Credentials. Depending on the type of credentials, different OAuth2 flows or validations may be triggered:
      • UsernamePasswordCredentials triggers the Password flow.
      • TokenCredentials attempts to validate an existing token, optionally performing token introspection if the token is not a valid JWT or is expired.
      • OAuth2Credentials triggers the configured OAuth2 flow (e.g., AUTH_CODE, PASSWORD, CLIENT, etc.).
      Specified by:
      authenticate in interface AuthenticationProvider<Credentials>
      Parameters:
      credentials - the credentials to authenticate
      Returns:
      a future that completes with the authenticated User, or completes exceptionally if authentication fails
      Throws:
      ClassCastException - if credentials is not a recognized subtype
      CredentialValidationException - if the credentials fail validation
      RuntimeException - if the flow is unsupported, or if token introspection is unavailable
      See Also:

    • discover

      public CompletableFuture<OpenIDAuthenticationProvider> discover()
      Initiates OpenID Connect Discovery to dynamically obtain configuration data (e.g., token endpoint, authorization endpoint, user info endpoint). The CompletableFuture completes with a new OpenIDAuthenticationProvider upon success or completes exceptionally on failure.
      Returns:
      a future that completes with an OpenIDAuthenticationProvider once discovery succeeds

    • introspect

      public CompletableFuture<org.json.JSONObject> introspect(User user, String tokenType)
      Performs token introspection for the specified tokenType in the user's auth data.

      The introspection response is returned as a JSONObject. For more details, see RFC 7662.

      Parameters:
      user - the user whose token is to be introspected
      tokenType - the token type to introspect (e.g., "access_token" or "refresh_token")
      Returns:
      a future that completes with the introspection response as JSON
      Throws:
      NullPointerException - if user is null

    • refresh

      public CompletableFuture<User> refresh(User user) throws IllegalStateException
      Refreshes an existing user session using its refresh token. Upon success, returns a new User instance with updated tokens.
      Parameters:
      user - the user whose token will be refreshed
      Returns:
      a future that completes with the new user instance containing updated tokens
      Throws:
      IllegalStateException - if the user has no valid refresh token

    • revoke

      public CompletableFuture<Void> revoke(User user, String tokenType)
      Revokes the given user's access_token or refresh_token.

      See RFC 7009 for details on token revocation.

      Parameters:
      user - the user for whom to revoke the token
      tokenType - the token type to revoke (either "access_token" or "refresh_token")
      Returns:
      a future that completes when the token is successfully revoked

    • userInfo

      public CompletableFuture<org.json.JSONObject> userInfo(@NotNull @NotNull User user)
      Retrieves detailed user information (e.g., profile data) from an OpenID Connect or OAuth2 userInfo endpoint using the user's access_token.

      This method also checks to ensure that the returned sub (subject) matches the one in the token's claims if present. If the endpoint returns a token field, it will attempt to verify that token as well.

      Parameters:
      user - the user whose information is to be fetched (must have an access_token)
      Returns:
      a future that completes with the user information in JSON format, or completes exceptionally if validation fails
      Throws:
      NullPointerException - if user is null
      AuthenticationException - if the subject in the UserInfo response does not match
      TokenExpiredException - if the token field has an expired token
      IllegalStateException - if the token field is invalid in any way

    • logout

      public CompletableFuture<Void> logout(@NotNull @NotNull User user)
      Logs out the specified user by invalidating (or otherwise marking as invalid) its access token (and optionally refresh token) on the authorization server.
      Parameters:
      user - the user to logout
      Returns:
      a future that completes when the user is logged out