Kensho Tsuchihashi (KenshoTsuchihashi)
Project Delivery Leader
Pegasystems Inc.
KenshoTsuchihashi Member since 2010 141 posts
Posted: 3 weeks 4 days ago
Last activity: 3 weeks 3 days ago
Posted: 5 Jul 2021 4:58 EDT
Last activity: 6 Jul 2021 4:58 EDT

How to get OpenID Connect / SAML 2.0 to work on SSL offloading environment



Some customers prefer enabling and offloading SSL at load balancer instead of Pega app nodes. With this solution, called "SSL offloading" or "SSL termination", client and LB communicates with SSL, and LB and server communicates without SSL. Encryption or decryption is CPU-intensive and consumes the resources to a large extent. The SSL offloading concept was introduced to relieve a web server of the processing burden and make the backend work faster. Another benefit is you need certificate only for LB and you don't need it for every app node.


Recently, customer reported to me that Single Sign On process using OpenID Connect does not work with LB that enables SSL offloading. To investigate this issue, we've set up a PoC environment as below and figured a solution. In this post, I'll summarize how we got this to work.

SSL offloading


1. Install nginx

First of all, we've set up a load balancer using nginx-1.13.7 on CentOS 7. I'll skip the detailed steps here but basically we configured cookie stickiness by installing an additional module (nginx-sticky-module-ng-1.2.6) and specified "sticky" in the nginx.conf as below.

Cookie Stickiness

SSL is offloaded by forwarding requests to backend servers by HTTP as below.


Using browser from different terminals, make sure two HTTPS requests to LB (i.e. are forwarded to AP #1 and AP #2 respectively. Be noted, the strings on browser URL field still shows "" even after forwarded. It won't be replaced with "" or "". You can validate that HTTP is used from Tomcat access log.


2. Install Keycloak

We installed Keycloak on Windows PC for OpenID Connect server. I'll skip the detailed step here but basically you need to set up "Realm", "User", and "Client" from Keycloak Admin Console. Pega serves as RP (Relying Party) and Keycloak serves as OP (OpenID Provider) in this scenario.


3. Configure Authentication Service

Create a Data-Admin-AuthService instance for OpenID Connect. Import metadata as below to fulfill all the necessary fields such as Authentication endpoint. This will also generate a Data-Admin-Security-Keystore instance.

Import metadata

Once metadata is imported, fill in Client ID and Client Secret. These can be obtained from Keycloak Admin Console. Then check on "Enable operator provisioning using model operator" and specify an existing model operator.

Authentication Service 1

Authentication Service 2

* Be noted, Login URL (http://backend/...) or Redirect URI (http://backend/...) on the rule form are varied based on how you log in. For example, if you log in from, then it shows Do not misunderstand that this string is a fixed value generated by this rule that you should use. This is just for informational purpose only.

  • Keystore

You can create this on your own but if you import metadata, system will generate it automatically for you.



4. Configure Redirect URI at OpenID Provider

You need to configure Redirect URI at Keycloak. Since LB resides in front of app node, you should specify LB URI with SSL. In our case, this will be

Redirect URI



Now let's test. From browser, access "". Unfortunately, with above settings, you'll face below error.

Invalid parameter - redirect_uri

Keycloak logs below error.

2021-07-05 15:46:42,576 WARN  [org.keycloak.events] (default task-46) type=LOGIN_ERROR, realmId=Demo, clientId=account, userId=null, ipAddress=, error=invalid_redirect_uri, redirect_uri=http://backend/prweb/PRAuth

This is because the URI parameter passed from HTTP header (http://backend/prweb/PRAuth) and the URI registered at Keycloak ( don't match. They have to be identical.



There are two approaches how to fix this issue. Let me outline both steps in detail and my recommendation at the end.


Approach A: Configure the load balancer to set context

1. Create a Dynamic System Settings (prconfig/Initialization/ContextRewriteEnabled/default)

Create below DSS and set the value to "true". This DSS is required for both Approach A and Approach B. After creation, restart Tomcat or it won't take effect.

  • Owning Ruleset: Pega-Engine
  • Setting Purpose: prconfig/Initialization/ContextRewriteEnabled/default


2. Configure LB to tell Pega Platform which URI context to use

When LB receives a request from a client workstation, add a correct load balancer URI information to the HTTP header.




Approach B: Configure Pega Platform to set context

1. Create a Dynamic System Settings (prconfig/Initialization/ContextRewriteEnabled/default)

This is the same DSS as Approach A. Create one and restart Tomcat.

2. Create a Dynamic System Settings (prconfig/Initialization/SetBaseHTMLContext/default)

Create below DSS and set the value to "". Restart Tomcat after creation.

  • Owning Ruleset: Pega-Engine
  • Setting Purpose: prconfig/Initialization/SetBaseHTMLContext/default



After configuration (Approach A or B), test it to see if authentication now works.

1. From browser, access "". It is redirected to Keycloak and below screen is displayed properly. Type username and password that you register at Keycloak.

OP shows log in screen

2. User is successfully created on-the-fly in Pega database and able to log in.

SSO successful



Now, we verified both Approach A and B solves the issue. Are there any differences? This is my personal opinion but I would recommend Approach A, because context is independently added outside of Pega upfront. For example, if you take Approach B, and if you access app node directly (ex., Pega still tries to push the request back to LB. As long as LB is alive it works but if LB is down, you'll see below error.

Browser error

On the other hand, if you are taking Approach A, and if you access app node directly, the context wouldn't be added. That means it won't push back to LB and Pega still works independently from LB. OpenID Connect authentication can even work as long as you add Redirect URIs for AP #1 and AP #2 at OP (see below for Keycloak configuration).

Keycloak Redirect URIs


  • Reference





***Edited by Moderator: Pooja Gadige to add platform capability tags, add Developer Knowledge Share tag***
Pega Platform 8.4.1 Security System Administration Developer Knowledge Share