This is to provide the steps to configure custom connector.
Release : 3.3.x, 3.4.x, 4.0.x and 4.1.x
Component : PRIVILEGED ACCESS MANAGEMENT
Component: Custom Connector
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.
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.
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 !!!
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.
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.
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".
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.
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.
"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" />
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.
"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>
Copy "C:\customconnector8\application\capamef.war" file to "C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps".
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"
This step may not be required if you can logon to PAM GUI from this machine.
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 !!!
UGRBjynDMLvoas892Pj4dVW/ZHTYPjXt7zYXdel18Vo=
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.
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.
"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"}