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. Continue to Configure Base URL and Authentication.

IIS Proxy

The Internet Information Services (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.
  3. Continue to Configure Base URL and Authentication.
    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.

Configure Base URL and Authentication

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 are not 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:
    1. For a Java Servlet proxy, located within the ..\riaproxy\WEB-INF folder (for example, C:\apache-tomcat-7.0.39\webapps\riaproxy\WEB-INF).
    2. For an IIS proxy, located within the …\ProxyService\Web.config folder.
  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.

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.
To enable token-based 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 where they are used instead of requesting a new token from the authentication server.

To enable OAuth 2.0 (Open Authorization) client credential authentication, set the following properties in the proxy.properties file, replacing client_username and client_password with the client API key and secret key to be used by the proxy:

  • auth.type=oauth2
  • token_url=<oauth token url>
  • client_username=<client key>
  • client_password = <client secret>
  • grant_type=client_credentials

The proxy uses the token URL to fetch the OAuth token from the authentication server and then saves it for the session. The proxy passes the user request with the OAuth token in the request header to get a response from the server and then return it to the client. When the client makes another request, the proxy gets the OAuth token from the session and uses it to get the response. If the token is expired, the proxy will request a new token from the authentication server and use it to serve a client request.

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.