Kyano Java Connector (further referred to as JCO) is a component used for authentication and communication with remote services, utilizing JDBC drivers or Java SDKs. It runs as an independent OS process and can be configured and controlled through transaction /DVD/JCO_MNG.

By default, the JCO is deployed directly on the SAP ABAP application server and can be managed from the SAP GUI.
If the application server's operating system is Linux x64 or Windows x64, the setup is straightforward.
If SAP runs on a different operating system or architecture, please follow additional steps in Using a custom Java Runtime.

In this section:

Transaction /DVD/JCO_MNG

/DVD/JCO_MNG is the interface for the JCO management.
The crucial configuration parameter is the SAP RFC destination, which will be used as a communication channel between SAP and JCO.
In the case of a standalone JCO, the interface only allows checking whether the JCO is up and connected, but the configuration and operation are done remotely (for more information, see the chapter (SM-2511) Standalone Java Connector ).

Table of Contents:

1 Prerequisites
- 1.1 SAP RFC role and user
- 1.2 JCO RFC Destination
- 1.3 SAP Gateway Access (reginfo)
2 Initial setup
3 Using a custom Java Runtime
- 3.1 Java Runtime Environment (JRE)
- 3.2 SAP Java Connector Library
4 Central Java instance
5 SNC configuration
- 5.1 Sample JCO configuration files with SNC enabled
6 Upgrading Kyano Java Connector
7 Automatic Java Connector startup after SAP system restart
8 Creating JCO Copy
9 Custom destination for JCO lock file

Prerequisites

SAP RFC role and user

The JCO requires a dedicated user in the SAP system for program registration on the SAP gateway.
This user should be created with the type System and with authorizations limiting the privileges to basic RFC communication.

Predefined role /DVD/JCORFC is included in the software and can be used as is, or serve as a template for the custom role.

The required authorization object is S_RFC with these settings:

RFC_TYPE = FUGR
RFC_NAME = RFC1, RFC_METADATA, SDIFRUNTIME, SYST, /DVD/SAP_JAVA_UTIL
ACTVT = 16
RFC_TYPE = FUNC
RFC_NAME = RFC_METADATA_GET, /DVD/SAP_JAVA_GET_PROXY
ACTVT = 16

and authorization object /DVD/RL with:

ACTVT = 16

JCO RFC Destination

The JCO communicates with SAP via TCP/IP RFC. Use the example below as a reference.

Technical Settings:

Connection Type: T for TCP/IP Connection.
Activation Type: Select Registered Server Program.
Program ID: Name of the program that JCO will identify itself as when logged on to the SAP gateway (Example: SNP_CONNECTOR).

Special Options:

Serializer: Select Classic serializer with No outbound bgRFC. This special option tends to be set to Fast serializer, which causes malformed messages.

SAP Gateway Access (reginfo)

External communication with the SAP system goes through the SAP gateway. If the SAP system parameter gw/acl_mode is enabled, the reginfo file limits the access of external programs.
In this case, a program needs to have access granted either by wildcard definition or by explicitly defining the program registration name (in our example, it is SNP_CONNECTOR).

More information on the SAP gateway ACL topic can be found on the SAP website, Gateway Security Files, secinfo, and reginfo.

Initial setup

Enter transaction /DVD/JCO_MNG,
Select the latest JCO version by double-clicking the row on the left side of the screen.
Switch to Edit mode,
Click Fill default values,
Fill in the RFC Destination in the General tab.
Fill in the Technical user credentials in the Config tab.

The following authorizations are required for the automatic start of the Java process:

S_RFC_ADM (Administration for RFC Destination): ACTVT = 03, RFCTYPE = * , RFCDEST = <JAVA_RFC>, ICF_VALUE = *
S_DATASET (Authorization for file access): PROGRAM =/DVD/*, ACTVT = *, FILENAME = *
S_LOG_COM (Authorization to Execute Logical Operating System Commands): COMMAND = ZDVD*, OPSYSTEM = * , HOST = *

Management of JCO config versions (upload/download) also requires S_GUI (Authorization for GUI activities) with ACTVT = 61,60

Using a custom Java Runtime

As of Reuse Library version 22.08, the Kyano Java Connector comes with a regularly updated embedded Java Runtime (Adoptium 11 JRE) for Linux 86_x64 and Windows x64, and no manual setup is required in this regard.

If the SAP system runs on a different operating system (Solaris, AIX, HPUX, etc.) or if it is not desired to use the embedded JRE, then the custom JRE and libsapjco3.so library need to be deployed to the application server(s) manually.

Java Runtime Environment (JRE)

Recommended JRE is the latest version of OpenJDK 11. OpenJDK JRE can be downloaded from the Adoptium download site for most architectures.

Not to interfere with possible Java installation already present on the SAP application server, the archive can be simply unpacked into any directory accessible to <sid>adm user, e.g.,/sapmnt/<SID>/global/JRE_11/.

The option to choose between embedded JRE and custom JRE can be found in the Advanced Tab of /DVD/JCO_MNG transaction (example):

Parameters:

Embedded JRE: Path to embedded JRE Java binary. It is by default nested in the JCO Installation directory defined in the Config Tab.
Use custom JRE: Check the checkbox whether or not to use a custom JRE. In the default configuration, the checkbox is unchecked, so the embedded JRE will be extracted to the default path.
Custom JRE: Path to custom JRE Java binary.

SAP Java Connector Library

Javao Java Connector uses a shared library published by SAP named libsapjco3.so (or sapjco3.dll on Windows OS).
The library is included in SNP transports for Linux 86_x64 and Windows x64.
If the system hosting JCO is running on an OS other than Linux 86_x64 and Windows x64, it is necessary to manually download and replace the library after the first attempt to start JCO.
The first start attempt will fail due to incompatibility, but it will deploy all other libraries and configuration files needed for the JCO run. The location of the library is /<installation_directory_path>/lib/.

The SAP Java Connector library can be downloaded at https://support.sap.com/en/product/connectors/jco.html.

Once uploaded to the application server(s), after the first startup attempt (see below), simply replace the library and change the ownership to <sid>adm:sapsys, for example:

cp libsapjco3.so /usr/sap/NSD/DVEBMGS01/work/dvd_conn/jco2402/lib/
chown nsdadm:sapsys /usr/sap/NSD/DVEBMGS01/work/dvd_conn/jco2402/lib/libsapjco3.so

Central Java instance

It is possible to deploy a single JCO instance, instead of running one on every application server.
It is not recommended for productive deployment, but where suitable, it can be set up, following these steps:

If the JCO is already running on several application servers, stop all instances.
Open the Java RFC destination and fill in the Gateway options valid for the desired instance.
When the transaction /DVD/JCO_MNG is reloaded, only buttons next to the application server hosting the JCO are functional, and all the other app. servers will be using this connection.
When the JCO is started, all rows in the Connection column should be green, indicating that every application server can reach the JCO via the designated RFC destination.

SNC configuration

If the SAP system is hardened by Secured Network Communication (system parameter snc/enable = 1), there are additional configuration steps.

The first step is the creation of a Personal Security Environment (PSE) for the JCO. This is to be done under the <sid>adm user.
PSE should be stored together with other SAP PSE files, by default on path /usr/sap/<SID>/<SAP_instance>/sec, referenced by the environment variable $SECUDIR.
Commands to create the PSE, with an example of system ID NSD with csh as nsdadm’s shell:
su - nsdadm
setenv SECUDIR /usr/sap/NSD/D00/sec
cd $SECUDIR
sapgenpse gen_pse -v -p SNPJCO.pse
A passphrase can optionally protect PSE. The mandatory input parameter is the Distinguished name of the PSE owner; in our example, it’s CN=SNPJCO, OU=SNP, C=DE.
nsd:nsdadm 98> sapgenpse gen_pse -v -p SNPJCO.pse Got absolute PSE path "/usr/sap/NSD/D00/sec/SNPJCO.pse". Please enter PSE PIN/Passphrase: Please reenter PSE PIN/Passphrase: !!! WARNING: For security reasons it is recommended to use a PIN/passphrase !!! WARNING: which is at least 8 characters long and contains characters in !!! WARNING: upper and lower case, numbers and non-alphanumeric symbols. get_pse: Distinguished name of PSE owner: CN=SNPJCO, OU=SNP, C=DE Supplied distinguished name: "CN=SNPJCO, OU=SNP, C=DE" Creating PSE with format v2 (default) succeeded. certificate creation... ok PSE update... ok PKRoot... ok Generating certificate request... ok. Certificate Request: Signed Part: Subject: CN=SNPJCO, OU=SNP, C=DE Key: rsaEncryption (2048 bits) Attributes: None Signature: Signature algorithm: sha256WithRsaEncryption (1.2.840.113549.1.1.11) Signature: <Not displayed> PKCS#10 certificate request for "/usr/sap/NSD/D00/sec/SNPJCO.pse": -----BEGIN CERTIFICATE REQUEST----- MIICcjCCAVoCAQAwLTELMAkGA1UEBhMCREUxDDAKBgNVBAsTA0RWRDEQMA4GA1UE ################################################################ ################################################################ ################################################################ PxmDNQSCYvLxURXcP+vQxDSOq5QYgQf4g4egjVXRcyQwOJNZRpHlP1olXc4Aa675 -----END CERTIFICATE REQUEST----- nsd:nsdadm 99>
The second step is to export the certificate with the public key from the newly created PSE, using the command:
sapgenpse export_own_cert -v -p SNPJCO.pse -o SNPJCO.crt
This produces the SNPJCO.crt file.
nsd:nsdadm 99> sapgenpse export_own_cert -v -p SNPJCO.pse -o SNPJCO.crt Opening PSE "/usr/sap/NSD/D00/sec/SNPJCO.pse"... No SSO credentials found for this PSE. PSE (v2) open ok. Retrieving my certificate... ok. Writing to file (PEM-framed base64-encoded)... ok. nsd:nsdadm 100>
Now import the JCO certificate file into the SAP system’s Trust Manager.
Run transaction STRUST > switch to Edit mode > double-click SNC PSE node > in the lower part of the screen, click on the Import certificate icon, locate the certificate file, confirm file selection > click Add to Certificate List > Save (Ctrl+S)
NOTE: You will need to download the certificate file to your front-end to be able to select it.
The JCO certificate has been imported to SAP. To create two-way trust between SAP and JCO, we now need to import the SAP system’s certificate to JCO PSE.
Export SAP’s certificate, similarly to step 3. Run STRUST and select the SNC PSE node, but double-click on Own certificate, and at the bottom of the screen, click the icon Export certificate. Choose Base64 format, path, and filename to save the .crt file. Upload the file to the application server, ideally to $SECUDIR.
To import the SAP certificate to JCO PSE, run the command:
sapgenpse maintain_pk -v -a SAP.crt -p SNPJCO.pse
nsd:nsdadm 104> sapgenpse maintain_pk -v -a NSD.crt -p SNPJCO.pse Opening PSE "/usr/sap/NSD/D00/sec/SNPJCO.pse"... No SSO credentials found for this PSE. PSE (v2) open ok. retrieving PKList Adding new certificate from file "NSD.crt" ---------- Subject : CN=NSD, OU=SNP, C=DE Issuer : CN=NSD, OU=SNP, C=DE Serialno : 0A:20:21:01:24:10:44:01 KeyInfo : RSA, 2048-bit Validity - NotBefore: Sun Jan 24 11:44:01 2021 (210124104401Z) NotAfter: Fri Jan 1 01:00:01 2038 (380101000001Z) KeyUsage : none ExtKeyUsage : none SubjectAltName : none ---------------------------------------------------------------------------- PKList updated (1 entries total, 1 newly added) nsd:nsdadm 105>
To allow JCO to run under <sid>adm user using the certificate stored in the PSE, SSO credentials must be created in the cred_v2 file.
The file typically already exists in SECUDIR, and access to the JCO PSE file certificate is granted with:
sapgenpse seclogin -p SNPJCO.pse -O nsdadm
If the SAP system is distributed, the PSE file and SSO credentials allowing access to it in cred_v2 need to be present on each application server.
IMPORTANT: cred_v2 file must NOT be copied between application servers!
It must be updated locally with the sapgenpse utility to reflect the correct PSE path. (The PSE file can be copied.)
nsd:nsdadm 106> sapgenpse seclogin -p SNPJCO.pse -O nsdadm running seclogin with USER="nsdadm" creating credentials for yourself (USER="nsdadm")... Added SSO-credentials for PSE "/usr/sap/NSD/D00/sec/SNPJCO.pse" nsd:nsdadm 107>

NOTE: If JCO is deployed in a Windows environment, allow access to the PSE file for user SAPService<SID>.
Example: sapgenpse seclogin -p SNPJCO.pse -O SAPServiceNSD
Available SSO credentials can always be checked using the command:
sapgenpse seclogin -l
Now that the security environment is prepared, configure JCO SNC in transaction /DVD/JCO_MNG in the Config Tab:
- SNC enabled: Once activated, the user and password fields will be greyed out and have no effect on JCO configuration.
- SNC QoP Level: SNC Quality of Protection, needs to be the same level set in system parameters snc/data_protection/use (default = 3).
- SNC name: Distinguished name chosen during the creation of JCO PSE (step 1).
- SNC-enabled GW port: SAP gateway port used for secure communication. Do not change the default value 48$$, $$ is automatically translated to the instance number of a particular application server.
- SNC partner name: Distinguished name of SAP system, pre-filled from SAP profile parameter snc/identity/as.
  Save the configuration when completed, but do not start the JCO yet.
There are two more configuration pieces to complete before JCO can properly start and register on the SAP gateway.
In SU01, activate SNC for the RFC user for JCO communication, filling in the SNC name of the JCO.
Despite the user no longer being configured in /DVD/JCO_MNG, it is used by matching the SNC name entered here and the name configured in the JCO PSE file.

Secondly, via SM59 activate SNC in the RFC destination dedicated to communication between SAP and JCO, and fill in the JCO Distinguished name again in the Logon & Security tab (SNC options button):

With all SNC prerequisites met, the Java Connector can be started.

Sample JCO configuration files with SNC enabled

If the JCo is deployed in a Windows environment, the path to the cryptographic library may contain \usr or a similar path segment with \u character.
That may result in an error during JCo startup:
Exception in thread "main" java.lang.IllegalArgumentException: Malformed \uxxxx encoding.

To circumvent this, every \u character in the configuration files must be preceded by an additional backslash → \\u.
To prevent the automatic overwrite of manually modified configuration files during JCO start, the option Avoid JCO config files creation of /DVD/JCO_MNG needs to be selected:

Configuration files example:

nsd:/usr/sap/NSD/D00/work/dvd_conn/jco2402 # cat config.jcoServer
version=2402
jco.server.gwhost=127.0.0.1
jco.server.gwserv=4800
jco.server.connection_count=10
jco.server.progid=SNPJCO
jco.server.repository_destination=ABAP_AS_WITH_POOL
jco.server.worker_thread_min_count=5
jco.server.worker_thread_count=20
jco.server.snc_mode=1
jco.server.snc_qop=3
jco.server.snc_myname=p:CN=SNPJCO, OU=SNP, C=DE
jco.server.snc_lib=/sapmnt/NSD/exe/uc/linuxx86_64/libsapcrypto.so

nsd:/usr/sap/NSD/D00/work/dvd_conn/jco2402 # cat config_as.jcoDestination
jco.client.client=001
jco.client.sysnr=00
jco.client.peak_limit=10
jco.client.ashost=127.0.0.1
jco.client.snc_mode=1
jco.client.snc_qop=3
jco.client.snc_myname=p:CN=SNPJCO, OU=SNP, C=DE
jco.client.snc_partnername=p:CN=NSD, OU=SNP, C=DE
jco.client.snc_lib=/sapmnt/NSD/exe/uc/linuxx86_64/libsapcrypto.so

Upgrading Kyano Java Connector

This is a list of steps to do when you update your SNP software, and you would like to switch to a new version of the Kyano Java Connector.

With SAP JCO version 3.1, additional authorization is required for JCO’s RFC user, which allows the execution of function modules in the function group RFC_METADATA.
Please make sure the RFC user has all authorizations listed in the SAP RFC role and user section of this page.

Open transaction /DVD/JCO_MNG
Double-click the current working connector and click Upgrade JCO.
A pop-up window will appear, confirming the version to which JCO will be upgraded and selecting the new installation directory. Press Proceed to continue.
Acknowledge the warning. Once confirmed, JCO will upgrade automatically.
After a successful upgrade, a new version of JCO will be automatically deployed and started.

Restarting the connector can cause running Glue/Outboard jobs to fail. Therefore, it is recommended to perform the upgrade during a quiet period and have Glue/Outboard jobs suspended.

Automatic Java Connector startup after SAP system restart

For the automatic start of the Java Connector after the SAP system restarts, schedule a periodic job with program /DVD/JCO_WATCH_DOG and an After Event start condition: SAP_SYSTEM_START.

Setting up the automatic start of the Java Connector after the SAP system restart is not mandatory. The JCO is normally started when it is needed.

Creating JCO Copy

Sometimes it may be needed to copy the JCO instance and create a separate version.
When the JCO is copied, a separate installation directory is used; the new JCO instance thus has its own space for configuration and logs.

Possible use cases for JCO Copy:

Vertical scaling: When more JCO instances are needed.
Versioning: When the JCO is needed for a different purpose.
JCO testing: To create different instances for testing purposes.

With Copy JCO functionality, the new JCO copy/instance is created with an increased subversion ID number.

For example, when copying from ID 240, then a JCO copy is created with ID: 240.1. The next copy will have ID: 240.2.

Open transaction /DVD/JCO_MNG.

Click on Copy JCO.

Copy config from Java RFC: Copies JCO configurdifferentom the JCO configured with the selected RFC destination.
Copy config from version ID: Copies JCO configuration from given JCO ID.
Use default values: Uses defaults for the new JCO.
Java version: Read-only field as a newly created copy of JCO will be created from a particular Java version.
Description: Description of a newly created copy of JCO.

Example of the JCO copy, reconfigured with appropriate parameters - most importantly, RFC destination and Installation directory.

Custom destination for JCO lock file

The lock file is used to prevent the accidental start of multiple JCO instances on the same host. By default, the lock file is created in the Installation directory.
If needed, the directory can be changed, using the parameter -DremoteLockFileDir=<ChosenDirectory>.

(SM-2511) Kyano Java Connector Setup