Configure the AJAX proxy 

By default, the IBM Connections AJAX proxy is configured to allow cookies, headers or mime types, and all HTTP actions to be exchanged among the IBM Connections applications. To change the traffic that is allowed from non-IBM Connections services, explicitly configure it.


Before starting

This task is not required. Only perform it if you want to display information from an external service within IBM Connections.

Important: When configuring the AJAX proxy to allow your users access to trusted third-party web sites, ensure that those sites implement appropriate security controls. Configuring the proxy to mirror content from third-party servers may cause the proxy to mirror malicious content from those servers, so be sure to allow access to trusted sites only.


About this task

The proxy-config.tpl template file defines rules about which HTTP requests, headers, and cookies are allowed to be redirected to the IBM Connections applications. When an IBM Connections server is started, it reads information about the applications from LotusConnections-config.xml, and, based on the rules defined in the proxy-config.tpl template file, configures the proxy to be used by any web browsers or other servers that send requests to IBM Connections.

For example, if you want to allow one application, such as Home page, to proxy a widget, but not allow any of the other applications to proxy it, create an application-specific version of proxy-config.tpl and edit that. See Configure the AJAX proxy for a specific application for more details.

To configure the AJAX proxy...


Procedure

  1. Access the common AJAX proxy configuration template file:

    1. From the dmgr host, go to...:

        app_server_root>\profiles\<dm_profile_root>\bin

        where <app_server_root> is the WAS installation directory and <dm_profile_root> is the dmgr profile directory, typically dmgr01. For example, on Windows:

        C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\bin

        Attention: You must run the following command to start the wsadmin client from this specific directory because the Jython files for the product are stored here. If you try to start the client from a different directory, then the execfile() command that you subsequently call to initialize the administration environment for an IBM Connections component does not work correctly.

    2. Enter the following command to start the wsadmin client:

      • AIX or Linux:

          ./wsadmin.sh -lang jython -user <admin_user_id> -password <admin_password> -port <SOAP_CONNECTOR_ADDRESS Port>

      • Microsoft Windows:

          wsadmin -lang jython -user <admin_user_id> -password <admin_password> -port <SOAP_CONNECTOR_ADDRESS Port>

        where:

        • <admin_user_id> is the user name of a person in the Administrator role on the IBM WAS.

        • <admin_password> is the password of the WAS administrator.

        • <SOAP_CONNECTOR_ADDRESS Port> is the SOAP port for the WAS. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter. If you are not using the default and you do not know the port number, you can look up its value in the WAS Integrated Solution Console. To look up the SOAP port number, perform the following steps:

          1. Open the WAS Integrated Solution Console for the deployment manager, and then select System Administration -> dmgr.

          2. In the Additional properties section expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.

        For example:

        • AIX or Linux:

            ./wsadmin.sh -lang jython -username primaryAdmin -password p@assword -port 8879

        • Microsoft Windows:

            wsadmin -lang jython -username primaryAdmin -password p@assword -port 8879

    3. Check out the configuration file using the following command:

        LCConfigService.checkOutProxyConfig("<temp_directory>",
         "<cell_name>")

        where <temp_directory> is a temporary directory of your choice, and <cell_name> is the name of the cell where the IBM Connections application that uses the global proxy template file is located.

  2. From the temporary directory to which you checked out the configuration files, open proxy-config.tpl in a text editor.

  3. Make your edits. For example, you can do the following things:

    • To explicitly refuse all traffic from a specific site, add a policy as follows:

        <proxy:policy url="malicious.site.com" acf="none">
            <proxy:actions/>
            <proxy:headers/>
            <proxy:cookies/>
            </proxy:policy>

    • To allow a particular service on your network to display a custom widget, you can add the following policy entry to the file:

        <proxy:policy url="http://my.network.com/widget/*" acf="none">
            <proxy:actions>
                <proxy:method>GET</proxy:method>
            </proxy:actions>
            <proxy:headers>
              <proxy:header>User-Agent</proxy:header>
              <proxy:header>Accept.*</proxy:header>
              <proxy:header>Content.*</proxy:header>
              <proxy:header>Authorization.*</proxy:header>
              <proxy:header>If-.*</proxy:header>
              <proxy:header>Pragma</proxy:header>
              <proxy:header>Cache-Control</proxy:header>
            </proxy:headers>
            <proxy:cookies>
                <proxy:cookie>JSESSIONID</proxy:cookie>
            </proxy:cookies>
        </proxy:policy>

    • If a service requires authentication, you can configure it to also allow basic authentication requests by adding a basic-auth-support="true" attribute to the <proxy:policy> element. For example:

        <proxy:policy 
         url="http://my.network.com/service/*" 
         acf="none" 
         basic-auth-support="true">
           ...
        </proxy:policy>

    • If this attribute is not added, when an unauthenticated request is sent to a service that requires authentication, the service does not display the basic authentication dialog, but returns an HTTP 403 status code instead.

    • To allow a particular service to run on your network and to pass cookies for LTPA tokens to the applications:

        <proxy:policy url="http://my.network.com/service/*" acf="none">
            <proxy:actions>
                <proxy:method>GET</proxy:method>
            </proxy:actions>
            <proxy:headers>
              <proxy:header>User-Agent</proxy:header>
              <proxy:header>Accept.*</proxy:header>
              <proxy:header>Content.*</proxy:header>
              <proxy:header>Authorization.*</proxy:header>
              <proxy:header>If-.*</proxy:header>
              <proxy:header>Pragma</proxy:header>
              <proxy:header>Cache-Control</proxy:header>
            </proxy:headers>
            <proxy:cookies>
              <proxy:cookie>JSESSIONID</proxy:cookie>
              <proxy:cookie>LtpaToken</proxy:cookie>
              <proxy:cookie>LtpaToken2</proxy:cookie>
            </proxy:cookies>
        </proxy:policy>

      Note: Specify the headers using regular expressions. If no cookies are specified, the proxy will pass all of them. To prevent it from passing any cookies, specify <proxy:cookies/>.

  4. The following policy allows GET requests to be passed to any web address. If you want to allow your users to have access to all web sites, remove the comments from around this policy. For example, users who add a feed to a community will see a 403 error where the feed results should be displayed unless you perform this step. Be sure that the policy is listed as the last policy in the configuration file.

      <!--proxy:policy url="*" acf="none"> 
          <proxy:actions>
            <proxy:method>GET</proxy:method>
          </proxy:actions>
          <proxy:headers/>
          <proxy:cookies/>
      </proxy:policy-->

      Note: Do not enable this policy on internet-facing deployments because it can allow unauthorized access to internal servers.

  5. You can optionally specify values for the following proxy:meta-data properties. Add any custom configurations before these proxy:meta-data elements.

      circular_redirects

        Specifies that circular redirects are allowed. This property accepts a Boolean value of true or false specified in lower-case letters. If set to true, it supports using a proxy for a site that redirects to the same URL but with different parameters. Such a change is not recognized as a new URL. The default value of this property is true.

      connection-timeout

        Amount of time before an attempt to connect to a host times out. Specified in milliseconds, the default value of this property is 60,000, which is 1 minute.

      max_circular_redirects

        Maximum number of times a circular redirect is allowed before the proxy rejects it. Specified as an integer, the default value of this property is 100.

      maxconnectionsperhost

        Maximum number of simultaneous connections between the proxy and a given host. Specified as an integer, the default value of this property is 20.

      maxtotalconnections

        Maximum number of simultaneous connections between the proxy and all of the hosts together. Specified as an integer, the default value of this property is 50.

      socket-timeout

        Amount of time before an attempt to use a socket times out. Specified in milliseconds, the default value of this property is 60,000, which is 1 minute.

      unsigned_ssl_certificate_support

        Specifies that self-signed SSL certificates are supported. This property accepts a Boolean value of true or false specified in lower-case letters. The default value of this property is true. Change it to false when the system is ready for production.

      For example:

      <proxy:meta-data>
        <proxy:name>maxconnectionsperhost</proxy:name>
        <proxy:value>20</proxy:value>
      </proxy:meta-data>  

  6. Save and close the file.

  7. Check proxy-config.tpl in during the same session in which you checked it out. Check the file in:

      LCConfigService.checkInProxyConfig("<temp_directory>",
       "<cell_name>")

      where <temp_directory> is the temporary directory to which you checked out the configuration files, and <cell_name> is the name of the cell where the application that uses the common proxy-config.tpl file is located.

  8. Restart the application server hosting IBM Connections.

      Configure the AJAX proxy for a specific application
      The AJAX proxy configuration for all of the IBM Connections applications is defined in proxy-config.tpl. If you want to specify different AJAX proxy settings for a specific application only, you can do so by creating a new, application-specific version of the proxy-config.tpl template file.

      Enable the AJAX proxy to forward user credentials
      Edit the proxy configuration template file to instruct the IBM Connections server to accept LTPA tokens. This task is necessary if you want to configure single sign-on between IBM Connections and the servers defined in the proxy configuration file.

      Configure the AJAX proxy to work with a pass-through proxy
      If your organization has a pass-through proxy required for Internet access, configure the AJAX proxy to send requests to it. Otherwise, your connections to the Internet will not work. The AJAX proxy supports Basic authentication.

      Configure the custom library proxy
      Add a proxy policy to the proxy-ecm-config.tpl file to enable communication between IBM Connections and ECM servers.


Parent topic

Security

Related concepts
Enable community feeds


Related tasks


Supporting Lotus Quickr authenticated feeds
Enable single sign-on for SiteMinder

Related reference
IBM Connections configuration error messages

+

Search Tips   |   Advanced Search