Helix Control-M/Agent (SaaS) install can fail due to self-signed certificate in use by proxy of the installed agent machine, as we’ve seen with Cisco Umbrella.
The error details available is log - ctm_ag_saas_cmd.log  which can be found, as seen in the install failure message:
Linux:        More details in ctm_ag_saas_cmd.log under Control-M/Agent proclog directory or after rollback in $HOME/BMCINSTALL/log
Windows: More details in ctm_ag_saas_cmd.log under Control-M/Agent proclog directory or after rollback in %temp%
Error example from log:
0202 08:59:02.748 INFO  main              com.bmc.saas.auth.TokenData         - Retrieving file from: https://static-endpoints.prod.controlm.com
0202 08:59:03.307 ERROR main              com.bmc.saas.auth.TokenData         - Cannot get https://static-endpoints.prod.controlm.com: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
0202 08:59:03.308 DEBUG main              com.bmc.saas.auth.TokenData         - Downloaded https://static-endpoints.prod.controlm.com: null
0202 08:59:03.308 ERROR main              r.OnBoardingUtilSetInstallTokenData - ctm_ag_saas_cmd set Install-Token-data : Failed to extract API-GTW endpoint from token
java.lang.IllegalArgumentException: Endpoint key 'PRDOGS' is not found in https://static-endpoints.prod.controlm.com
                  at com.bmc.saas.auth.TokenData.getEndpointUrl(TokenData.java:48)
                  at com.bmc.ctm.agent.saas.onboardingutils.runoption.OnBoardingUtilSetInstallTokenData.extractInstallTokenData(OnBoardingUtilSetInstallTokenData.java:198)
                  at com.bmc.ctm.agent.saas.onboardingutils.runoption.OnBoardingUtilSetInstallTokenData.run(OnBoardingUtilSetInstallTokenData.java:91)
                  at com.bmc.ctm.agent.saas.onboardingutils.OnBoardingUtilsApp.runRequestedOption(OnBoardingUtilsApp.java:243)
                  at com.bmc.ctm.agent.saas.onboardingutils.OnBoardingUtilsApp.handleRunOption(OnBoardingUtilsApp.java:149)
                  at com.bmc.ctm.agent.saas.onboardingutils.OnBoardingUtilsApp.main(OnBoardingUtilsApp.java:70)
0202 08:59:03.309 ERROR main              c.b.c.a.s.o.OnBoardingUtilsApp      - *** ctm_ag_saas_cmd RUN_OPTION: install-token done with error! The token provided is not valid. Copy the token again and reinstall the agent. If problem repeats, Contact BMC support.
 

Below instructions are relevant for Helix Control-M/Agent v21.080 and higher for which the Agent uses external Java supplied by the customer.
In versions prior to v21.080, the Agent is installed with its internal Java so update of the ‘cacerts’ file requires install with no registration which is more complicated -  instructions in internal KA 000395731.

The ‘cacerts’ file holds the Java Runtime Environment (JRE) trusted certificates which are used for https handshake.
The Agent is not aware of any internally used certificate so it will fail if any “unexpected” certificate is required on https handshake with “PKIX path building failed: … unable to find valid certification path to requested target”.

The solutions is to add to the Agent used Java ‘cacerts’ file the self-signed certificate which is accessible only by the customer so can be done only by the customer.

First, get the self-signed certificate used in pem format to file: ss-cert.crt – see below section ‘Get the self-signed certificate’.

Next, add the self-sign certificate to the Agent used Java ‘cacerts’ file as follows:
File path should be: {BMC_INST_JAVA_HOME}/lib/security/cacerts

cd {BMC_INST_JAVA_HOME}/lib/security/
First backup the original file: cp cacerts cacerts.ORIG

Import the self-sign certificate by running bellow command using java keytool:
{BMC_INST_JAVA_HOME}/bin/keytool -import -trustcacerts -alias ss-proxy -file ss-cert.crt -keystore cacerts
If above fails, try with password:
{BMC_INST_JAVA_HOME}/bin/keytool -deststorepass changeit -import -trustcacerts -alias ss-proxy -file ss-cert.crt -keystore cacerts
Note1: alias name used above for the certificate is ss-proxy, use other alias name if you want to.
Note2: default keystore password is used:  changeit – should work.

Verify above import done ok by dumping the ‘cacerts’ updated certificates list to -  ‘cacert-list.txt’, check ‘ss-proxy’ is included in dump file.
{BMC_INST_JAVA_HOME}/bin/keytool -storepass changeit -list -v -keystore cacerts > cacert-list.txt
Note: run above list command before and after import to different dump files and compare the two – should be different due to the added certificate.

Last, run Agent install again and check if problem resolved.
If installation fails, it is important to send us the ‘ctm_ag_saas_cmd.log’, as detailed in below install error message:
Linux: “More details in ‘ctm_ag_saas_cmd.log‘ under Control-M/Agent proclog directory or after rollback in $HOME/BMCINSTALL/log”
Windows: “More details in ‘ctm_ag_saas_cmd.log‘ under Control-M/Agent proclog directory or after rollback in %temp%”


Get the self-signed certificate

Best is to contact the IT to get the self-signed certificate used by your organization for proxy.

If Cisco Umbrella is used as proxy it uses self-signed certificate which can be retrieved as explained here:
https://docs.umbrella.com/deployment-umbrella/docs/install-cisco-umbrella-root-certificate