This content has been archived.

Configuring login security and password policies in PRPC 6.3 SP1 to Pega 7.1.x

You can configure user login security and password policies on the Security Policies landing page. These policies help you to defend your system against so-called "brute force" attacks, in which an attacker tries thousands of randomly generated credentials or popular passwords from a password dictionary to gain access to your application.

You can also set policies to improve operator ID and password security and review security audit logs of attempts to access your application.

Policy changes take effect immediately and affect all operators who use your application. The first time the policies are enabled on a system, all users are prompted to change their password when they log in.

Suggested approach

The Security Policies landing page is available to operators who have the pzViewAuthPoliciesLP privilege in their access roles. This privilege is part of the standard PegaRULES:SysAdmin4 role.

Enabling security policies

  1. Click Designer Studio > System > Settings > Security Policies. If the policies are disabled, the tab is displayed in its "closed" mode.
  2. Click Enable Security Policies.
  3. Configure the security policies as required, and click Submit.

The policies apply to several properties and conditions, and you can enable none, some, or all of the following policy groups.

Operator ID

Set the minimum number of characters that an operator ID must have. For example, if your company is ThisCo, and every operator ID ends with "", you can set the minimum length to 12 (the length of the mandatory string plus one character).

With this policy enabled, users cannot create an operator ID that is shorter than the required length.


Good system security includes requiring passwords to be complex enough so that they are not easy to guess. A password that includes letters, numbers, and special characters, and that also must be changed at regular intervals, protects the operator's account and the whole system.

Set values for the following policies:

  • Minimum operator password length: Set a value between 3 and 64. The default is 8.
  • Minimum numeric characters: Set the number of numerical characters that the password must contain, between 0 and 64. The default is 1.
  • Minimum alphabetic characters: Set the number of alphabetical characters (a-z and A-Z) that the password must contain, between 0 and 64. The default is 1.
  • Minimum special characters: Set the number of special characters ('~!@#$%^&*()_+-=[]|\:";'<>,./) that the password must contain. The default is 1.
Make sure that the sum of the values for the minimum policies above is not greater than 64.​​
  • Maximum unique historical operator passwords: Set the number of passwords that the system remembers for each operator, starting with the most recent, between 0 and 128. The default is 5.
  • Maximum operator password age: Set the maximum number of days before the operator must change the password, between 1 and 128. The default is 30. If the value is set to 0, the password never expires.


A Completely Automated Public Turing test to tell Computers and Humans Apart (CAPTCHA) creates a challenge that is easy enough for a human user to meet, but which is likely to defeat standard automated software. In its most typical form, a CAPTCHA presents an image of numbers and letters, and prompts the user to enter the characters in the image into a field. If the typed characters match the characters in the image, the system proceeds to examine the operator ID and password that the user supplied.

Set the following policies:

  • CAPTCHA implementation: If set to Default, the system presents the CAPTCHA implementation that is included with the Pega® Platform. If set to Custom, the system presents the custom CAPTCHA implementation enabled for this system. An application can use third-party CAPTCHA solutions on the application login screen. However, a certain amount of development work is required to prepare the custom ruleset to deliver the third-party resource.
  • Enable CAPTCHA Reverse Turing test module: If enabled, the system presents the CAPTCHA on authentication failure, with a probability set by the Probability that CAPTCHA will be presented field. If disabled, no CAPTCHA is displayed, even on login failure.
  • Probability that CAPTCHA will be presented: If the CAPTCHA Reverse Turing Test is enabled, the percentage set here is the likelihood that the CAPTCHA is displayed.
  • Enable presentation on first login: If enabled, the CAPTCHA is displayed the first time the user logs in to a new system or from a new computer.

Imposing lockout penalty

You can invoke a time-out penalty if more than a reasonable number of unsuccessful attempts are made during a specified time period. The penalty is a time delay before the next attempt is possible, with the delays increasing after each subsequent failure.

Set the following policies:

  • Enable authentication lockout penalty mechanism: If enabled, after the specified number of login attempts, the system imposes a delay of a specified time (in minutes and seconds) after every unsuccessful login attempt. The delay increases with each subsequent failure.
  • Failed login attempts before employing authentication lockout penalty: Set the number of failed attempts, between 0 and 128, after which the user experiences a delay for each subsequent attempt.
  • Initial authentication lockout penalty: Set the initial delay, in seconds, between 0 and 128.

For example, enable the lockout penalty, set the number of failed login attempts that triggers the penalty to 5, and set the initial penalty to 10. When an automated tool (or a human) tries to log in with a user name and a random password, and fails, the system notes the failure. When the automated tool tries and fails again, the system increments the failure count.

If the automated tool tries five times, the system notes that it has hit the penalty threshold and imposes the initial delay of 10 seconds before the login screen becomes available again.

When the automated tool tries and fails again, the delay increases to 20 seconds (the initial delay of 10 seconds plus the penalty). When the automated tool tries and fails again, the delay increases to 30 seconds (the initial delay, plus the first penalty and the second penalty), and continues in a similar manner.

Account lockout

You can enforce account lockouts after repeated failed attempts by an operator to thwart brute-force attacks. When an account is locked, the Pega Platform does not allow any further login attempts until the account is unlocked. The account can be unlocked manually or automatically based on your preferences.

Activating account lockout policy

To configure your account lockout policy, do the following steps:

  • Set the Enable authentication lockout penalty policy to Disabled status. This step is required because you cannot enforce account lockout and lockout penalty policies at the same time.
  • Set the Failed login attempts before password lockout policy to the maximum number of allowed login attempts. When the number of failed attempts exceeds the number set in this policy, the account is locked.

  • Set the Password lockout duration policy to the time period (in minutes) for which you want the account to remain locked:

    • Set the policy to a non-zero value if you want the account to be unlocked automatically after the specified time is over.

    • Set the policy to zero value if you want the account to be unlocked manually.

While an account is locked, users who try to log in by using a browser authentication challenge or session timeout login page are not notified of the account lockout.

Unlocking an account

You can unlock a blocked account in two ways:

Auto: Use this method to unlock the account automatically after a certain time without resetting the operator's password. You can specify the time period for which the account needs to be locked in the Password lockout duration policy. Until the specified time period expires after the lockout, further attempts are not allowed. After the lockout period expires, users can log in with valid credentials.

Manual: Use this method to unlock the account manually, which requires you to reset the password. To activate this method, set the Password lockout duration policy to zero. To unlock an account manually:

  1. Click Designer Studio > System > Settings > Unlock Operator. The Unlock Operator landing page lists all the blocked accounts.
  2. Click Unblock & Reset to unlock an account. The account is unlocked and the password is reset and displayed on the screen.
  3. Notify the operator of the new password.

Instead of notifying operators every time their account is unblocked, you can automate the notification of new password. To do so, customize the pyUnlockOperatorExtension activity. When you customize this activity, the password is automatically sent to the operator when you click Unblock & Reset.

Additionally, you can customize the message that users see when their password is reset. To do so, customize the pyPasswordResetDetails HTML rule.

Configuring audit log level

The audit log records login attempts. For each logged event, the log captures the following information:

  • Create Date/Time – The time of the attempt
  • Remote IP Address – The IP address of the system from which the attempt was made
  • Remote Host – The name of the computer involved
  • User Name – The operator ID used in the login attempt
  • Message – The status message returned during authentication of the login
  • Browser (User-Agent) – HTTP Request Header "User-Agent"
  • Referrer – HTTP Referrer of the "User-Agent"
  • Via – Records proxies through which the request was sent
  1. Select a level for the audit log level policy:
    • None – No log entry is added
    • Basic – Record failed login attempts only
    • Advanced – Record failed and successful login attempts
  2. Click Display Audit Log to review the log in its own window. The log is displayed as a Report Definition report.

The default time period covered is one month. You can adjust the range by clicking the link to the right of Filters, located above the report. You can edit, save, summarize, print, and export the report from the Actions menu.

Review history of changes to the security policies

Click View History on the Security Policies tab to see a report of changes to security policies. The report lists the changes, who made the change, and when the change took place. You can edit, save, print, and export the report from the Actions menu.

Pega Platform 6.3 SP1 System Architect UI/UX Specialist System Administrator Security
Suggest Edit

90% found this useful

Have a question? Get answers now.

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