Reverse proxy servers provide limited external access to private web resources. Because PRPC and the Pega 7 Platform are designed to have a direct connection between the client workstations and the server, some additional configuration is required to set up a reverse proxy server.

This article describes how to set up a reverse proxy server, but not how to set up an Oracle WebLogic clustering environment or other configurations that might seem similar to a reverse proxy server. If you follow this configuration in such cases, sporadic 404 errors or other odd HTTP behaviors can occur.

If your organization has a firewall, and wants to offer limited access through that firewall, you can set up a reverse proxy server outside the firewall. The reverse proxy server sends all the information and data from outside the organization through the firewall and into the local network.

Or, if the server that hosts PRPC or the Pega 7 Platform is made inaccessible to every computer except for the reverse proxy server, the reverse proxy server can be a central point for single sign-on.

When reverse proxy servers are not in use, a user's client workstation sends HTTP requests to the PRPC or the Pega 7 Platform server. The client then tracks the Request Context in several properties on the clipboard pxRequestor page, which identifies the server's URI:

Clipboard page

Properties such as pxRequestor.pxReqContextURI and pxRequestor.pxReqHomeURIidentify the PRPC or the Pega 7 Platform server. In the basic configuration, these clipboard values are populated based on the information that is associated with the incoming request. The property values are reset with each incoming request to reflect any changes (such as a localization change).

With a reverse proxy server, the client workstation sends HTTP requests to the proxy server instead of to the PRPC or the Pega 7 Platform server.

Reverse proxy server setup

The client workstation sends requests to the proxy server with additional information that tells the proxy server where to further direct the request. The proxy server then sends the request to the PRPC or the Pega 7 Platform server.

The issue in this situation is that when the PRPC or the Pega 7 Platform server returns information through the proxy server to the client workstation, the response includes the values of the two properties; these identify the PRPC or the Pega 7 Platform server.

After receiving this response, the client workstation attempts to communicate directly with that address on the next HTTP request, bypassing the proxy server. To avoid this situation, modify your system so that the pxRequestor page properties contain the URI to the proxyserver (instead of to the PRPC or the Pega 7 Platform server). Because these properties are reset with every incoming request, you must also reset the URI information.

You can use the following methods to configure PRPC or the Pega 7 Platform in a reverse proxy environment:

• Approach A: Configure the proxy server to set the context.
• Approach B: Configure PRPC or the Pega 7 Platform to set the context.

Each request sent from a client workstation to the server includes a standard HTTP header. The reverse proxy server configurations use various HTTP settings to alert the PRPC or the Pega 7 Platform server to the proxy server.

Approach A: Configure the proxy server to set context

You can configure the proxy server to tell PRPC or the Pega 7 Platform which URI context to use. When the proxy server receives a request from a client workstation, it adds information to the HTTP header for the request before sending the request.

Add the following information to the HTTP header:

PegaRULES-SetContextURI: http:// proxyserverinformation

where the value of the header is the proxy server URI.

In the following example, the proxy server is:

http://revproxy/AcmeCorp

and the PRPC or the Pega 7 Platform server is:

http://pegaserver:8080/prweb

In this setup, in the first request from the client to the proxy server, the URI reflects the proxy server (notthe PRPC or the Pega 7 Platform server), because the request is routed through the proxy server.

1. Client sends the request to proxy:

GET /AcmeCorp/PRServlet?pyActivity=Rule-Obj-ListView.ShowView HTTP/1.1
Accept: */*
Accept-Language: en-us,zh-cn;q=0.5
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; .NET CLR 1.1.4322)
Host: revproxy
Connection: Keep-Alive
Cookie: JSESSIONID=CF2230E5584A4F3D83627C42EB93AC68; Pega-RULES=HB08F782811828F97671DAF32CE2A72A9; ZeusSessionCookie=HB08F782811828F97671DAF32CE2A72A9

The proxy server then includes the SetContextURI command when it sends the request to the PRPC or the Pega 7 Platform server.

2. Proxy sends the request to the PRPC or to the Pega 7 Platform server:

GET /prweb/PRServlet?pyActivity=Rule-Obj-ListView.ShowView HTTP/1.1
Accept: */*
Accept-Language: en-us,zh-cn;q=0.5
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; .NET CLR 1.1.4322)
PegaRULES-SetContextURI: http://revproxy/AcmeCorp/
Host: pegaserver:8080
Connection: Keep-Alive
Cookie: JSESSIONID=CF2230E5584A4F3D83627C42EB93AC68; Pega-RULES=HB08F782811828F97671DAF32CE2A72A9; ZeusSessionCookie=HB08F782811828F97671DAF32CE2A72A9

When the PRPC or the Pega 7 Platform server returns information through the proxy server to the client, the return data is normally marked (in these properties) as coming from the PRPC or the Pega 7 Platform server.

To keep the proxy server in the session, enable the SetContextURI setting. When the system receives the preceding information, it alters the pxRequestor page properties to reflect the proxy server URI, so that for the next and later HTTP requests, the client continues to use the proxy server.

To implement the SetContextURI header setting, update the prconfig.xml file to set the ContextRewriteEnable entry to true:

<env name="Initialization/ContextRewriteEnabled" value="true" />

Approach B: Configure PRPC or the Pega 7 Platform to set the context

An alternative to having the proxy server set the HTTP header is to perform this action on the PRPC or the Pega 7 Platform server by configuring the prconfig.xml file:

<env name="Initialization/ContextRewriteEnabled" value="true" />

<env name="Initialization/SetBaseHTMLContext" value="http://revproxy/AcmeCorp/setup" />

In the SetBaseHTMLContext setting, identify the proxy server URI. Do not enter the entire login URL as this value. For example, the following value:

http://nnodev02.chhips.chh.com/hsq296/prweb/PRServlet

might cause attempted logins to loop or fail. The correct value is:

http://nnodev02.chhips.chh.com/hsq296/prweb

As in the Configure the proxy to set the context process, you can set a prconfig.xml file entry SetBaseHTMLContext to populate the pxRequestor page properties. The difference with this setup is that the information is applied to any arrivingrequest (as opposed to the request arriving with the values). The system applies the context to every connection. Therefore, even if a user directly connects to the PRPC or the Pega 7 Platform server, the user's pxRequestor page properties reference the proxy names.

To use the SetBaseHTMLContext entry, update the prconfig.xml file to set the ContextRewriteEnabled entry to true.

The first HTTP request from a client workstation to the PRPC or the Pega 7 Platform server is processed directly from the server, and the client receives a normal response. However, the response is sent through the proxy server because the SetBaseHTMLContext setting is implemented on the server. Subsequent requests from that client use the SetBaseHTMLContext entry and are directed through the proxy server.