How You Can Configure the OpenROAD Server Java Client Gatekeeper2
The gatekeeper2 web server application serves two important functions:
Message Transformation
Converts HTTP requests into DCOM calls, and converts DCOM return values into HTTP responses.
Security
Decides which clients are allowed to make calls and which 4GL SCPs they are permitted to call.
The Java Client gatekeeper2 (source: OpenROADGatekeeper.java) provides an out-of-the-box experience through using the compiled *.class files and configuration options, which you can set in the web.xml file. The class files and web.xml file are contained in the WEB-INF subdirectory, which you may copy directly into a Tomcat webapps subdirectory.
The installed files for this original gatekeeper are listed in
OpenROAD Server Java Client Gatekeeper2 Components.
The servlet class itself should work with different web servers (for JBoss, WebSphere, WebLogic, and so on); no Tomcat-specific Java functions are used. BASIC authentication should be supported by any web server; this is why none of the more advanced options were used. Configuration files (web.xml for Tomcat 5.0 or higher) might be slightly different, but it should not be difficult to convert them.
Prepare for Tomcat
To prepare your OpenROAD server to work with Tomcat, follow the appropriate procedure for your platform. For more informationn about installing Tomcat, see
Installing Tomcat.
To prepare a Windows server for Tomcat
1. Create a new subdirectory in %CATALINA_HOME%\webapps. For example:
mkdir %CATALINA_HOME%\webapps\openroad
2. Copy the WEB-INF subdirectory from %II_SYSTEM%\ingres\orjava\Gatekeeper2 into the subdirectory created in Step 1.
3. If you have not done this yet, copy the %II_SYSTEM%\ingres\orjava\openroad.jar file into %CATALINA_HOME%\shared\lib.
To prepare a Linux or UNIX server for Tomcat
1. Create a new subdirectory in $CATALINA_HOME/webapps. For example:
mkdir $CATALINA_HOME/webapps/openroad
2. Copy the WEB-INF subdirectory from $II_SYSTEM/ingres/orjava/Gatekeeper2 into the subdirectory created in Step 1.
3. If you have not done this yet, copy the $II_SYSTEM/ingres/orjava/openroad.jar file into $CATALINA_HOME/shared/lib.
You now may configure Tomcat (Authentication and Servlet Options—see
How You Configure Tomcat) and restart it.
How You Configure Tomcat
Authentication:
The web.xml file is configured to use BASIC web server authentication (with username and password) using the role "orspo_users".
A default Tomcat installation uses the $CATALINA_HOME/conf/tomcat_users.xml file for authentication information.
You must add this role and according user entries under the <tomcat-users> tag in this file, for example:
<tomcat-users>
...
<role rolename="orspo_users"/>
<user username="testuser" password="xyz" roles="orspo_users"/>
</tomcat-users>
Servlet Options:
You may configure the servlet with the following InitParameters in the web.xml file:
OpenROAD_ServerApp
Defines the name of the OpenROAD Server application that the gatekeeper connects to.
If this parameter is missing or set to *, it allows the application name to be provided by the "image" parameter of the Initiate request.
We recommend that you have different webapps for separate OpenROAD applications.
permittedSCPs
Limits the access to permitted SCPs.
If this parameter is missing or set to *, it allows access to all SCPs.
Names of SCPs are delimited by whitespaces (space, tab, newline, carriage-return, form-feed).
logcalls
Logs requests of the OpenROAD Gatekeeper to the file $CATALINA_HOME/logs/localhost_log.yyyy-mm-dd.txt when set to 1. This parameter is provided for testing purposes.
Frequenty Asked Questions
Q: How do you provide the username and password on Initiate?
A: The username and password credentials can be provided in the flags parameter of the RemoteServer.Initiate() method. For example:
rso.Initiate( ..., flags=':testuser:xyz::');
If the username and password are not provided, the user will be prompted to provide the credentials (only on the first Initiate).
Q: How is security applied?
A: Authorization is performed using the web server.
An authorized user may call any SCP provided by the application configured with the OpenROAD_ServerApp config parameter. Additional security should be provided by using SSL encryption. For more information, see
http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html.
Customized authentication or authorization can be accomplished through advanced web server configuration or customizing the Java source of the Gatekeeper (this requires a Java SDK).
Q: Can the authorization be switched off?
A: You can switch off web server authentication by removing the <security-constraint>, <login-config>, and <security-role> tags from the web.xml file.
This can be useful for testing or if you use applications in a trusted environment.
Q: What is the URL of the gatekeeper?
A: The URL is the address of the web server extended by the name of the directory for the web application, for example:
http://myhost:8080/openroad/
Or:
https://myhost:8443/openroad/
Some web servers require the trailing slash when using the directory name (for example, Tomcat 7, if the attribute "sessionCookiePathUsesTrailingSlash" is not set to "false" for the <Context> used). Otherwise, errors could occur (for example, "0x8004C001 Your HTTP session has timed out. You must initiate again.").
Appending the name of the servlet is not required because it is already configured in the web.xml file, but is optional:
http://myhost:8080/openroad/OpenROADGatekeeper