Package io.github.mastodonContentMover

Class Authenticator

java.lang.Object
io.github.mastodonContentMover.Authenticator
public class Authenticator extends Object
Handles the process of authenticating a connection with a Mastodon instance, using an OAuth callback facilitated by OAuthListener — a minimal HTTP server that runs briefly on the local machine to receive a call from the browser on that machine to the localhost.

Uses the singleton model - for current (and anticipated) use cases, there should not be a need for more than one Authenticator object to be instantiated simultaneously.

Credentials for the client and the user account are saved and retrieved from the filesystem in XML format using ClientCredentialStore and UserCredentialStore respectively.

Credentials are not persisted when connecting via a custom port (maybe this could be changed if there is a significant need for it, but it would require a rework of the data structure used to save credentials and the need for a custom port is expected to be a rare use case anyway).

Since:
0.01.00
See Also:

  • Method Details

    • getSingletonInstance

      protected static Authenticator getSingletonInstance()
      Obtains a reference to the currently instantiated Authenticator singleton object, or instantiates one if that has not already been done.

      Returns:
      a reference to an Authenticator object

      Since:
      0.01.00

    • getClient

      protected social.bigbone.MastodonClient getClient(String instance, String username, Integer customPort) throws jakarta.xml.bind.JAXBException, IOException, social.bigbone.api.exception.BigBoneRequestException
      Obtains an authenticated MastodonClient object for the specified user account on the specified Mastodon instance, using saved credentials from previous use of the tool or by exhausting the various possible methods of authentication in order of preference.

      The sequence of steps for OAuth authentication is as follows:
      1. Authenticating the client with the Mastodon instance, to obtain a client key and secret
      2. Using the client key to obtain an OAuth URL
      3. Accessing the URL while logged in with the user account within the browwer to obtain an OAuth callback code, sent within the callback request after the user authorizes the tool
      4. Using the client key, secret and callback code to obtain an access token that can then be used with user-level API methods
      5. Using that access token to build an authenticated MastodonClient object


      This method:
      1. Attempts to load an existing access token for a user from file (saved from previous use of the tool
      2. If a token is not available, attempts to load existing client credentials from file (saved from previous use of the tool)
      3. If client credentials are not available, registers the tool as a client to obtain a client key and secret that can be used to obtain an access token via OAuth authorization
      4. Uses the client key (loaded or obtained) to load an OAuth URL and obtain a callback code, and then uses the client key and secret together with the callback code to obtain an access token for the user account logged in in the browser
      5. Once the user-level access token is obtained (either loaded from file or via OAuth), it is used to build an authenticated MastodonClient


      OAuth authorization is preferred as it is most likely to accommodate browser-based security measures such as two-factor authentication. There is currently no check within the tool to ensure that the Mastodon user account logged in to the given instance within the browser when OAuth authorization is given matches the user account provided as a command-line parameter to this tool (TODO: fix this).

      Both read and write access is requested irrespective of the operation being performed, because the scope must be specified as part of the client registration for all operations the client will perform on the given Mastodon instance. If write access was only requested on occasions when statuses were being reposted from an archive, it would be necessary to maintain two separate sets of client credentials for each instance (one with read access, and one with write access) or renew tokens each time the tool was run.

      OAuth authorization is implemented using a minimal HTTP server that runs briefly on the local machine (while the user reviews the OAuth permission web page on the specified Mastodon instance and chooses whether or not to authorize the tool). A localhost URL is passed on a call to the Mastodon /oauth/authorize endpoint, so the OAuth token is sent by the instance on callback to the temporary HTTP server on the local machine. Once this is detected, the HTTP server is shut down.

      This HTTP server runs on the port specified in the constant DEFAULT_PORT, set at time of writing to 8081. In the event that this port is already in use on the local machine, it is possible to run this tool using a custom port that can be specified here as a parameter Credentials are not saved to or loaded from file when connecting via a custom port (OAuth or another method of authentication must be used every time the tool is run). Approaching this differently would require quite a significant rework of the data structure used to save credentials, and the need for a custom port is already expected to be a rare use case. Both user and client credential storage would need to be rewritten, as the port must be given as part of the callback URL submitted during client registration (you cannot register the client once and then re-use that client registration for OAuth user authorization irrespective of callback port.

      Alternative ways to obtain an access token include the getUserAccessTokenWithPasswordGrant method offered by the BigBone library's OAuthMethods.kt, and manual entry of an access token. Currently neither of these are supported, but they could and should be so the tool can still be used in the event of an issue with OAuth authorization (TODO). Obviously typing in an access token manually would be cumbersome; perhaps it could be a command-line parameter.

      Parameters:
      instance - the hostname or address of the Mastodon instance with which this method should authenticate
      username - the username for the account on the Mastodon instance with which this method should authenticate
      customPort - a valid port that can be bound on the local machine to briefly run an

      Returns:
      an authenticated MastodonClient

      Throws:
      social.bigbone.api.exception.BigBoneRequestException - (TODO: add more info here on when this happens)
      jakarta.xml.bind.JAXBException - (TODO: add more info here on when this happens)
      IOException - (TODO: add more info here on when this happens)

      Since:
      0.01.00

    • oAuthCallback

      protected void oAuthCallback(String code)
      Passes an OAuth callback code received by an instance of OAuthListener (which runs a separate thread) to this object, so it can then be collected by getClient(String instance, String username, Integer customPort) to perform further authentication tasks.

      Parameters:
      code - the OAuth callback code

      Since:
      0.01.00
      See Also: