Installing the Proxy

Spectrum™ Technology Platform ships with two proxy implementations, one for Java Servlet containers (2.4 and higher) and one for IIS (.NET). Decide which proxy to install, then verify the installation was successful.

Java Servlet Proxy

To install the Java Servlet proxy:

  1. Download the proxy binary from your Spectrum™ Technology Platform installation at: http://hostname:port/managers/PlatformConfiguration/Exports/riaproxy.war.
  2. Deploy the WAR file to a web application server of your choice. Refer to the documentation of the application server for details on deploying WAR files. If you are using Apache Tomcat, this involves copying the WAR file into the %CATALINA_HOME%\webapps directory. As long as automatic application deployment is enabled and you keep the WAR file name intact, the proxy will be made available under the default context path of riaproxy.
    Note: If you decide to deploy the proxy under a different context path, be sure to provide the correct value when following the step to define the path to the proxy in your web application. This step is defined in the section: Define the Path to your Proxy
  3. Once the proxy has been installed, set a trusted base URL (preferably to your Spectrum™ Technology Platform server's endpoint). URLs that do not start with this value will not be relayed by the proxy. This is necessary to prevent the proxy from being abused to request resources from other domains than the one required by the JavaScript API. Leaving this set to “http” will allow the proxy to forward to any other http endpoint. To configure this:
    1. Open the proxy.properties file located within the ..\riaproxy\WEB-INF folder (for example, C:\apache-tomcat-7.0.39\webapps\riaproxy\WEB-INF).
    2. Set the value of the trusted.base.url property to http://servername, where servername is a placeholder for the hostname the JavaScript API is installed on; for example, trusted.base.url=http://localhost:8080.
    3. Restart the proxy application.

      Note: If your Spectrum™ Technology Platform server is deployed to https, then the Spectrum™ Technology Platform server endpoint specified here should start with https rather than http.

  4. To enable HTTP Basic authentication, set the following properties in the proxy.properties file, replacing username and password with the actual login credentials to be used by the proxy:
    • auth.type=basic
    • anonymous_username=username
    • anonymous_password=password
    Note: This performs HTTP Basic authentication against the JavaScript API server-side component on behalf of but transparent to the client. Requests by the client to the proxy are not protected and additional steps have to be taken if that is necessary. Refer to the documentation of your application server for further details.
  5. To enable token authentication, set the following properties in the proxy.properties file, replacing username and password with the actual login credentials to be used by the proxy:
    • auth.type=token
    • token_url=<authentication server domain> (for example, http://localhost:8080)
    • anonymous_username=<authentication server username>
    • anonymous_password = <authentication server password>
    Once the server request is successful, the proxy will send the session and authentication token back to the client as cookies. When the client makes another request, the browser will resend these cookies back to the proxy and are used instead of requesting a new token from the authentication server.

IIS Proxy

The IIS proxy requires IIS7 or above. You must have admin rights and be running in administrator mode.

To install the IIS proxy:

  1. Download the proxy binary from your Spectrum™ Technology Platform installation at: http://hostname:port/managers/PlatformConfiguration/Exports/riaProxy.zip.
  2. Unzip the file and run setup.exe to install the proxy into IIS. During the install, the WebSetup dialog will select a default web site, but you have the option to select a web site of your choice. Refer to the documentation of the application server for details on deploying WAR files.
    Note: The configuration of the IIS proxy is equivalent to the Java Servlet proxy, in that you need to configure the base URL and authentication. The only difference is the configuration file is located at …\ProxyService\Web.config. The Web.config file is an XML file and configuration properties are set with <add> elements nested inside the <appSettings> element of the file; for example, <add key=”trusted.base.url” value=http://localhost:8080.

Verification

Once you have installed the proxy and set it to forward the requests to the JavaScript application, you can test it by accessing the JavaScript API file, ria.js directly and through the proxy. Suppose the JavaScript API is installed on 'myserver' on port 8070 and the proxy is installed on the localhost using the default name of riaproxy on default port 80, the two URLs are as shown below:

  • http://myserver:8070/ria/ria.js
  • http://localhost/riaproxy/proxy.aspx?url=http%3A%2F%2Fmyserver%3A8070%2Fria%2Fria.js

Compare the pages loaded by the two URLs and make sure they are same.