SA-14891

Summary

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

Resolution

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, EMAILADDRESS=your_email@your_host.com”
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:

 
conf\tomcat-users.xml
webapps\prweb\WEB-INF\web.xml
 

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.

 <tomcat-users>
<!-- 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=your_email@your_host.com" password="" roles="needcert"/>
<!-- END: Changes for Client-Certificate-Authentication -->
<tomcat-users>​
 

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) -->
<security-constraint>
        <web-resource-collection>
                     <url-pattern>/api/*</url-pattern>
                     <url-pattern>/DiagnosticData</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>needcert</role-name>
        </auth-constraint>
    </security-constraint>
    <login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>certificate</realm-name>
    </login-config>
    <security-role>
        <role-name>needcert</role-name>
    </security-role>
<!-- 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 -->
<!--
                <login-config>
                                <auth-method>BASIC</auth-method>
                                <realm-name>PegaRULES</realm-name>
                </login-config>
-->
<!-- 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:
 
 
<CATALINA_BASE>\conf\logging.properties
 
Add the following loggers:
 
# For debugging CLIENT CERTIFICATION AUTHENTICATION
org.apache.catalina.realm.level = FINEST  
org.apache.catalina.authenticator.level = FINEST