Skip to main content
This content has been archived and is no longer being updated. Links may not function; however, this content may be relevant to outdated versions of the product.
LinkedIn
Copied!

Reverse proxy server configuration

Starting with Pega® Platform 7.2, the best practice for deploying behind a proxy server is to use XF-* extension headers. 

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:

Thumbnail

Clipboard page

Properties such as pxRequestor.pxReqContextURI and pxRequestor.pxReqHomeURI identify 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.

Thumbnail

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 proxy server (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 (not the 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 arriving request (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.

If you configure the SetBaseHTMLContext setting and also the PegaRULES-SetContextURI header setting — possibly to different values — the system uses the SetContextURI HTTP header setting.
 
 
 
 
 
 
Did you find this content helpful?

100% found this useful

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best.

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us