Best Practices from Oracle Development's A‑Team

ICS Connectivity Agent Advanced Configuration

Greg Mally
Consulting Solutions Architect

PLEASE NOTE: The following blog pertains to Oracle's Integration Cloud Service (ICS) and NOT Oracle's Integration Cloud (OIC) ...

Oracle's Integration Cloud Service (ICS) provides a feature that helps with the integration challenge of cloud to ground integrations with resources behind a firewall. This feature is called the ICS Connectivity Agent (additional details about the Agent can be found under New Agent Simplifies Cloud to On-premises Integration). The design of the Connectivity Agent is to provide a safe, simple, and quick setup for ICS to on-premise resources. In many cases this installation and configuration is an almost no-brainer activity. However, there are edge cases and network configurations that make this experience a bit more challenging.

We have encountered the following post-installation challenges with the ICS 16.3.5 Connectivity Agent:

1. Networks containing proxy server with SSL and/or Man In The Middle (MITM) proxy
2. On-premise resources requiring SSL
3. nonProxyHost required for on-premise resources
4. White list OMCS and upgrade URIs

It's important to note that future releases of ICS may improve on these configuration challenges. However, some are not related to the product (e.g., network white list) and appropriate actions will need to be coordinated with the on-premise teams (e.g., network administrators).

Import Certificates

One of the more challenging activities with post-configuration of the ICS Connectivity Agent is updating the keystore with Certificates that the agent needs to trust. Since the agent is a lightweight, single server, WebLogic installation, there are no web consoles available to help with the certificate import. However, if you investigate this topic on the internet you will eventually end up with details on using java keytool and WebLogic WLST to accomplish this task. Instead of doing all this research, I am including a set of scripts (bash and WLST) that can be used to expedite the process. The scripts are comprised of 4 files where each file contains a header that provides details on how the script works and its role in the process. Once downloaded, please review these headers to make yourself familiar with what is required and how they work together.

The following is a step-by-step example on using these scripts:

1. Download the scripts archive on the machine where the Connectivity Agent is running
Scripts: master.zip from GitHub (https://github.com/oracle/cloud-asset-ics-agentkeystore-scripts)
2. Extract the scripts archive into a directory. For example:
[oracle@icsagent importToAgent]$ unzip master.zip -d .
Archive: master.zip
creating:  ./cloud-asset-ics-agentkeystore-scripts-master/
inflating: ./cloud-asset-ics-agentkeystore-scripts-master/Readme.md
creating:  ./cloud-asset-ics-agentkeystore-scripts-master/advancedConfigScripts/
inflating: ./cloud-asset-ics-agentkeystore-scripts-master/advancedConfigScripts/createKeystore.sh
inflating: ./cloud-asset-ics-agentkeystore-scripts-master/advancedConfigScripts/importToAgent.py
inflating: ./cloud-asset-ics-agentkeystore-scripts-master/advancedConfigScripts/importToAgent.sh
inflating: ./cloud-asset-ics-agentkeystore-scripts-master/advancedConfigScripts/importToAgentEnv.sh
inflating: ./cloud-asset-ics-agentkeystore-scripts-master/changelog.md
creating:  ./cloud-asset-ics-agentkeystore-scripts-master/credentialScripts/
inflating: ./cloud-asset-ics-agentkeystore-scripts-master/credentialScripts/updateicscredentials.py
inflating: ./cloud-asset-ics-agentkeystore-scripts-master/license
3. Update the importToAgentEnv.sh to reflect your agent environment
4. Create a subdirectory that will be used to hold all the certificates that will need to be imported to the agent keystore:
[oracle@icsagent importToAgent]$ mkdir certificates
5. Download or copy all certificates in the chain to the directory created in the previous step:
[oracle@icsagent importToAgent]$ ls -l certificates/
total 12
-rwxr-x---. 1 oracle oinstall 1900 Nov 1 14:55 intermediate-SymantecClass3SecureServerCA-G4.crt
-rwxr-x---. 1 oracle oinstall 1810 Nov 1 14:55 main-us.oracle.com.crt
-rwxr-x---. 1 oracle oinstall 1760 Nov 1 14:55 root-VeriSignClass3PublicPrimaryCertificationAuthority-G5.crt
  NOTE: You can use your browser to export the certificates if you do not have them available elsewhere. Simply put the secured URL in the browser and then access the certificates from the "lock":


6. Execute the createKeystore.sh:
[oracle@icsagent importToAgent]$ bash createKeystore.sh -cd=./certificates -cp=*.crt
Certificates will be added to ./certificates/agentcerts.jks
Adding certificate intermediate-SymantecClass3SecureServerCA-G4.crt
Certificate was added to keystore
Adding certificate main-us.oracle.com.crt
Certificate was added to keystore
Adding certificate root-VeriSignClass3PublicPrimaryCertificationAuthority-G5.crt
Certificate already exists in system-wide CA keystore under alias
Do you still want to add it to your own keystore? [no]: yes
Certificate was added to keystore
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 3 entries
main-us, Nov 1, 2016, trustedCertEntry,
Certificate fingerprint (SHA1): 9D:61:69:38:4C:54:AC:44:5C:22:90:E1:8F:80:8F:85:43:9E:8D:7C
intermediate-symantecclass3secureserverca-g4, Nov 1, 2016, trustedCertEntry,
Certificate fingerprint (SHA1): FF:67:36:7C:5C:D4:DE:4A:E1:8B:CC:E1:D7:0F:DA:BD:7C:86:61:35
root-verisignclass3publicprimarycertificationauthority-g5, Nov 1, 2016, trustedCertEntry,
Certificate fingerprint (SHA1): 4E:B6:D5:78:49:9B:1C:CF:5F:58:1E:AD:56:BE:3D:9B:67:44:A5:E5
Keystore ready for connectivity agent import: ./certificates/agentcerts.jks

NOTE: This script has created a file called importToAgent.ini that contains details that will be used by the importToAgent.py WLST script. Here's an example of what it looks like:

[oracle@icsagent importToAgent]$ cat importToAgent.ini
appStripe: system
keystoreName: trust
keyAliases: intermediate-SymantecClass3SecureServerCA-G4,main-us,root-VeriSignClass3PublicPrimaryCertificationAuthority-G5
keyPasswords: changeit,changeit,changeit
keystorePassword: changeit
keystorePermission: true
keystoreType: JKS
keystoreFile: ./certificates/agentcerts.jks
7. Make sure your agent server is running and execute the importToAgent.sh:
[oracle@icsagent importToAgent]$ bash importToAgent.sh -au=weblogic -ap=welcome1 -ah=localhost -aport=7001
Initializing WebLogic Scripting Tool (WLST) ...
Welcome to WebLogic Server Administration Scripting Shell
Type help() for help on available commands
Using the following for the importKeyStore:
WebLogic URI = t3://localhost:7001
WebLogic User = weblogic
WebLogic Password = welcome1
appStripe = system
keystoreName = trust
keyAliases = intermediate-SymantecClass3SecureServerCA-G4,main-us,root-VeriSignClass3PublicPrimaryCertificationAuthority-G5
keyPasswords = changeit,changeit,changeit
keystorePassword = changeit
keystorePermission = true
keystoreType = JKS
keystoreFile = ./certificates/agentcerts.jks
Connecting to t3://localhost:7001 with userid weblogic ...
Successfully connected to Admin Server "AdminServer" that belongs to domain "agent-domain".
Warning: An insecure protocol was used to connect to the
server. To ensure on-the-wire security, the SSL port or
Admin port should be used instead.
Location changed to serverRuntime tree. This is a read-only tree with ServerRuntimeMBean as the root.
For more help, use help('serverRuntime')
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root.
For more help, use help('domainRuntime')
Keystore imported. Check the logs if any entry was skipped.

At this point you will have imported the certificates into the keystore of the running Connectivity Agent. I always bounce the agent server to make sure it starts cleanly and everything is picked up fresh.

Update http.nonProxyHost

If your network contains a proxy server, you will want to make sure that any on-premise resource the agent will be connecting to is on the http.nonProxyHosts list.  This way the agent knows to not use the proxy when trying to connect to an on-premise endpoint:


To update this Java option, open the $AGENT_DOMAIN/bin/setDomainEnv.sh and search for nonProxyHosts. Then add the appropriate host names to the list. For example:


export JAVA_PROPERTIES="${JAVA_PROPERTIES} -Dhttp.nonProxyHosts=localhost| -Dweblogic.security.SSL.ignoreHostnameVerification=true -Djavax.net.ssl.trustStoreType=kss -Djavax.net.ssl.trustStore=kss://system/trust"


export JAVA_PROPERTIES="${JAVA_PROPERTIES} -Dhttp.nonProxyHosts=localhost||*.oracle.com -Dweblogic.security.SSL.ignoreHostnameVerification=true -Djavax.net.ssl.trustStoreType=kss -Djavax.net.ssl.trustStore=kss://system/trust"

Once this update has been done, you will need to restart your agent server for the update to be picked up.

Add Agent URIs to Network White List

The Connectivity Agent contains two URIs that it will reach out to. The primary one is Oracle Message Cloud Service (OMCS), which is how ICS communicates to the on-premise agent. The other one is for things like agent upgrades. These two URIs must be added to the network white list or the agent will not be able to receive requests from ICS. The URIs are located in the following Connectivity Agent file:


The contents of this file will look something like the following (with the URIs circled):



Please follow the official on-line documentation for the ICS Connectivity Agent install. If you run into things like handshake errors when the agent starts or attempts to connect to an on-premise resource, the aforementioned will be a good starting point to resolve the issue. This blog most likely does not cover all edge cases, so if you encounter something outside of what is covered here I would like to hear about it.

Join the discussion

Comments ( 1 )
  • Anatoliy Smirnov Wednesday, April 15, 2020
    Hi, thanks for the great article! Any version of he same pertaining to OIC? Will be nice to have a look.
    PS And please ask someone in Oracle to fix the invalid captcha issue, I learned to copy the response before the submit button click, the hard way
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha