Table of Contents

Customizing CAPTCHA presentation and function


Pega Platform™ provides CAPTCHA validation on login as one of the options on the Security Policies landing page. A CAPTCHA (or Reverse Turing Test) creates a challenge that is easy enough for a human user to meet, but which is likely to defeat standard automated software. To learn more about enabling CAPTCHA, see Enforcing policies from the Security Policies landing page and Security policies settings.

This article demonstrates how to fine-tune the display and functioning of the default CAPTCHA implementation in Pega Platform, and how to substitute another third-party service, or an in-house solution, instead of the default, SimpleCaptcha.

For information about SimpleCaptcha, see

Suggested Approach

For most implementations the default CAPTCHA provided in Pega Platform will provide satisfactory service. However, if you already use another CAPTCHA service (perhaps one your team has developed) in other applications, and would prefer to deploy it for PRPC, you can do so following the steps below. You can also adjust the display of the default CAPTCHA to better match the need of both system security and valid users who wish to log in.

To use any of the options below, you need to create a ruleset and an access group to serve unauthenticated visitors to the site. The process for creating what you need and configuring Pega Platform to use it is detailed in How to customize the login screen (6.2 SP2), in the sections "Create and deploy a custom ruleset and access group" and "Update the requestor type". You use the same ruleset for CAPTCHA refinements and for updates to the images on the login screen.

Fine-tune the display and functioning of the default CAPTCHA

On the Security Policies landing page (click Configure > System > Settings > Security Policies) you can enable or disable the presentation of a CAPTCHA appears to those attempting to log in. To fine-tune the details of the CAPTCHA (how many characters drawn from what character set, what sort of background for the image, and so on), use the following steps:

  1. Find the Activity pyGenerateCaptcha and save a copy with the same name into the ruleset you created for unauthenticated visitors.
  2. Expand step 1 to display the Java code
  3. Make the adjustments you want and save the rule.
  4. Make sure that, on the Security Policies gadget, the CAPTCHA implementation policy is set to Default (although you have modified the CAPTCHA, you are still using the default CAPTCHA provider).

Some typical adjustments to the CAPTCHA presentation include:

  • Modify the character set: add characters to, or remove them from, this section of the code:

    char[] DEFAULT_CHARS = new char[] { 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'k', 'm', 'n', 'p', 'r', 'w', 'x', 'y', '2', '3', '4', '5', '6', '7', '8', };
  • Change the number of characters displayed by modifying the bolded number in this section of the code:

    nl.captcha.text.producer.DefaultTextProducer textProd = new nl.captcha.text.producer.DefaultTextProducer(6, DEFAULT_CHARS );
  • Change the color of the font by modifying the color specified in the bolded text in this line of the code:

    DEFAULT_COLORS.add(new java.awt.Color(0,51,102));

For more examples of modification that are available,, visit the SimpleCaptcha website,

You can achieve any of the effects demonstrated on the SimpleCaptcha website. However you must use fully-qualified names in Pega Platform to refer to SimpleCaptcha classes. For example, the website demonstrates creating a CAPTCHA using a complex background and Chinese characters:


The SimpleCaptcha website provides the following code to achieve that CAPTCHA:

Captcha captcha = new Captcha.Builder(200, 50)
.addText(new ChineseTextProducer(6)) // Answer will be 6 Chinese characters
.addBackground(new GradiatedBackgroundProducer())
.addNoise(new StraightLineNoiseProducer())
.gimp(new FishEyeGimpyRenderer())
.build(); // Required.

To get the same effect in Pega Platform, modify the code by using fully-qualified names, and add it to pyGenerateCaptcha:

nl.captcha.Captcha captcha = new nl.captcha.Captcha.Builder(200, 50)
.addText(new nl.captcha.text.producer.ChineseTextProducer(6)) // Answer will be 6 Chinese characters
.addBackground(new nl.captcha.backgrounds.GradiatedBackgroundProducer())
.addNoise(new nl.captcha.noise.StraightLineNoiseProducer())
.gimp(new nl.captcha.gimpy.FishEyeGimpyRenderer())
.build(); // Required.

back to top

Substitute another service for the default CAPTCHA

Pega Platform uses the SimpleCaptcha service by default. You can opt to use another third-party service, or a solution you have developed in-house.

In either case, you need to take the following steps:

  1. Locate the following rules and save them without changing their names into the ruleset you created for unauthenticated visitors:
    • pyCustomCaptchaHead
    • pyCustomCaptchaBody
    • pyValidateCustomCaptcha
    • pyCustomCaptchaConnector
  2. Customize the rules as indicated below to serve your custom CAPTCHA solution.
  3. In the Security Policies gadget, make sure the CAPTCHA implementation policy is set to Custom and that CAPTCHA is enabled.

back to top

Substitute a third-party service

Third-party CAPTCHA services provide extensive user guidance: review the documentation of the service you wish to use.

Here is how to implement Google's reCAPTCHA service ( on your Pega Platform login page in place of SimpleCaptcha.

  1. Obtain an account for the third-party service. As reCAPTCHA is now part of Google, you must use a (free) Google account to access reCAPTCHA.
  2. Create a reCAPTCHA key. By default the reCAPTCHA key is restricted to a domain you associate; however, this poses problems as the domain for Pega Platform in development may be different from its domain in the testing environment and from where it is deployed in production. Opt for a global key that is not tightly tied to a domain.

    The key is in two parts, a public key and a private key. The public key is used in the code in the Pega Platform login screen; the private key is what Pega Platform shares with the reCAPTCHA server.
  3. Customize the required rules
    • pyCustomCaptchaHead:
      This HTML fragment rule contains the scripts that are embedded in the <head> tag of the login page (Web-login.htm). For reCAPTCHA add the following:


      #recaptcha_widget {
      background: none repeat scroll 0 0 #FFFFFF;
      border: 1px solid #97C7E7;
      margin: 16px;
      padding: 10px;

      #recaptcha_widget a {
      margin: 5px 0px;
      color: #31669A;
      text-decoration: none;

      #recaptcha_widget a:hover {
      text-decoration: underline;

      <script type="text/javascript">
      var RecaptchaOptions = {
      theme : 'custom',
      custom_theme_widget: 'recaptcha_widget'


      Refer to the reCAPTCHA website to see the other themes you can choose instead of "custom".
    • pyCustomCaptchaBody:
      This HTML fragment rule contains the custom code to send the public key to the third-party server. For reCAPTCHA add the following. Include the registered public key you received in the two lines indicated::

      <div id="recaptcha_widget" style="display:none">
      <div id="recaptcha_image"></div>
      <div class="recaptcha_only_if_incorrect_sol" style="color:red">Incorrect please try again</div>
      <span class="recaptcha_only_if_image">Enter the words above:       </span>
      <span class="recaptcha_only_if_audio">Enter the numbers you hear:</span>

      <input type="text" id="recaptcha_response_field" name="recaptcha_response_field" />

      <div style="padding: 10px; text-align: center; font-family: tahoma; font-size: 11px;"><a href="/javascript:Recaptcha.reload()">Reload CAPTCHA  |  <a href="/javascript:Recaptcha.switch_type('audio')" class="recaptcha_only_if_image">Get an audio CAPTCHA</a><a class="recaptcha_only_if_audio" href="/javascript:Recaptcha.switch_type('image')">Get an image CAPTCHA</a>  |  <a href="/javascript:Recaptcha.showhelp()">Help</a>

      <script type="text/javascript" src= ""> </script>

      <iframe src= "" height="300" width="500" frameborder="0"></iframe>
      <br />
      <textarea name="recaptcha_challenge_field" rows="3" cols="40"> </textarea>
      <input type="hidden" name="recaptcha_response_field" value="manual_challenge">
    • pyValidateCustomCaptcha:
      When the user enters login credentials and a CAPTCHA answer and clicks the Login button, the system passes the parameters submitted on the login screen, plus other parameters the service requires, to this activity. For reCAPTCHA, the additional parameters are recaptcha_challenge_field and recaptcha_response_field, referenced in pyCustomCaptchaBody.
      The activity connects to the third-party server to verify whether the user's response matches the CAPTCHA challenge. If they match, the activity sets the value of pyIsValidCaptcha to true; otherwise the activity sets it to false.
      On the Parameters tab
      List pyIsValidCaptcha:

      On the Steps tab
      In Step 1, set a parameter and four properties in the class Code-Security to hold connector-related information
      Property Value
      param.pyFailMessage ""
      .pyPrivateKey Provide the registered private key you obtained.
      .pyResponseCaptcha param.recaptcha_response_field
      .pyChallenge param.recaptcha_challenge_field
      .pyRemoteip pxRequestor.pxReqRemoteAddr

      Provide the private key you obtained from the third-party service as the value for .pyPrivateKey.

      In Step 2, invoke pyCustomCaptchaConnector (see below):

      In Step 3, set .pyIsValidCaptcha, making sure the precondition (.pyUserIdentifier is present) is enabled:

    • pyCustomCaptchaConnector:
      The connector connects to the ReCAPTCHA service to verify the CAPTCHA answer. This is required for reCAPTCHA; other third-party solutions may have differing requirements.

      On the Servicetab, fill in the fields as follows:
      Field Value
      Endpoint URL Provide the URL your third-party service specifies. For reCAPTCHA, enter
      HTTP Method POST
      HTTP Version Select the version your third-party service specifies. For reCAPTCHA, select 1.1.
      Allow Redirects Selected
      Response Timeout 0000
      Status Value Property .pyStatusValue
      Status Message Property .pyStatusMessage
      Error Handler Flow ConnectionProblem
      Intended for immediate execution

      On the Request tab, set the query string parameters:
      Name Map From Map From Key
      privatekey Clipboard .pyPrivateKey
      remoteip Clipboard .pyRemoteip
      challenge Clipboard .pyChallenge
      response Clipboard .pyResponseCaptcha

      On the Response tab, map the response from the service to the property .pyUserIdentifier on the clipboard:

When all modifications are complete, the login page uses reCAPTCHA instead of SimpleCaptcha:


Your third-party CAPTCHA solution may allow for extensive customizations. For ReCaptcha, customization information is available at

back to top

Substitute a solution developed in-house

If your team has developed its own CAPTCHA solution, you can use that instead of the default SimpleCaptcha. To accomplish this:

  • Override pyGenerateCustomCaptcha to work with the in-house CAPTCHA solution, following the example for reCAPTCHA, above. Note that you cannot use any other standard activity beside pyGenerateCustomCaptcha with the login screen, as users reaching that screen are not yet authenticated.
  • Invoke pyGenerateCustomCaptcha from pyCustomCaptchaBody, as in the example above.
  • Embed in pyCustomCaptchaHead any scripts the in-house service requires, as in the example above.
  • Enter appropriate values in pyCustomCaptchaConnector and pyValidateCustomCaptcha.

back to top

  • System Architect
  • Business Architect
  • UI/UX Specialist
  • Project Manager
  • System Administrator
  • Security
Suggest Edit

91% found this useful

Have a question? Get answers now.

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