Mutual SSL in Service REST.
Hi,
We exposed a REST Service for our upstream systems. We need to know how to configure mutual SSL authentication in our Service REST rule.
we tried with the enabling the Authentication Type as "Basic" and enabled the "Use TLS/SSL (REST only)" but it seems to be not working. Please advise on this and let us know how mutual SSLworks with Service Rest.
Thanks.
Accepted Solution
Pegasystems Inc.
GB
Posting the resolution of the SR here for reference.
RESOLUTION
The following suggestion was made after having been tested in-house by GCS.
Note there are at least two known side-effects to implementing this procedure:
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 already 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.
PROCEDURE:
For this example:
Posting the resolution of the SR here for reference.
RESOLUTION
The following suggestion was made after having been tested in-house by GCS.
Note there are at least two known side-effects to implementing this procedure:
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 already 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.
PROCEDURE:
For this example:
- Our CLIENT CERTIFICATE has the ‘Subject’ of “CN=JoeBloggs, OU=gcs, O=pega, L=reading, ST=berkshire, C=UK, [email protected]”
- Our REST SERVICE has the URL Pattern of ‘/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.
- Stop Tomcat.
- Backup the following files in the <CATALINA_BASE> directory:
conf\tomcat-users.xml
webapps\prweb\WEB-INF\web.xml
- In the ‘tomcat-users.xml’, add the following two lines (highlighted) 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, [email protected]" password="" roles="needcert"/>
<!-- END: Changes for Client-Certificate-Authentication -->
<tomcat-users>
- 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 authenticaiton
will function, but the designer desktop may not function properly
-->
And immediately after that comment, add in 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 -->
We also need to COMMENT out this 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 -->
- Restart Tomcat.
- Log into PRPC DEVELOPER CONSOLE
- Locate your SERVICE RULE.
- Ensure the ‘Requires authentication’ checkbox is NOT checked.
For debugging the authentication process: the following file can be edited:
<CATALINA_BASE>\conf\logging.properties
To add in the following LOGGERS:
# For debugging CLIENT CERTIFICATION AUTHENTICATION
org.apache.catalina.realm.level = FINEST
org.apache.catalina.authenticator.level = FINEST
Pegasystems Inc.
US
Hi,
Have you already followed this: https://docs-previous.pega.com/best-practices-securing-rest-and-soap-connectors and the associated links? What app server are you using?
Pegasystems Inc.
US
Please share the details here in this post. If we decide your issue needs in-depth investigation, then a SR should be created and follow the normal SR process.
Updated: 21 Sep 2015 11:01 EDT
Pegasystems Inc.
US
Here are the suspect:
2015-09-21 04:16:05,724 [tp-bio-8443-exec-201] [TABTHREAD1] [ ] [ Eden:01.01.01] (pages.DeclarativePageUtilsImpl) WARN <private ip> sArumugam - Required parameter'ProfileName' for data page 'D_AuthenticationProfileRecord' cannot be blank.
2015-09-21 04:16:09,426 [tp-bio-8443-exec-193] [TABTHREAD1] [ ] [ Eden:01.01.01] ( connect.rest.RESTClient) ERROR <private ip> sArumugam - javax.net.ssl.SSLPeerUnverifiedException: peer not authenticated
2015-09-21 04:16:09,426 [tp-bio-8443-exec-193] [TABTHREAD1] [ ] [ Eden:01.01.01] ( connect.rest.RESTClient) ERROR <private ip> sArumugam - com.pega.pegarules.pub.services.ConnectorException: Problem invoking REST client
Can you share your auth profile def and also turn on the debug on package: com.pega.pegarules.integration.engine.internal.client.rest?
I have seen folks confusing 1-Way for 2-Way SSL(mutual auth), can you confirm if the server hosting REST service has "Client Authentication" set to required?
Two-way authentication requires a truststore and a keystore on both the client and the server. In this example (below image), CA certificate "A" exists in the truststore and a CA certificate "B" in the keystore of the client. CA certificate "B" exists in the truststore and a CA certificate "A" in the keystore of the server.
The client sends a request to the SSL server(REST Endpoint). The SSL server(REST Endpoint) sends Certificate A from the keystore to the client. The client validates Certificate A against the certificates that are contained in the truststore.
If the certificate is found in the truststore, the client accepts communication from the SSL server(REST Endpoint). The server sends an authentication request to the client(Pega). The client(Pega) then sends Certificate B from the keystore to the SSL server(REST Endpoint). The server validates Certificate B against the certificates that are contained in the truststore. If the certificate is found in the truststore, the server accepts communication from the client.
I have seen folks confusing 1-Way for 2-Way SSL(mutual auth), can you confirm if the server hosting REST service has "Client Authentication" set to required?
Two-way authentication requires a truststore and a keystore on both the client and the server. In this example (below image), CA certificate "A" exists in the truststore and a CA certificate "B" in the keystore of the client. CA certificate "B" exists in the truststore and a CA certificate "A" in the keystore of the server.
The client sends a request to the SSL server(REST Endpoint). The SSL server(REST Endpoint) sends Certificate A from the keystore to the client. The client validates Certificate A against the certificates that are contained in the truststore.
If the certificate is found in the truststore, the client accepts communication from the SSL server(REST Endpoint). The server sends an authentication request to the client(Pega). The client(Pega) then sends Certificate B from the keystore to the SSL server(REST Endpoint). The server validates Certificate B against the certificates that are contained in the truststore. If the certificate is found in the truststore, the server accepts communication from the client.
Also you may want to check the SSL protocol your REST endpoint is running on:
https://community.pega.com/support/support-articles/restful-services-fail-sslpeerunverifiedexception
Lloyds Banking Group
GB
Aditya,
Thanks for the helpful information, to give more information we are exposing the REST service form Pega, and when the client system tries to access our Pega REST Service they are getting
HTTP/1.1 401 Unauthorized exception.
Note : we already completed the exercise of installing SSL certificates at both Client/Server side. But we are not sure how to enable the Authentication(for mutual ssl) at Service Package level.
Aah make it clear, as per Kevin's note please add DEBUG to "com.pega.pegarules.integration.engine.internal.client.rest" package and share the logs. Also provide screen capture of authentication profile. You may also want to open a SR for this?
Lloyds Banking Group
GB
Can you please tell how to add DEBUG to "com.pega.pegarules.integration.engine.internal.client.rest" package ?. we are not using any authentication profile we were just trying with random options and would have got that exception.
Pegasystems Inc.
US
If an SR is raised, please make sure to note its ID in this discussion so we can track it (though I'd be fascinated to see if an issue of this complexity can be resolved in the PSC).
One thing of note, for any log files/screenshots attached, make sure to remove/blur out any references to things like ip addresses and customer information. For the most part, attaching this information with sensitive details scrubbed out is completely legitimate as that info often doesn't pertain to the issue being discussed.
Thanks.
B.
Cognizant Technology Solutions
US
Hi Brendan,
I'm Sathish (Silp's colleague). We have created a SR-A8816, here is the reply I got from the support engineer,
********************************
Hi Brendan,
I'm Sathish (Silp's colleague). We have created a SR-A8816, here is the reply I got from the support engineer,
********************************
Hello
You have asked how to prevent the calling application to access a REST
service without the private key/certificate
I have reviewed the information you provided in SR-A8816. This request falls
outside the scope of work supported by GCS. Questions about how to
design, develop, or debug custom applications and similar types of questions
are best addressed by posing a question to the (*NEW*) Product Support
Community.
The Product Support Community is a place where Pegasystems architects,
developers, and administrators may pose questions and interact with one another
in a dynamic community. It is a great place to seek solutions to problems, and
to share ideas. To access the Product Support Community please use this link: https://mesh.pega.com/community/pegaproductsupport
If you would rather have direct consulting assistance with your question I can
reach out to the Pega Consulting practice on your behalf. Please let me know if
you would prefer this option.
I will proceed with closing this SR based on the information I have provided.
******************************************
Thanks,
Sathish
Cognizant Technology Solutions
US
We have both Connect-REST and Service-REST for this implementation.
In Connect-REST we have an option to configure the Key store in the "Security settings" where we are passing the private key & certificate to the target application. The similar way target application is calling us, but the problem is our REST service is hosted in the public Pega cloud and anybody can hit this service now.
In the Service-REST/Service package there is no OOTB option to stop anybody coming in to our application without the specific private key & certificate. There is a provision in the Service-SOAP, its not available for REST.
Thanks,
Sathish
Updated: 21 Sep 2015 13:39 EDT
In your Service Package rule that belongs to your Service-REST, you must select TLS/SSL option and select "Requires Authentication" check box. When selected, all invocations of REST services belonging to this service package must use TLS/SSL, that is, using the https protocol.
Cognizant Technology Solutions
US
We did that, but the problem is when the target system calling the Pega REST service, its being challenged by "basic" authentication instead of Certificate. The expectation is it should validate the client certificate provided by the calling application and verify the authentication using the SSL setup in place.
There is NO option to just select the "Use TLS/SSL (REST) only", it comes by default with "Basic" auth.
Thanks,
Sathish
Cognizant Technology Solutions
US
There has to be a way where we need to refer a "Key store/Trust store" contains the calling application's public key/certificate to validate the REST call by the calling application. I see that is the configuration is missing, which technically bridges the calling application and Pega application server to validate mutual SSL call. But I do not know where to provide that configuration.
Thanks,
Sathish
Hi Team,
I tried to setup SSL for REST service on Tomcat and these are the 3 steps i performed:
(1) create the keystore (Self signed):
keytool -genkeypair -validity 1825 -alias siroaw7 -keyalg RSA -keystore C:\SSL\keystorefile -storepass changeit -dname "CN=siroaw7.rpega.com, OU=Engineering, O=Pegasystems, L=Cambridge, ST=MA, C=US, [email protected]"
(2) configure Tomcat for SSL:
Export the certificate (optional step).
keytool -exportcert -rfc -alias siroaw7 -file C:\SSL\siroaw7.crt -keystore C:\SSL\keystorefile -storepass changeit
Configure Tomcat for SSL by uncommenting and modifying the SSL connector in server.xml (clientAuth is set to false, this is 1-way SSL):
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
keystoreFile="C:/SSL/keystorefile" keystorePass="changeit"
clientAuth="false" sslProtocol="TLS" />
(3) Configure the REST service for TLS/SSL:
Update the REST Service by selecting the “Use TLS/SSL (REST only)” check box in the Service Package
Hi Team,
I tried to setup SSL for REST service on Tomcat and these are the 3 steps i performed:
(1) create the keystore (Self signed):
keytool -genkeypair -validity 1825 -alias siroaw7 -keyalg RSA -keystore C:\SSL\keystorefile -storepass changeit -dname "CN=siroaw7.rpega.com, OU=Engineering, O=Pegasystems, L=Cambridge, ST=MA, C=US, [email protected]"
(2) configure Tomcat for SSL:
Export the certificate (optional step).
keytool -exportcert -rfc -alias siroaw7 -file C:\SSL\siroaw7.crt -keystore C:\SSL\keystorefile -storepass changeit
Configure Tomcat for SSL by uncommenting and modifying the SSL connector in server.xml (clientAuth is set to false, this is 1-way SSL):
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
keystoreFile="C:/SSL/keystorefile" keystorePass="changeit"
clientAuth="false" sslProtocol="TLS" />
(3) Configure the REST service for TLS/SSL:
Update the REST Service by selecting the “Use TLS/SSL (REST only)” check box in the Service Package
Add the new REST Service endpoint in SOAPUI
Cognizant Technology Solutions
US
Step 1 was done by Pega cloud support.
Step 2: Here is our server.xml entries for the configuration,
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
keystoreFile="conf/.tomcatSSL" keystorePass="SmartPaaSTomcat"
clientAuth="false" sslProtocol="TLS" />
Step 3: we have the same configurations enables, except the context value set as "stateless".
Pegasystems Inc.
CA
Sathish, I see clientAuth set to false in your server.xml. Is this on your REST client side or on Pega REST service side?
Pegasystems Inc.
US
Sathish,
Thanks for sharing the details of this. While we are getting a good handle on the process of referring people to use the community from an SR, we are still working on improving the process of SRs raised after having been discussed in the community first.
I've suspected this could happen, but until now, did not have any documented evidence.
With your feedback, we'll continue to iterate and improve on this particular aspect of the community experience.
Adi - Thanks for ensure the SR continued on the right path.
Thanks.
B.
Accepted Solution
Pegasystems Inc.
GB
Posting the resolution of the SR here for reference.
RESOLUTION
The following suggestion was made after having been tested in-house by GCS.
Note there are at least two known side-effects to implementing this procedure:
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 already 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.
PROCEDURE:
For this example:
Posting the resolution of the SR here for reference.
RESOLUTION
The following suggestion was made after having been tested in-house by GCS.
Note there are at least two known side-effects to implementing this procedure:
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 already 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.
PROCEDURE:
For this example:
- Our CLIENT CERTIFICATE has the ‘Subject’ of “CN=JoeBloggs, OU=gcs, O=pega, L=reading, ST=berkshire, C=UK, [email protected]”
- Our REST SERVICE has the URL Pattern of ‘/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.
- Stop Tomcat.
- Backup the following files in the <CATALINA_BASE> directory:
conf\tomcat-users.xml
webapps\prweb\WEB-INF\web.xml
- In the ‘tomcat-users.xml’, add the following two lines (highlighted) 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, [email protected]" password="" roles="needcert"/>
<!-- END: Changes for Client-Certificate-Authentication -->
<tomcat-users>
- 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 authenticaiton
will function, but the designer desktop may not function properly
-->
And immediately after that comment, add in 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 -->
We also need to COMMENT out this 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 -->
- Restart Tomcat.
- Log into PRPC DEVELOPER CONSOLE
- Locate your SERVICE RULE.
- Ensure the ‘Requires authentication’ checkbox is NOT checked.
For debugging the authentication process: the following file can be edited:
<CATALINA_BASE>\conf\logging.properties
To add in the following LOGGERS:
# For debugging CLIENT CERTIFICATION AUTHENTICATION
org.apache.catalina.realm.level = FINEST
org.apache.catalina.authenticator.level = FINEST