Which distribution and/or version you choose may depend on the application’s needs. It is recommended that the contents of the Oracle Java installation chosen be carefully reviewed and your application be thoroughly tested before moving to production.

The following distributions are available for most common end-user platforms and can be used to run FSAL:

• The Java 8 family: 32-bit and 64-bit distributions of the JRE, JDK, or Server JRE.

  Note:

  The Server JRE distribution is delivered as a zip file that must be manually extracted. Because this distribution does not perform a software installation and is much more lightweight than the JRE and JDK distributions, this option is ideal for the FSAL when used along with a customized startup script or similar.
• Java 17 and newer. These are only available as a 64-bit JDK distribution, but can be used with FSAL. Be sure to refer to Oracle Fusion Middleware Supported System Configurations for this Forms version in order to ensure you are using a certified Java version.

Here are the main differences between the available Java distributions:

• Java Runtime Environment - JRE: Java 8 only. The JRE installs most components needed for typical end-users. It includes everything needed to run a local Java application, as well as the Java Deployment components (Java Web Start and Java Plug-in). Java Deployment components are not available in major releases newer than Java 8.
• Java Development Kit - JDK: The JDK, available in all versions, is generally for Java developers and includes far more than a typical user should need. The JDK includes a complete JRE, the Java Deployment components (Java 8 only), and tools for developing, debugging, and monitoring and maintaining Java applications.
• Server JRE: Java 8 only. The Server JRE is primarily for deploying Java applications on servers. It includes tools for JVM monitoring and tools commonly required for server applications. It does not include the Java Deployment components needed for browser integration—such as Java Plug-in, Java Web Start, auto-update, and an installer.
• Custom JRE: Oracle Java version 17 or newer. Users can use this version to create a custom JRE distribution.

  Note:

  This guide doesn't cover how to create a custom JRE distribution. Refer to your Java documentation for information on how to use these utilities.

  This version includes these utilities:

  • The jdeps utility: Used to determine which Java modules are needed
  • The jlink utility: Used to create the custom JRE
  • The jpackage utility: Used to package your custom JRE into an installable distribution if desired

Knowing the complete Forms application URL is necessary in order to service the request. Currently, the use of URL redirects or rewrites is not supported, but may be technically possible depending on the server configuration. FSAL expects to receive a fully qualified URL that points to the Forms environment.

A desktop shortcut, script, or batch file can be used in place of a hyperlink in order to make starting the application simple and less error prone.

To start an application with FSAL:

Oracle Forms generated output, typically seen in the Java Console, appears in the shell used to start the application. If the javaw or similar command is used rather than java, a console may not be shown. If using the java command, closing the shell that started the application will terminate the application.

This behavior can be altered to accommodate the application needs using various shell commands and associated switches. Refer to the operating system documentation for information on using the command shell on the user’s platform.

Refer to the FSAL Usage page provided in the installation for a complete list of command line arguments. To access this page, enter this URL in a browser:

http://<server>:<port>/forms/html/fsal.htm

If the applications do not use the Forms audio feature, you can skip these steps.

To enable JavaFX on the user’s machine:

In many cases, users will access a Forms application while within a corporate network. In some cases, this means that the user’s machine requires the appropriate proxy configuration in order to access both internal and external content. In the case of using FSAL, the browser and system level settings may not be visible to the shell that launches the application. Therefore, you may need to include such settings at the time FSAL is run.

You can do this by using arguments that either reference the system proxy settings or include the specific proxy settings.

To use the system proxy settings, enter this command to run the application:

java -Djava.net.useSystemProxies=true –jar frmsal.jar -url "https://<server>:<port>/forms/frmservlet?config=standaloneapp"

The argument, -Djava.net.useSystemProxies=true, causes Java to attempt the call using the proxy settings provided at the system level.

You can also specifically include proxy settings. Here are two examples depending on the protocol (HTTPS or HTTP):

java -Dhttps.proxyHost=<proxyserver> -Dhttps.proxyPort=<proxyserver port number> -Dhttps.nonProxyHosts="localhost|example.com" –jar frmsal.jar -url "https://<server>:<port>/forms/frmservlet?config=standaloneapp"

java -Dhttp.proxyHost=<proxyserver> -Dhttp.proxyPort=<proxyserver port number> -Dhttp.nonProxyHosts="localhost|example.com" –jar frmsal.jar -url "http://<server>:<port>/forms/frmservlet?config=standaloneapp"

See Java Networking and Proxies.

To use a custom protocol, register the custom protocol on the user’s machine and include a properly formatted hyperlink on the desired web page.

Using a Custom Protocol in a Hyperlink

Here is an HTML example that uses a hyperlink with a custom protocol that can be used to launch FSAL with a named Forms configuration, standaloneapp:

<a href="fsal://<SERVER>:<PORT>/forms/frmservlet?config=standaloneapp">Run FSAL</a>

Registering a Custom Protocol

The steps needed to register this new protocol on the user’s machine depend on the operating system. This section provides the steps to register a new protocol on a Microsoft Windows machine. For registering custom protocol handlers on other operating systems, refer to the Operating System documentation or contact the vendor for assistance.

The following commands can either be run individually on a Windows DOS command prompt or executed from a script. Regardless of the approach, the user must have Administrator privileges since this will write to the Windows Registry.

The examples in this section assume:

• The latest Forms frmsal.jar is stored in the user’s home directory.
• The latest Oracle Java 8 (32-bit) JRE is installed. Any certified Oracle Java version can be used, however be sure to adjust the path in the examples below to match the location of the java executable.

In the following commands, be sure to carefully review the last entry in each section. Be sure the path to javaw.exe and the path to frmsal.jar on the user’s machine represents your situation. Note that the Java path used is a special path created when installing the JRE only. If using the JDK, this path will need to be updated.

Commands for non-SSL Requests

reg add HKEY_CLASSES_ROOT\fsal /t REG_SZ /d "Oracle Forms Standalone Launcher" /f
reg add HKEY_CLASSES_ROOT\fsal /v "URL Protocol" /t REG_SZ /d "" /f
reg add HKEY_CLASSES_ROOT\fsal /v "UseOriginalUrlEncoding" /t REG_DWORD /d "00000001"
reg add HKEY_CLASSES_ROOT\fsal\shell /f
reg add HKEY_CLASSES_ROOT\fsal\shell\open /f
reg add HKEY_CLASSES_ROOT\fsal\shell\open\command /t REG_SZ /d "\"C:\Program Files (x86)\Common Files\Oracle\Java\javapath\javaw.exe\" -jar %USERPROFILE%\frmsal.jar -url \"%1\"" /f

Commands for SSL Requests

reg add HKEY_CLASSES_ROOT\fsals /t REG_SZ /d "Oracle Forms Standalone Launcher with SSL/TLS" /f
reg add HKEY_CLASSES_ROOT\fsals /v "URL Protocol" /t REG_SZ /d "" /f
reg add HKEY_CLASSES_ROOT\fsals /v "UseOriginalUrlEncoding" /t REG_DWORD /d "00000001"
reg add HKEY_CLASSES_ROOT\fsals\shell /f
reg add HKEY_CLASSES_ROOT\fsals\shell\open /f
reg add HKEY_CLASSES_ROOT\fsals\shell\open\command /t REG_SZ /d "\"C:\Program Files (x86)\Common Files\Oracle\Java\javapath\javaw.exe\" -jar %USERPROFILE%\frmsal.jar -url \"%1\"" /f

Once the above have been successfully executed, the protocols fsal:// or fsals:// can be used in a browser in place of http:// or https://.

Using The FSAL Certificate Importer

On receiving initial feedback from the server, FSAL checks the TrustStore to determine if the delivered certificate is known. If known and deemed trusted, the application runs without interruption.

If the certificate is unknown, the user sees a prompt indicating this and allowing the user to import a new certificate. This prompt includes a More Information link that provides details about the delivered certificate.

If the user clicks OK, the new certificate is inserted into a newly created Java TrustStore used by Forms/FSAL. This FSAL created TrustStore is used by FSAL for all subsequent requests unless disabled by the user by setting the runtime switch cert_truststore to "java".

This new Java TrustStore is created in the user’s home directory, specifically in:

C:\Users\<USER NAME>\Oracle\forms

The TrustStore file name is formstruststore. Changing the name of the generated TrustStore is not supported. If the file is not found, a new empty file is created. Because this is a Java generated and standard TrustStore file, the tools found in the Oracle Java installation (keytool.exe) can be used to administer this file if necessary.

When running an application, you can use the autoImportCert switch to import unknown certificates automatically. If set to true, the user will not see the prompt before the certificate is imported. This option is not recommended and is provided mostly for testing purposes. Here is an example of how to use it:

java -jar frmsal.jar -url "https://<server>:<port>/forms/frmservlet?config=standaloneapp" -autoImportCert true

For additional information, refer to the FSAL command line arguments listed on the Usage web page. The list of command line arguments is also included here: FSAL Command Line Arguments.

Configuring the KeyStore Manually

Refer to the command line options provided near the end of this document for details on reverting to the previous behavior.

If using the FSAL SSL/TLS Certificate Importer is not desirable, follow these steps prior to using FSAL. It may also be necessary to complete these steps if a compatibility issue is identified with the certificate(s) in use and the FSAL Certificate Importer. Some non-standard or self-generated certificates may not be compatible with the FSAL Certificate Importer.

1. Obtain an SSL/TLS certificate from a known Certificate Authority and configure Oracle HTTP Server (or WebLogic Server) according to the instructions provided by the documentation for those components.
2. Obtain the public key portion of the certificate.

   The public key portion of the certificate is be needed on the user’s machine. If you do not have the public key, there are several ways to obtain it. Obtaining the key chain can be done from any machine that has access to the server. Here is an example of how to obtain the key(s) using the openssl command. Make sure to replace <server>:<port> with the server name and SSL/TLS port number.

   openssl s_client -showcerts -connect <server>:<port> > output.txt

   Note:

   This is pre-installed on most Unix/Linux platforms, but can be obtained for Microsoft Windows.

   The result of running this command will be saved in a file named “output.txt”. The file will contain one or more certificates (depending on the certificate type and how it was created). The certificate is the contents between and including the BEGIN and END header/footer.

3. Copy each certificate to its own text file.

   Be sure to include the BEGIN and END text exactly as shown below and the contents between them. Do not include extra lines above or below the -----BEGIN CERTIFICATE----- or -----END CERTIFICATE----- when saving the file, but do include these header/footer entries.

   Here is an example:

   -----BEGIN CERTIFICATE-----
   MIIFKDCCBBCgAwIBAgIBPTANBgkqhkiG9w0BAQsFADCBrjEpMCcGA1UEAxMgTmlj
   Y2subWFuc0BvcmFjbGUuY29tMRAwDgYDVQQLEwdTdXBwb3J0MQ8wDQYDVQQKEwZP
   cmFjbGUxGTAXBgNVBAcTEENvbG9yYWRvIFNwcmluZ3MxETAPBgNVBAgTCENvbG9y
   . . .
   -----END CERTIFICATE-----

   Tip:

   Alternatively, run the following to directly generate the needed certificate file:

   openssl s_client -showcerts -servername <server name> -connect <server>:<port> | openssl x509 -outform PEM > cert.cer

4. Import the public key(s) into the KeyStore on the user’s machine (for example, cacerts).

   If it is a certificate chain, be sure to import all keys in the chain (signer, intermediate, root, and so on). This means it may be necessary to run the keytool utility more than once. To import the certificate public key(s) use the Java keytool utility, which is included in most Oracle Java distributions.

   Here is an example of how import each certificate using the keytool utility. Refer to the Oracle Java documentation for details on how to use the keytool utility.

   keytool -importcert -alias <server_name> -keystore <JAVA_HOME>/jre/lib/security/cacerts -file cert.cer

   Note:

   The alias must be unique. If there are more than one certificate in the chain each must have a unique alias. However, the root should be imported first and should use the server’s name as its alias. Attempting to use an alias that was previously used will result in an error. It is recommended that the server’s name be used in the alias. For example, the root certificate should be imported first and should be named myserver, the second myserver2, and the third myserver3.
5. Run FSAL with SSL, including the switch, -cert_truststore, set to java in order to bypass the automatic certificate importer:

   java -jar frmsal.jar -url "https://<server>:<port>/forms/frmservlet?config=standaloneapp" –cert_truststore java

Forms, Java Plug-in, and Java Web Start

To run a Java application from a browser with the Java Plug-in or Java Web Start, the user would likely click a hyperlink or bookmark or manually type a URL into a browser. This can potentially put the user's system at risk. To protect against a link opening a malicious Java application on the user’s machine, the Java Plug-in and Java Web Start have special security features, including a requirement to only permit signed (and trusted) applications to run. Unsigned applications are not permitted and are blocked.

All Java JAR files provided by Oracle Forms that run on the user’s machine are signed in order to comply with Java’s security requirements. This allows Forms applications to run safely with Java Web Start. It is further required that custom JAR files (those not provided by Oracle) also be properly signed with a trusted certificate. Signing JARs not provided by Oracle is the customer’s responsibility.

Refer to the jarsigner utility and its documentation for details on how to add a certificate to your own JAR files.

FSAL and Signed JARs

JAR signing is recommended for all deployments, including when using FSAL. Since the inherent risk associated with using a browser is mostly avoided when using FSAL, this client configuration is quickly becoming the preferred approach. That said, you should still carefully consider all security aspects when planning application deployment.

Although running native Java applications like FSAL do not have the same level of built-in security checks found in the Java Plug-in and Java Web Start, limited levels of signed code verification can be enabled.

To enable signed code awareness for FSAL and specifically your application:

1. Obtain the public keys associated with all JAR files used in the application.

   Oracle provided JARs are signed when delivered and this certificate is included in the KeyStore by default. If the signer’s public key for the JAR files used is not available, use the following Java command for each of the JARs to obtain their certificates:

   keytool -printcert -rfc -jarfile <yourJarFile>.jar

   You should see output like this in response:

   -----BEGIN CERTIFICATE-----
   MIIG7zCCBNegAwIBAgIQCl39nB4pDWNpkID7lx+kLjANBgkqhkiG9w0BAQsFADBp
   MQswCQYDVQQGEwJVUzEXMBUGA1UEChMORGlnaUNlcnQsIEluYy4xQTA/BgNVBAMT
   ...
   2ROzDhwQmGHIbDXUo8jXX7NGHdpyZovPm//IO/zp9d6Anka/B3viZlii4eAz6Xbv
   yIafqfh5fS9ZLb4kSHKgf87f4Zlm8YElQF+ZJ+rGVT5xArbEjxcoLyzpmmLWCPeI
   yTifK4P1GgeEhdWol7/R25bAKyPr9OrySnQx9vnUbmKa120i13/mhJm2gXp7qG+P
   uxx1l3SL/yU8gbmOdRno6CcANWLUvQ5FjMVppV8FVPf+7gyhsKrAYP2SMNy2F0qi
   1OIF
   -----END CERTIFICATE-----

   Note:

   The first certificate returned should be the "signer" certificate and the one needed for the steps that follow.
2. Copy the contents of the first certificate into a text file (foo.pem in this example). The copied contents should begin with "-----BEGIN CERTIFICATE-----" and end with "-----END CERTIFICATE-----".
3. On the user’s machine, import each public key into the Java KeyStore that will be used at runtime:

   keytool -importcert -alias foo -file C:\foo.pem

   The above alias can be any alphanumeric string, however be sure to remember it as it will be needed in a coming step. Also, because the –keystore switch was not included, a KeyStore in the user’s home directory is used (or created if one does not exist). The file will be named “.keystore”. To use a different KeyStore and/or KeyStore name, add the –keystore switch as desired.

4. Repeat the above step for each certificate.
5. Create a .java.policy file in the user’s home directory if one does not exist or if you want a fully customized file. Otherwise, use the default file. <JAVA_HOME>\jre\lib\security\java.policy

   Add the following to it:

   keystore ".keystore";
   grant signedBy "foo" {
      permission java.security.AllPermission;
   };

   The “foo” reference is a pointer to the alias used in step 2. Add additional grant signedBy sections for each key that was imported in step 2. The value of keystore is a pointer to the KeyStore file you expect to use.

6. Run your Forms application using FSAL with this slightly modified command entry:

   java -Djava.security.manager -jar frmsal.jar -url "https://yourserver:port/forms/frmservlet?config=standaloneapp"

When running the application, JAR certificates are matched with those in the KeyStore. If they do not match, the app will not run. In the above example, it is assumed that the default java.policy is used or a .java.policy was created in the user’s home directory.

java -Djava.security.manager -Djava.security.policy=${user.home}/foo.policy -jar frmsal.jar -url "https://<server>:<port>/forms/frmservlet?config=standaloneapp"

You can also access a custom policy file from another directory on the user’s machine or a remote location (URL).

java -Djava.security.manager -Djava.security.policy=https://<server>:<port>/foo.policy -jar frmsal.jar -url "https://<server>:<port>/forms/frmservlet?config=standaloneapp"

Single Sign-on

Single Sign-on is an authentication concept that offers many valuable advantages to web applications. The idea of integrating Forms with Single Sign-on (SSO) is often believed to have a significant benefit over using the Forms database login functionality because database credentials for running Forms applications can be hidden from the user.

To use SSO with FSAL you must perform the same configuration steps needed for using SSO with Forms in any other case. For information about how SSO is configured with Forms and how it works, see Using Forms Services with Oracle Access Manager.

To enable SSO for a specific application, set ssoMode=true in the desired application configuration of the Forms Web Configuration settings associated with the application to be protected.