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: importToAgent.tar |
| 2. | Extract the scripts archive into a directory. For example: |
[oracle@icsagent importToAgent]$ tar xvf importToAgent.tar.gz createKeystore.sh importToAgentEnv.sh importToAgent.sh importToAgent.py
| 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 [ImportKeyStore] 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:
Before
export JAVA_PROPERTIES=”${JAVA_PROPERTIES} -Dhttp.nonProxyHosts=localhost|127.0.0.1 -Dweblogic.security.SSL.ignoreHostnameVerification=true -Djavax.net.ssl.trustStoreType=kss -Djavax.net.ssl.trustStore=kss://system/trust”
After
export JAVA_PROPERTIES=”${JAVA_PROPERTIES} -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.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:
$AGENT_DOMAIN/agent/config/CpiAgent.properties
The contents of this file will look something like the following (with the URIs circled):
Summary
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.
All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission