Skip to main content

Table of Contents

Substitute a third-party service


Only available versions of this content are shown in the dropdown

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. Choose a global key that is not tightly tied to a domain.
    1. 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:

    1. 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".
    2. 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">
    3. 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, select pyIsValidCaptcha:

      1. 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
      2. Provide the private key you obtained from the third-party service as the value for .pyPrivateKey.
      3. In Step 2, invoke pyCustomCaptchaConnector (see below):
      4. In Step 3, set pyIsValidCaptcha, making sure the precondition (pyUserIdentifier is present) is enabled:
    4. 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 Service tab, 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 Connection Problem
      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

Did you find this content helpful?

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