Package com.ptc.fba

Class FormBasedLogin

java.lang.Object
com.ptc.fba.FormBasedLogin
public final class FormBasedLogin extends Object
Utility class for performing a form-based login from a Java client.

Supported API: true

Extendable: false

  • Method Details

    • login

      public static boolean login(URL baseUrl, String defaultUserName, String defaultPassword)
      Perform a form-based login.

      If the wt.properties entry wt.auth.form.enabled is not set to true, then this method will simply return true, indicating that no form-based authentication is required according to the server configuration.

      Otherwise, access is tested as per canAccessTestUrl(java.net.URL). If the access test succeeds, then the method will return true, indicating that no form-based authentication is required.

      If the access test fails, then the behavior differs depending on whether an parent Applet can be discovered via WTContext or via NetAuthenticator.getParentComponent(). If so and if the wt.properties entry wt.auth.form.browserLogin.enabled is set to true, then a dialog is presented to the user requesting that they log in via the browser before continuing. The dialog offers a button to show the login page (via AppletContext.showDocument(java.net.URL, java.lang.String). The URL is the value of the wt.properties entry wt.auth.form.browserLogin.url or, if this is unspecified, baseUrl.

      If a parent Applet cannot be found or wt.auth.form.browserLogin.enabled is not set to true, the actual form-based login is delegated to a FormBasedLogin.Handler implementation. The ServiceLoader API is used to obtain the name of the implementation class to use. See ServiceLoader for more information. Note that the META-INF/services file name in this case should be com.ptc.fba.FormBasedLogin$Handler (note the '$' character).

      If no FormBasedLogin.Handler implementation class is specified, then a default implementation will be used as per getDefaultHandler().

      Note that almost all form-based authentication is cookie based. This class will therefore internally establish a cookie handler. Unfortunately, if one forms any HTTP(S) connections to the given server prior to calling this API, those connections may be persistent and may lack a cookie handler. It is therefore critical to establish a cookie handler prior to this point (via CookieHandlerInstaller.ensureHandler()), else this class will fail to function properly.

      Supported API: true

      Parameters:
      baseUrl - Base URL of web application to authenticate against
      defaultUserName - Default user name; can be null
      defaultPassword - Default password; can be null
      Returns:
      True upon a successful login or if a login was unnecessary; otherwise false

    • login

      public static boolean login(URL baseUrl)
      Same as login(java.net.URL, java.lang.String, java.lang.String) but without ability to provide a default username and password.

      Supported API: true
      Parameters:
      baseUrl - Base URL of web application to authenticate against
      Returns:
      True upon a successful login or if a login was unnecessary; otherwise false

    • canAccessTestUrl

      public static boolean canAccessTestUrl(URL baseUrl)
      Test access to baseUrl/wtcore/jsp/testAuthAccess.jsp.

      When form-based authentication is used, this URL should require form-based authentication.

      Supported API: true

      Parameters:
      baseUrl - Base URL of web application
      Returns:
      True if the result of a request to the test URL is as expected, otherwise false.

    • getDefaultHandler

      public static FormBasedLogin.Handler getDefaultHandler()
      Returns an instance of the default FormBasedLogin.Handler implementation. This is primarily intended for use by login(java.net.URL, java.lang.String, java.lang.String).

      This implementation reads wt.auth.form.submitUrl from the server's wt.properties. If this fails or this property does not contain a valid URL, the login attempt immediately fails.

      The implementation then requests baseUrl/login/login.jsp and parses it as XHTML to obtain text and password input fields, their names, and their localized labels. These are used as the definition of the login form. The JSP page can be customized as needed to reflect additional inputs (only text and password inputs are supported at this time) or provide custom labels.

      If a username and password are both passed to the handler and the form definition indicates that these are the only form fields, then an attempt is made to post these to the URL specified by wt.auth.form.submitUrl. If this succeeds and accessing the test URL is then successful (see canAccessTestUrl(java.net.URL)), then success is returned.

      Otherwise a dialog is presented based on the form definition to gather user inputs. If the user cancels out of the dialog, failure is returned. Otherwise the inputs are posted to the URL specified by wt.auth.form.submitUrl and access to the test URL is re-tested. If access fails, the dialog is presented to the user again.

      Supported API: true

      Returns:
      An instance of the default FormBasedLogin.Handler implementation