Download and Run the Connectivity Agent Installer

Create an Agent Group

You must create an agent group in Oracle Integration before you can run the connectivity agent installer. Creating the agent group automatically creates an OAuth client application in Oracle Identity Cloud Service. This enables the connectivity agent to use OAuth 2.0 token-based authentication when invoking Oracle Integration endpoints. Basic authentication is not supported in Oracle Integration 3. Up to two connectivity agents can be associated with an agent group. For a single Oracle Integration instance, you can create up to five agent groups.

What to Know About OAuth 2.0 Token-Based Authentication Support

OAuth 2.0 token-based authentication is more secure and Oracle Integration 3 connectivity agent configuration is simpler than in Oracle Integration Generation 2.

However, be aware of the following:

You must allow egress from the agent network to Oracle Integration design-time and runtime and the Oracle Identity Cloud Service or identity domain.
The Service Gateway on the Oracle VCN provides access to Oracle Integration, Oracle Identity Cloud Service, and identity domains in the same region as the connectivity agent. See Access to Oracle Services: Service Gateway.
The Service Gateway on the Oracle VCN does not provide access to Oracle Integration, Oracle Identity Cloud Service, and identity domains in a different region than the connectivity agent; this type of access requires the NAT Gateway. See NAT Gateway.

Create an Agent Group

Creating the agent group also creates the necessary artifacts required for message exchange. You can edit the connection name after creation.

In the navigation pane, click Design, then Agents.
Click Create.

The Create agent group panel opens.

Enter the following information, then click Create.

Field Description

Field	Description
Name	Provide a meaningful name so that others can understand the agent name. The name must be unique among all agent names in the system. The name can consist of the following: Letters (A-Z, a-z) Numbers (0-9) Spaces ( ) Special characters ( _ - ) The name must not begin or end with a space and cannot be longer than 50 characters.
Identifier	Accept the default identifier value or change it, if necessary. The identifier is initially the same as the agent group name you provided, but in upper case. When you install the agent, the identifier value is automatically included in the `InstallerProfile.cfg` file. Note: After creating the agent group, you cannot edit the agent group identifier. Instead, you must delete and recreate another agent group to associate with a different agent group identifier.
Description	Provide a meaningful description so that others can understand the responsibilities of the agent group.

Name

Provide a meaningful name so that others can understand the agent name. The name must be unique among all agent names in the system. The name can consist of the following:

Letters (A-Z, a-z)
Numbers (0-9)
Spaces ( )
Special characters ( _ - )

The name must not begin or end with a space and cannot be longer than 50 characters.

Identifier

Accept the default identifier value or change it, if necessary. The identifier is initially the same as the agent group name you provided, but in upper case. When you install the agent, the identifier value is automatically included in the InstallerProfile.cfg file.

Note: After creating the agent group, you cannot edit the agent group identifier. Instead, you must delete and recreate another agent group to associate with a different agent group identifier.

Description

Provide a meaningful description so that others can understand the responsibilities of the agent group.

This action automatically creates an OAuth client application in Oracle Identity Cloud Service. The application name takes the following form:

agent_group_name-instance_IDCS_name

This enables the connectivity agent to use OAuth 2.0 token-based authentication when invoking endpoints. In Oracle Integration 3, each agent group has its own OAuth client application.

System Requirements

Satisfy the following system requirements before installing the on-premises connectivity agent.

Connectivity Agent Prerequisites

Allowlist the Oracle Integration runtime and design-time IP addresses and the Oracle Identity Cloud Service IP address to install the connectivity agent.
Install and use JDK version 17.

You do not need to purchase a JDK license. See JDK license and support for OIC Connectivity Agent (Doc ID 2611142.1).

The JDK installation can be shared with other products installed on the same host. However, ensure that the JDK installation is not modified for use with these other products.
Install the connectivity agent on one of the following certified operating systems:
- Oracle Linux 6.x
- Oracle Linux 7.x
- Oracle Linux 8.x
- RedHat Enterprise Linux 6.6
- RedHat Enterprise Linux 7.x
- RedHat Enterprise Linux 8.x
- Suse Linux Enterprise Edition 12 SP2
- Windows Standard Edition 2016
- Windows 2019
Note:
- The connectivity agent is not certified on Kubernetes (K8s).
- IBM or Open JDK are not supported.
Provide a minimum of 8 GB memory with 4 GB of heap size dedicated for the connectivity agent JVM. If you want to include any other processes on that host besides the on-premises agent, it is strongly recommended that you increase physical memory to a value greater than 8 GB.

Ensure the Connectivity Agent Version is Compatible with JDK 17

Run the following command from the agenthome directory to determine if the connectivity agent is compatible with JDK 17. The following minimum version on Oracle Integration 3 is required for JDK 17 compatibility.

$ cat version
20230613.0926.318

If you receive the following error when starting the connectivity agent after upgrading to JDK 17, you are not running a compatible version of the connectivity agent:

Agent is only supported on Java version 8 or 11. Please set JAVA_HOME and PATH to the location
for Java (JDK 8 or 11). This error occurs because you are using an older version of the connectivity agent.

You may be running an older version of the connectivity agent for the following reasons:

Previous attempts to upgrade the connectivity agent failed
You started the agent with the following option:
```
-DenableAutoUpgrade=false
```

To resolve this issue:

Start the connectivity agent once with your previous JDK version (JDK 8 or JDK 11).
Wait for the connectivity agent upgrade to finish. You can monitor upgrade in the agenthome/logs/agent-upgrade.log file.
Stop the connectivity agent.
Restart the connectivity agent with JDK 17.

Upgrade the Existing JDK 11 Agent to the JDK 17 Agent

If you need to upgrade from JDK 11, perform the following steps.

Install JDK 17.
Stop the existing connectivity agent.
Set JAVA_HOME and PATH to JDK17.
Restart the connectivity agent.

Connectivity Agent Restrictions

Note the following connectivity agent restrictions.

When the Oracle WebLogic JMS Adapter is used with a version of Oracle WebLogic Server prior to 12.2.1.4, JDK 11 and JDK 17 are not supported. To know your version of Oracle WebLogic Server, perform the following steps:
1. Enter the Oracle WebLogic Server URL. For example:
```
http://abcweblogic.oracle.com:7001/console
```
2. At the bottom left, find the version. For example:
```
WebLogic Server Version: 12.2.1.4.0
```
When installed on a Windows host, the connectivity agent does not work with a proxy using NT LAN Manager (NTLM) authentication.

Agent Download and Installation

The agent must be downloaded and installed on your local host. If needed, you can also install a security certificate on your local host. If necessary, you can also run the agent installer as a background process.

Download and Install the Agent

Download the connectivity agent installer to install the agent in your local environment. During installation, you associate the connectivity agent with the agent group identifier you generated when creating an agent group in Oracle Integration. Ensure that you restrict access to the folder in which you install the connectivity agent to only those users who need to stop and start the agent.

Note:

You must have the Java execute permission to install and restart the agent.
You must have the ServiceAdministrator role to download the agent.
See What Users Can Do in the Integrations Design Section by Role of Provisioning and Administering Oracle Integration 3.

Create a directory for connectivity agent installation on your on-premises host.
Note:
- Do not install the agent in a directory path that includes /tmp.
  The agent must never be installed in /tmp. Per the Filesystem Hierarchy Standard version 3.0, /tmp is meant for temporary files. Even though the install and agent work, it is not a recommended location for agent installation because the directory in /tmp may be deleted after the reboot of the system or agent virtual machine.
- Agent installation is not supported with use of an SSL proxy.
In the navigation pane, click Design, then Agents.
Click Download, then Connectivity Agent.
Download the connectivity agent installer to a directory on your on-premises host.
Extract oic_conn_agent_installer.zip.
If you need to add any third party JARs (for example, for the Siebel Adapter or MySQL Adapter), copy them under the agenthome/thirdparty/lib directory.

Note:
If you perform this step after installing the connectivity agent, you must restart the agent. See Restart the Connectivity Agent.
Hover over the agent group.
Click Actions , then select Download config.
This step downloads a preconfigured InstallerProfile.cfg file to use during installation. The following message is displayed.
```
BootStrap configuration downloaded for Agent Group agent_group_name. 
Replace the file in agent install location before proceeding with agent setup.
```
Replace the existing InstallerProfile.cfg template file in the oic_conn_agent_installer directory that was created when you extracted the agent installation file in Step 5 with the preconfigured InstallerProfile.cfg file you downloaded in Step 7.
The preconfigured InstallerProfile.cfg file automatically includes values for all required parameters such as oic_URL and agent_GROUP_IDENTIFIER and OAuth 2.0 token-based authentication parameters such as client ID, client secret, and scope. This eliminates the need to manually specify values for these parameters.
1. Optionally set proxy parameter values. These parameters are only required if the connectivity agent is used with a proxy in the on-premises environment.
2. If you have multiple hosts that must be configured in a nonproxy host environment, you must separate each IP address or host with a pipe symbol (|) in the proxy_NON_PROXY_HOSTS parameter. For example:
```
proxy_NON_PROXY_HOSTS=localhost|127.0.0.1|*.myorg.com
```
3. If you use a proxy user for Windows, the user name must include the MS domain name in front of the user name, along with double backslashes before the user name (for example, MS_domain\\username). If you do not specify the double backslashes, you receive a 407 Proxy Authentication Required error.
Set the JAVA_HOME property to the location of the JDK installation.
Set the PATH property. For example, if csh is your shell:
```
setenv PATH = $JAVA_HOME/bin:$PATH
```
Run the connectivity agent installer from the command prompt. If you want to copy and paste this command, ensure that it does not have any special characters.
```
java –jar connectivityagent.jar
```
Wait for a successful installation message to appear.
```
Done with Agent installation & configuration... Starting agent for message processing.
Agent started successfully... listening for new messages... 
```
The agent group associated with this connectivity agent now has its own InstallerProfile.cfg file and OAuth client application in Oracle Identity Cloud Service. If you delete the agent group, the OAuth client application is also deleted in Oracle Identity Cloud Service.

If errors occur, review the agent diagnostic logs.

See Monitor Agents.
Depending on your agent environment, you may also need to install a certificate.

See Install a Certificate on the Agent Host.

Install a Certificate on the Agent Host

If you need to add a certificate on the agent host, use the keytool to import the certificate in keystore.p12. Installing the certificate enables you to access hosts with self-signed certificates. A certificate is not typically needed.

Note:

If you install a certificate after installing the connectivity agent, you must restart the agent.

See Restart the Connectivity Agent.

Scenarios under which you need to import the certificate in the agent keystore are as follows:

The connectivity agent is used with an SSL proxy.
The connectivity agent is used to invoke secure (SSL) on-premises endpoints.

Go to the agenthome/agent/cert/ directory (keystore.p12 is available here).
Run the following command:
```
keytool -importcert -keystore keystore.p12 -storepass password -alias alias_name -noprompt -file certificate_file -trustcacerts
```
Where:
- -storepass password: The default, initial password for the agent keystore. Refer to your keytool documentation for the default storepass password. See keytool.
- -alias alias_name: Any name to uniquely identify the imported certificate in the keystore.
- -file certificate_file: Absolute path of the certificate file.

Run the Connectivity Agent Installer as a Background Process on Linux Systems

When you run the connectivity agent installer (using java -jar connectivityagent.jar), the process is tied to the terminal window in which you are working and ends when the window is closed. If you want to run the process in the background, use one of the following options:

Run the Connectivity Agent Installer as a Background Process

Run the agent process. For example:
```
nohup java -jar connectivityagent.jar &
```

Or

If you do not want to expose the password in InstallerProfile.cfg, perform the following steps:
1. Enter java -jar connectivityagent.jar at the command prompt.
2. Enter the user name and password when prompted.
3. Enter Ctrl+Z to suspend the process.
4. Enter bg (to run the process in the background).
5. Enter jobs to get the jobid.
6. Enter disown -a %jobid (from Step e) to disassociate the process from the owning shell.

Connectivity Agent Cannot Be Run as a Service on Windows

Running the connectivity agent as a service on Windows is not supported. You must be logged in to the Windows host. Otherwise, the agent stops working when you log off. Consider the following recommended options.

Create a new service account on Windows.
Use that account to log in to the Windows host and remain logged in with that account.
Install the connectivity agent on the Windows host.
Use that agent to communicate with the MS SQL Server or other endpoints accessed on Windows.

or

Instead of installing the connectivity agent on a Windows host, install it on a Linux virtual machine that has access to the Windows systems with which that agent must interact.