Skip to main content

This content has been archived and is no longer being updated. Links may not function; however, this content may be relevant to outdated versions of the product.

Support Article

Securing Rest Service using Client-Certificate



A Rest service is configured within PRPC. The requirement is to secure this service using client-certificates.
Tomcat is used as the Application Server.


PRPC provides two options for securing Rest Service endpoints: Basic Authentication and Custom Authentication.
There is no out-of-the-box mechanism to allow client-Certificate Authentication.

NOTE: there are at least two known side-effects to implementing this procedure, they are:

1. The Rest Service will not longer be available over HTTP. 
2. Some aspects of PRSYSMGMT (SMA) will stop working (download of logs from PRPC for instance): this can be corrected by loading the client certificate into the browser's keystore.

The following procedure assumes that the trust store of the JVM, where PRPC is running, has the certificate loaded (if using a self-signed certificate) or that the certificate is signed by a well-known 'Certificate Authority' which is already trusted by the JVM.
  1. Client certificate has the ‘Subject’, “CN=JoeBloggs, OU=gcs, O=pega, L=reading, ST=berkshire, C=UK,
  2. Rest service has the URL Pattern, ‘/api/*’ (which matches the OOTB ‘Pega API’ Rest Service). Change this for the specific Rest Service that requires securing.
This should be replaced with the ‘Subject’ of the Client Certificate(s) you wish to authenticate.
  1. Stop Tomcat.
  2. Backup the following files in the <CATALINA_BASE> directory:
  1. In ‘tomcat-users.xml’, add the following two lines into the main ‘tomcat-users’ section, remember to replace the ‘CN=….’ with the data from the Client Certificate.
<!-- START: Changes to allow Tomcat Client-Certificate-Authentication -->
<role rolename="needcert"/>
<user username="CN=JoeBloggs, OU=gcs, O=pega, L=reading, ST=berkshire, C=UK, EMAILADDRESS=" password="" roles="needcert"/>
<!-- END: Changes for Client-Certificate-Authentication -->

  1. In the ‘web.xml’ for the ‘prweb’ application, locate the existing comment in the file:
           Web Container Authentication
           PegaRULES should only be used with Basic HTTP authentication. Form-based authentication
           will function, but the designer desktop may not function properly
Add the following:

<!-- START: Changes to allow Tomcat Client-Certificate-Authentication -->
<!-- Secure the following URLs: to ensure they will require a CLIENT CERTIFICATE (note: to complete this task, Authentication needs to be switched off in any REST SERVICE) -->
<!-- END: Changes to allow Tomcat Client-Certificate-Authentication -->


Comment-out the below section:
<!-- START: Changes to allow Tomcat Client-Certificate-Authentication -->
<!-- We need to disable 'login-config' - only allowed one occurence of 'login-config' is allowed in the configuration -->
<!-- END: Changes to allow Tomcat Client-Certificate-Authentication -->

  1. Restart Tomcat.
  2. Log in to PRPC Developer studio.
  3. Locate your service rule.
  4. Ensure the ‘Requires authentication’ checkbox is not checked.

For debugging the authentication process, the following file can be edited:
Add the following loggers:
org.apache.catalina.realm.level = FINEST  
org.apache.catalina.authenticator.level = FINEST 


Published January 31, 2016 - Updated October 8, 2020

Was this useful?

0% found this useful

Have a question? Get answers now.

Visit the Collaboration 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.

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