PAM - How to setup custom connector
Article ID: 192532
Updated On:
Products
Issue/Introduction
This is to provide the steps to configure custom connector.
Environment
Release : 3.3.x, 3.4.x, 4.0.x and 4.1.x
Component : PRIVILEGED ACCESS MANAGEMENT
Component: Custom Connector
Resolution
1. Prerequisites
Download the following files.
1. jdk 1.8.0_202 64bit (jdk-8u202-windows-x64.exe) or the latest version of JDK8
2. Apache Tomcat 9.0.35 (apache-tomcat-9.0.35.exe)
3. Custom Connector 3.3.0 (GEN500000000002565.zip) or the version of PAM you are using.
2. Install JDK8 64bit
By default, this gets installed to "C:\Program Files\Java\jdk1.8.0_202"
Set "JAVA_HOME" in System variables
Add "{JDK}\bin" to Path in System variables.
3. Install Tomcat 9.0.35
By default, tomcat installer will detect existing JDK and decide to install either 32bit or 64bit tomcat.
Tomcat is installed with DEFAULT settings. Just click next next until complete.
It is installed to "C:\Program Files\Apache Software Foundation\Tomcat 9.0"
No need to run Tomcat at this point. Just shut it down if it is running.
You may configure the tomcat9 service to start automatically.
!!! DO NOT CONFIGURE CUSTOM CONNECTOR WITH TOMCAT THAT IS ALREADY HOSTING OTHER APPLICATIONS !!!
4. Extract Custom Connector zip file to "C:\customconnector8"
5. Create Tomcat HTTPS Certificate Keystore.
Create a "keystore" folder under "C:\customconnector8".
Open cmd and navigate to "C:\customconnector8\keystore" folder and run the following command.
"keytool -genkey -alias pam -keyalg RSA -keysize 2048 -storetype PKCS12 -dname "CN=capamtcf, OU=PAM, O=CA, L=Burlington, ST=MA, C=US" -keypass keystore_password -storepass keystore_password -keystore C:\customconnector8\keystore\https.jks -validity 360"
This is plain java keytool command to generate a self-signed certificate and store it in this https.jks file.
For easy understanding, I am adhering to the literal password in the documentation, the "keystore_password" is the keystore password which is also the private key passphrase.
You can run the following command to list the content of this keystore.
"keytool -list -keystore https.jks -storepass keystore_password"
Note the entry type is "PrivateKeyEntry" meaning it has a keypair and this will be used by tomcat to allow HTTPS connections.
6. Export certificate from https.jks
At the same cmd at "C:\customconnector8\keystore" folder, run the following command to export the certificate.
"keytool -exportcert -alias pam -keystore https.jks -keypass keystore_password -storepass keystore_password -rfc -file tcf.crt"
You can check the certificate by double clicking on the "tcf.crt" file in that folder.
7. Encrypt the keystore password using configTCF.cmd
In cmd, navigate to "C:\customconnector8\configTCF" folder and run the following command.
"configTCF.cmd -Dcommand=encryptPassword -Dpassword=keystore_password"
"7RLgOeriH7501yVNsAMh7dfwyBtIZ5pbj2kJxftWlaE=" is the encrypted version of "keystore_password".
8. Copy the capamextensionstcfCryptoUtil.jar to "{TOMCAT}\lib" folder.
This jar file is the one handling the encryption and decryption of keystore password.
Without this jar file, tomcat would not be able to open the https.jks to obtain the keypair so you will get an error listening on 8443 port.
9. Update catalina.properties file.
Add the following 2 lines to "C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\catalina.properties"
org.apache.tomcat.util.digester.PROPERTY_SOURCE=com.ca.pam.extensions.tcfcryptoutil.TCFPropertySource
tomcat.keystore.pwd=7RLgOeriH7501yVNsAMh7dfwyBtIZ5pbj2kJxftWlaE=
This encrypted password is from step 7.
10. Update "Connector" setting in server.xml file under "Catalina" Service.
"C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\server.xml" file need to be updated by modifying the existing "Catalina" service section.
FROM:
TO:
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="30000" URIEncoding="UTF-8" address="127.0.0.1" />
11. Add a new Connector to "Catalina" Service.
You only need to replace the "keystoreFile" value to the actual filepath which is "C:\customconnector8\keystore\https.jks"
!!! CHECK POINT!!!
At this point, you should be able to startup tomcat service and catalia.log should show "Catalina" service initialized successfully and 8443 port listening.
There should be no ERROR/SEVERE in the logs at this point.
Until this part is purely deploying a tomcat application server with only a custom jar to encrypt the passphrase to access https.jks keystore for keypair for https.
09-Jun-2020 05:48:50.561 INFO [main] org.apache.catalina.core.StandardService.startInternal Starting service [Catalina]
09-Jun-2020 05:48:50.561 INFO [main] org.apache.catalina.core.StandardEngine.startInternal Starting Servlet engine: [Apache Tomcat/9.0.35]
...
09-Jun-2020 05:48:50.764 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-127.0.0.1-8080"]
09-Jun-2020 05:48:50.764 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["https-jsse-nio-8443"]
Now, following is deploying the sample target connector.
12. Add new "CatalinaTC" Service in server.xml
"C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\server.xml" file need to be updated by adding the following additional "Service" section.
<Service name="CatalinaTC">
<Connector port="18080" protocol="HTTP/1.1" connectionTimeout="30000"
URIEncoding="UTF-8" address="127.0.0.1" />
<!-- Define an AJP 1.3 Connector on port 8009
<Connector port="18009" protocol="AJP/1.3" redirectPort="18443" />
-->
<Engine name="CatalinaTC" defaultHost="targetconnectors">
<Host name="targetconnectors" appBase="webapps_targetconnectors"
unpackWARs="true" autoDeploy="false" deployOnStartup="true">
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
prefix="localhost_access_log" suffix=".txt"
pattern="%h %l %u %t "%r" %s %b" />
</Host>
</Engine>
</Service>
server.xml file has the following structure so you need to this at the right location.
<Server>
<Listener />
<GlobalNamingResources>
<Resource />
</GlobalNamingResources>
<Service name="Catalina>
...
</Service>
<Service name="CatalinaTC>
...
</Service>
</Server>
13. Copy the capamef.war file to "{TOMCAT}\webapps" folder.
Copy "C:\customconnector8\application\capamef.war" file to "C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps".
14. Copy sample TargetConnector war files to "{TOMCAT}\webapps_targetconnectors"
This "webapps_targetconnectors" path is defined in the "CatalinaTC" Service section.
This "webapps_targetconnectors" folder do not exist so you need to create it first.
Copy the 2 war files in "C:\customconnector8\samples" folder to "C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps_targetconnectors"
15. Copy the "tcf.crt" file over to a machine where you launch PAM Client.
This step may not be required if you can logon to PAM GUI from this machine.
16. Logon to PAM GUI and navigate to "Config - Custom Connector"
17. Enter the IP address of your Custom Connector Server and import the "tcf.crt".
18. Click on "GENERATE KEY" and "SAVE".
Your configuration at PAM Server is complete. It only requires step 16, 17 and 18.
!!! DO NOT CLICK ON "CLEAR" BUTTON AS IT WILL WIPE OUT ALL CONFIGURATION !!!
19. Copy and paste the "Encryption Key" into a notepad.
UGRBjynDMLvoas892Pj4dVW/ZHTYPjXt7zYXdel18Vo=
20. Encrypt PAM "Encryption Key" and store it in keystore.
This "Encryption Key" is from step 18. This action is performed at the custom connector server side.
Open cmd and navigate to "C:\customconnector8\configTCF" and run the following command.
"configTCF.cmd -Dcommand=createKeyStore -DkeyStoreFile=C:\customconnector8\keystore\pamkey.jks -DkeyStorePWD=keypwd -Dkey=UGRBjynDMLvoas892Pj4dVW/ZHTYPjXt7zYXdel18Vo="
Again, I am using the same password sample for this keystore password as showin in the documentation which is "keypwd".
!!! DO NOT CONFUSE THIS KEYSTORE WITH HTTPS.JKS AND ITS KEYSTORE PASSWORD !!!
This command creates "pamkey.jks" and set the keystore password as "keypwd". It would then store the PAM "Encryption Key" in it.
It also encrypts the keystore password "keypwd" and returns the encrypted version of it which need to be stored in extension_framework.properties in the next step.
The file is created.
Copy the encrypted password in notepad. ZbF7ARZ68A9WFjjw11rIag==
You can check the content of this keystore using the following command.
"keytool -list -keystore pamkey.jks -storepass keypwd"
And as you can see, there is a SecretKeyEntry with alias "tcfkey". This "tcfkey" is the PAM "Encryption Key".
In case if you generate a new Encryption Key in PAM GUI then you need to perform this again.
21. Store the pamkey.jks keystore password in extension_framework.properties
This extension_framework.properties file is not generated yet so you need to startup tomcat service so the "capamef.war" can be deployed.
And don't worry about the following error in the catalina.log
09-Jun-2020 06:43:58.532 INFO [main] com.ca.pam.extensions.framework.util.ExtensionFrameworkContextListener.contextInitialized Initializing framework context listener.
09-Jun-2020 06:43:58.532 INFO [main] com.ca.pam.extensions.framework.util.PropertiesLoader.loadProperties PropertiesLoader loading properties file: /extension_framework.properties
09-Jun-2020 06:43:58.532 INFO [main] com.ca.pam.extensions.framework.util.PropertiesLoader.loadProperties PropertiesLoader loaded properties successfully
09-Jun-2020 06:43:58.532 INFO [main] com.ca.pam.extensions.framework.util.ExtensionEncryption.init Encryption is enabled
09-Jun-2020 06:43:58.547 INFO [main] com.ca.pam.extensions.framework.util.ExtensionEncryption.retrieveEncryptionKey Retrieve the encryption key
09-Jun-2020 06:43:58.547 SEVERE [main] com.ca.pam.extensions.framework.util.ExtensionEncryption.init Encryption Key does not exist
You will now find the "C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\capamef\WEB-INF\classes" folder created and you will find the "extension_framework.properties" file.
Update the "extension_framework.properties" file as below.
extension.encryption.pwd=ZbF7ARZ68A9WFjjw11rIag==
extension.keystore.file=C:\\customconnector8\\keystore\\pamkey.jks
The "extention.encryption.pwd" value is the encrypted version of "keypwd" which was generated in step 20.
For clarification, you can run the following command to confirm.
For "extension.keystore.file" should have double backslash instead of one in its FULL FILEPATH!
Do not use relative filepath.
This "extension_framework.properties" tells custom connector where is the keystore containing the PAM "Encryption Key" and the password to access it.
If you somehow mess these 2 parts(encryption.pwd and keystore.file), the "TEST" button at the PAM GUI will fail and PAM catalina.out in FINE mode would show HTTP 401.
22. TESTING
"extension_framework.properties" has wrong encrypted password or filepath is invalid. PAM performs "TEST"
Custom connector catalina.log would report the following.
09-Jun-2020 07:08:42.214 SEVERE [https-jsse-nio-8443-exec-7] com.ca.pam.extensions.framework.util.ExtensionEncryption.decryptKeyStorePassword [e6afe6af-b7c8-42d5-9957-81ea4f7f4c07] [PAMTargetConnector] Error decrypting password: Last unit does not have enough valid bits
09-Jun-2020 07:08:42.293 SEVERE [https-jsse-nio-8443-exec-7] com.ca.pam.extensions.framework.util.ExtensionAuthenticationFilter.validateAuthToken [e6afe6af-b7c8-42d5-9957-81ea4f7f4c07] [PAMTargetConnector] Authorization header cannot be decrypted:
org.jose4j.lang.InvalidKeyException: The key must not be null.
at org.jose4j.jwx.KeyValidationSupport.notNull(KeyValidationSupport.java:72)
at org.jose4j.jwx.KeyValidationSupport.validateAesWrappingKey(KeyValidationSupport.java:86)
at org.jose4j.jwe.AesKeyWrapManagementAlgorithm.validateKey(AesKeyWrapManagementAlgorithm.java:60)
at org.jose4j.jwe.AesKeyWrapManagementAlgorithm.validateDecryptionKey(AesKeyWrapManagementAlgorithm.java:55)
at com.ca.pam.extensions.framework.util.TcfJsonWebEncryption.decrypt(TcfJsonWebEncryption.java:187)
Using browser to test.
You can use a browser to access "https://172.17.1.21:8443/capamef/targetConnectors/test" where 172.17.1.21 is the custom connector and you will get certificate error and eventually an HTTP 401 and this is normal.
It is because no Authorization header was submitted from your browser.
Custom connector catalina.log would report the following.
09-Jun-2020 07:08:02.011 SEVERE [https-jsse-nio-8443-exec-1] com.ca.pam.extensions.framework.util.ExtensionAuthenticationFilter.validateAuthToken [PAMTargetConnector] Authorization header cannot be empty.
09-Jun-2020 07:08:02.011 SEVERE [https-jsse-nio-8443-exec-1] com.ca.pam.extensions.framework.util.ExtensionAuthenticationFilter.doFilter Failed to validate token for test endpoint.
Test when everything is configured correctly.
The "TEST" button will generate a sample data and POST it to the above URL and the response should be HTTP 200.
And custom connector catalina.log should report the following.
09-Jun-2020 07:14:53.809 INFO [https-jsse-nio-8443-exec-6] com.ca.pam.extensions.framework.util.ExtensionEncryption.retrieveEncryptionKey Retrieve the encryption key
09-Jun-2020 07:14:53.903 INFO [https-jsse-nio-8443-exec-6] com.ca.pam.extensions.framework.api.TargetConnectors.testTargetConnector Encrypted payload is: DO0xlI5ZR10qr9Qxuhz7H/ziUPks8yCNO5qC1LIJxBIB98OMuC6k7xrUzIbecXamZJYgs9ymGDE/VnKs1fSyuSJohuhFfMdA6u7VeYYa
09-Jun-2020 07:14:53.903 INFO [https-jsse-nio-8443-exec-6] com.ca.pam.extensions.framework.api.TargetConnectors.testTargetConnector Decrypted json payload is: {"name":"connectorframeworkTest","version":"1.0"}
Additional Information
Feedback
