Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Substitute a third-party service

Updated on July 1, 2021

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.
        pyPrivateKeyProvide the registered private key you obtained.
      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:

      Endpoint URLProvide the URL your third-party service specifies. For reCAPTCHA, enter
      HTTP MethodPOST
      HTTP VersionSelect the version your third-party service specifies. For reCAPTCHA, select 1.1.
      Allow RedirectsSelected
      Response Timeout0000
      Status Value Property.pyStatusValue
      Status Message Property.pyStatusMessage
      Error Handler FlowConnection Problem
      Intended forImmediate execution

      On the Request tab, set the query string parameters:

      NameMap FromMap From Key

      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

  • Previous topic Substituting another service for the default CAPTCHA
  • Next topic Substitute a solution developed in-house

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us