The destination service securely stores your configuration information — such as user and password or logon tickets that call remote business applications. Additionally, the destination service can store different parameters that depend on the protocol used and describe how to access the necessary business component. Furthermore, the destination service provides functionality that allows you to generate tickets (e.g., logon ticket or assertion ticket used in the system back-end communication) and define user mapping. This is helpful, for example, if you use basic authentication functionality and your user name and password differ in the remote system.

The destination service supports the following connection types to remote business applications and systems:

• HTTP connection
• Remote Function Call (RFC) connection
• Web service connection

I explain the SAP NetWeaver Application Server (SAP NetWeaver AS) Java connection types and authentication mechanisms. I use example configurations of HTTP- and RFC-based connections to an SAP ABAP-based system and calling of remote business functionality — such as calling RFC function modules in an SAP ABAP system using SAP Java Connection (SAP JCo) or searching for business information using SAP Enterprise Search (HTTP-based searching using OpenSearch standard). Finally, I show you how to use the connection service and configured destinations in your Java business applications.

Authentication Mechanisms with Destination Services

Destination service supports the following authentication mechanisms for HTTP and RFC connections:

• Basic
• X.59 client certificate authentication
• SAP logon ticket
• SAP assertion ticket

• User mapping

Basic Authentication

This authentication is also known as user name and password authentication. With the basic authentication type, you set the user name and password. The system uses this information for each call to authenticate the call into the target system.

X.509 Client Certificate Authentication

This authentication, also known as client certificate authentication, is based on SSL. It provides server authentication and client authentication with X.509 certificates. The configured certificate is used for each call to the remote business functionality, independent of the user who requests access to the configured destination.

SAP Logon Ticket

If this authentication type is configured, the destination service uses HTTP to gather information about the current user and creates a user-specific logon ticket that is valid for the user in the target system. This ticket is sent to the target system each time the user calls the business functionality in that system.

SAP Assertion Ticket

The SAP assertion ticket is a special form of the logon ticket which is used to communicate between systems. With both SAP logon tickets and SAP assertion tickets, no user interaction is necessary. The ticket is created for the logged on user. It is available for one-time use only and has a short validity period (two minutes).

If this authentication type is configured, the destination service uses HTTP to create a user-specific assertion ticket that is valid for the user in target system. In this case, you must set the system ID (SID) and client of the target system for which the assertion ticket is intended. This ticket is sent to the target system each time the user calls the remote business functionality.

User Mapping

This authentication type allows you to define user mapping in the target system. The destination service uses HTTP to obtain the current user information and applies user mapping configuration to switch the user name and password to call the target system. The destination service allows user mapping for basic authentication — the mapping functionality for the ticket-based authentication is not supported. The mapping functionality requires the User Management Engine (UME) to set up the mapping between the local user and the user in the remote (i.e., target) system. Additionally, UME supports group-related and role-related mapping.

First, the UME checks if the current user has a remote user defined (i.e., user name and password). If no, the UME checks each group to which the current user is assigned for the remote user mapping on group level. If no group-related user mapping is found, the UME checks the user mapping configuration for any assigned role that has a remote user configured. The first found mapping is returned — otherwise, the secure connection cannot be established via the user mapping functionality.

To support these authentication mechanisms, the destination service uses the secure keystore functionality (for X.509 authentication and SSL) and the UME (e.g., for user mapping) which are part of SAP NetWeaver AS Java. The destination service in SAP NetWeaver AS Java 7.11 supports the creation of dynamic destinations. This functionality can be used by privileged components to create new destination types and instances. This means that the destinations and their properties can be created or modified programmatically in your Java-based business application via the destination service API. The privileged component may access the destination properties (especially security-sensitive properties) using the code-based security.

I start with a short introduction to the HTTP and RFC destination configuration that SAP NetWeaver Administrator supports and then explain how to configure a destination that uses HTTP protocol or RFC protocol. At the end, I present how to use the existing configured destination to access remote system in the business application, such as to call SAP Enterprise Search functionality and consume the search results.

Configure the Destination Service

You can create the destination via SAP NetWeaver Administrator, which is an administrative tool that allows you to administer SAP NetWeaver AS Java. To call this tool, you use the following URL:

https://<hostName>:<portNumber>

For example, https://wdfd00223395a:51000 and use the SAP NetWeaver Administrator navigation entry to start the tool (Figure 1).

Figure 1

Call SAP NetWeaver Administrator

Alternatively, you can use the following direct URL:

https://<hostName>:<portNumber>/nwa

For example, https://wdfd00223395a:51000/nwa.

In the next step, you need to log in as the administrator (a user with administrative rights) and follow menu path Configuration Management > Security > Destinations (Figure 2).

Figure 2

Access the Destinations configuration

The destination service is integrated into SAP NetWeaver Administrator (Figure 3). You can easily display the list of configured destinations in the Destination Detail window. You can then modify the destination by clicking the Edit button or remove it by clicking the Remove or Remove All buttons. Furthermore, you can check if the destination configuration allows an open connection to the target system by clicking the Ping Destination button in the Destination Detail view.

Figure 3

The list of configured destinations

Configure the Secure HTTP Connection

To create a new destination, click the Create… button in Figure 3 to start the creation wizard. In this example, you start to configure the connection to the SAP Enterprise Search system that allows you to search SAP and non-SAP systems, such as to find business objects defined in SAP ERP, SAP Customer Relationship Management, or SAP Supply Chain Management.

Figure 4 presents the first creation steps of destination — the general data. In the initial screen, the Hosting System data is filled with the local setting for the SAP NetWeaver AS Java configuration (the Local J2EE System CLG value). You need to enter the Destination Name (SAP.Enterprise.Search.System.EKA) and select the Destination Type (HTTP).

Figure 4

Create the HTTP destination — general data

Click the Next button to move to the next window, where you can configure the connection parameters and security setting (Figure 5). In the connection area, enter the URL to the target system in the URL field. For an SAP system, enter the system identifier, client number, and language.

Figure 5

Create the HTTP destination — Connection data

Additionally, you can configure the use of certificates in the destination (SSL Server Certificates). If you select Accept Certificates in Keystore View, you can select an imported server certificate that the system uses each time the destination/connection communicates with the target system (e.g., to call a business application running in the target system). If you select the Ignore Server Certificates option (default configuration), the server certificate is not used. In this case, you need to configure the authentication method in the next step.

Figure 6 shows you the next wizard step where you configure the connection authentication method (basic authentication, X.509 Client Certificate with SSL, Assertion Ticket, Logon Ticket, or User Mapping).

Figure 6

Select the authentication method

After you have selected the authentication method, the wizard opens additional input fields where you enter required information, such as the user name and password for the basic authentication (Figure 7). The configuration of basic authentication is only an example — you can select different authentication methods depending on your requirements. In this case, the creation wizard asks you for other authentication data (if necessary).

Figure 7

Enter the user name and password for basic authentication

After the destination data is complete, click the Ping Destination button. The destination service checks if the connection can be established and processes the appropriate success or error message (see the message in the window’s header).

Click the Finish button to save a newly created destination in the destination service. After that the new destination appears in the list of configured destinations (Figure 8).

Figure 8

HTTP destination overview

Now you can use the destination in your business application to connect to a remote system, which I explain in the next section.

Configure a Secure RFC Connection

Here is an example of how to configure an RFC connection to an SAP ABAP system. Click the Create… button and follow the configuration wizard to configure the connection to SAP ABAP system. In my example, I show how to create a destination to an SAP Enterprise Search system.

Figure 9 presents the first creation steps of creating the RFC destination — the general data. Similar to creating an HTTP destination, the Hosting System field is filled with the local setting of SAP NetWeaver AS Java configuration (in my example, Local J2EE System CLG). Enter the Destination Name (RFC destination – EKA system) and select the Destination Type (RFC).

Figure 9

Create the general data for the RFC destination

Click the Next button. The wizard opens the Connection and Transport window (Figure 10).

Figure 10

Create RFC destination connection data

In the connection area, select whether the destination should use the load balancing functionality, enter the SAP system identifier, message server, message server service, logon group, and, if used, the gateway host and service.

Additionally, you can use the connection for Secure Network Communications (SNC) functionality. Select the Active SNC and enter the protection data (QoP and SNC Partner Name). Otherwise, the SNC is not used (default configuration is that SNC is inactive).

Figure 11 displays the logon data view, where you configure the following authentication data:

• Authentication method: The destination service offers the following authentication methods and information:
  • Technical user
  • Current user using logon ticket
  • Current user using assertion ticket
  • User mapping
• Language: The language used to connect to the SAP system
• Client: The client number
• User name and password: The name of user and its password that is used to connect to the target SAP system

Figure 11

Set the authentication data

When you finish entering the destination data, click the Ping Destination button to check if the destination service can establish a connection using configured data (see the success message in the window’s header).

Figure 12 shows the last configuration step — configuration of additional settings, such as the use of the connection pool, trace, and SAP router.

Figure 12

Create the destination data for the RFC destination

The Pool Settings allows you to set whether the destination should support the use of pooled connections, the maximum number of connections that can be opened in parallel to communicate to target system, the pool size, and how long (in milliseconds) the connection should wait for a response before closing the connection. Additionally, the destination service supports some advanced options, such as the use of an SAP router, configuration of a connection trace, and configuration of the level of trace. Finally, you can indicate the communication codepage to use.

Click the Finish button and the destination service saves the destination into configuration store. It displays the new destination service in the list of configured destinations, such as the list in Figure 8. For more information on how the system stores the destination configuration, see the sidebar “Storing and Viewing the Destination Configuration.”

Set Up Project References to Use the Destination Service

To use the previously configured destinations in your business application, you need to set up the build-time reference and runtime references to the destination service interface.

The build-time reference is defined as Java project reference in SAP NetWeaver Developer Studio and used during the compilation of the business application. Select the project (e.g., myBusinessApplication project), right-click, and select the project properties. In the Properties window, select the Java Build Path view. Then in the Libraries tab, add the reference to the .jar file that defines the destination service interface: sap.com~tc~sec~destinations~interface_api~impl.jar (Figure 13).

Figure 13

Configure the Java project build-time dependencies

The runtime reference is defined in the application’s deployment, which is a part of the business application and used by the SAP J2EE server to resolve an application’s dependencies at runtime. Figure 14 presents the example J2EE application deployment descriptor (application-j2ee-engine.xml file), which contains the references to destination service interface.

<?xml version="1.0" encoding="UTF-8"?>
<application-j2ee-engine xmlns:xsi=https://www.w3.org/2001/XMLSchema-instance 
xsi:noNamespaceSchemaLocation="application-j2ee-engine.xsd">
  <reference reference-type="hard">
    <reference-target provider-name="sap.com" target-type="interface">  
        tc~sec~destinations~interface
    </reference-target>
  </reference>        
</application-j2ee-engine>

The runtime reference is defined by the <reference> element, which contains the reference type parameter. This parameter defines whether the reference is a weak or hard reference. This means that if the value of the element is hard, the referenced application must be already deployed and running during application’s deployment or startup. If the value of the element is weak, the referenced application must be available when the application starts accessing it. Additionally, the reference definition contains the <reference-target> element, which defines the provider name and its type (see the target-type parameter). The value of the target-type parameters could be as follows:

• Interface: If the reference points to the J2EE interface
• Service: If the reference points to the J2EE service

• Application: If the reference points to the J2EE application

Obtain an Instance of the Destination Service

To use the destination service in the business application, you may obtain the destination service instance from the Java naming and directory service (the Java Naming and Directory Interface [JNDI]), which is a central service in the SAP J2EE server that allows Java applications to discover and look up data and objects via a name application’s name (identifier).

Figure 15 displays a sample Java program that obtains the instance of the destination service from JNDI.

import javax.naming.InitialContext;
import com.sap.security.core.server.destinations.api.Destination;
import com.sap.security.core.server.destinations.api.DestinationService;
public class ConnectionBuilder implements ConnectionBuilderLocal {
    public DestinationService getDestinationServiceInstance() {
       InitialContext initCtx = null;
        DestinationService dstService = null;
        try {
            initCtx = new InitialContext();
            dstService = (DestinationService) initCtx.lookup(DestinationService.JNDI_KEY);
        } catch (NamingException e) {
            e.printStackTrace();
        }
       
        return dstService;
    }
}

First, you need to create the instance of JNDI initial context (see initCtx = new InitialContext();) and then use the JNDI lookup() method to obtain Destination service (see dstService = (DestinationService) initCtx.lookup(DestinationService.JNDI_KEY);).

Call the HTTP Destination

After you have obtained the instance service destination from JNDI (instance of com.sap.security.core.server.destinations.api.DestinationService) you can use it to obtain a particular destination. Figure 16 shows the sample method getXmlDocumentFromDestination(), which calls the getDestinationServiceInstance() method to obtain the destination service instance. Then it calls its getDestination() method to obtain the HTTP destination. The HTTP destination object provides the method getURLConnection(), which is used to call the target system (e.g., call the URL that provides the xml document).

public Document getXmlDocumentFromDestination(String destName)  {
    DestinationService destService = this.getDestinationServiceInstance();
    try {
        HTTPDestination httpDest = (HTTPDestination) destService.getDestination("HTTP", destName);
        HttpURLConnection httpConnection = httpDest.getURLConnection();
           
        Document xmlDocument = DocumentBuilderFactory.newInstance().newDocumentBuilder()
.parse(httpConnection.getInputStream());
    } catch (DestinationException e) {
        e.printStackTrace();
    }
}

Table 1 presents the list of destination service methods that allow you to obtain particular destinations or check if the destination works.

Table 1

Destination service methods

The destination service API provides functionality that allows you to programmatically create, modify and delete destinations.

The method storeDestination() (see storeDestination (String type, Destination destination) throws DestinationException, java.rmi.RemoteException) and stores the  destination defined by destination parameter and given destination type. If the destination does not exist, the destination is created. Otherwise, the existing destination is modified.

The method updateDestination() (see updateDestination(String type, Destination destination) throws DestinationException, java.rmi.RemoteException) and updates the existing destination.

The method removeDestination() (see removeDestination(String type, java.lang.String name) throws DestinationException, java.rmi.RemoteException) and removes an existing destination from the destination service store.

The destination service protects the execution of these methods (storeDestination, updateDestination, removeDestination) using user-based permission check and therefore the current user that performs this method call must be assigned to the UME action named Destination_Service_Write_Permission. This action is already assigned to members of the UME Administrator role.

Call an RFC Destination

With RFC destinations, the destination service does not provide a ready-to-use connection to the target system. Instead, it provides RFC properties that define a certain RFC endpoint. After you have obtained the instance service destination from JNDI, you can obtain the destination properties and use them to build the RFC connection using SAP JCo.

Figure 17 shows the sample method getRfcClient(), which provides a ready-to-use RFC connection. To obtain the destination service instance, the method calls the previously defined getDestination() method. An RFC destination object that provides RFC properties is used as a configuration source to create the instance of SAP JCo.

public JCO.Client getRfcClient(String destName) {
    DestinationService destService = this.getDestinationServiceInstance();
       
    RFCDestination rfcDest = (RFCDestination) destService.getDestination("RFC", destName);
   
    Properties jcoProperties = rfcDest.getJCoProperties();
    int maxPoolSize = rfcDest.getMaxPoolSize();
    long maxWaitTime = rfcDest.getMaxWaitTime();
     
    JCO.Client client = JCO.createClient(jcoProperties);
    client.connect();
    client.ping();
       
    return client;
}

The SAP JCo provides the connect() method that opens connection to SAP system and you can use it to call the RFC function in SAP ABAP systems. Additionally, the SAP JCo provides the ping functionality that allows you to programmatically check if the destination is configured properly and the target system can be reached.

Storing and Viewing the Destination Configuration
The destination configuration is stored using the SAP NetWeaver Configuration Manager in the SAP JEE persistence. You can access it directly via the SAP NetWeaver Config Tool. 

The Config Tool allows low-level viewing and maintenance of the SAP JEE configuration. Start the Config Tool by using its startup script (configtool.bat on Windows systems or configtool.sh on Unix systems). This script is located on the central J2EE instance in the Config Tool directory:

• On Windows systems: <drive>usrsap<SID>JC<InstNo>j2eeconfigtool
• On Unix systems: /usr/sap/<SID>/JC<InstNo>/j2ee/configtool

Figure A presents the configuration entry point in the SAP NetWeaver Configuration Manager.

Figure A

The configuration entry point in SAP NetWeaver Configuration Manager

Figure B displays an example of an RFC destination that is stored in the SAP JEE persistence.

Figure B

Sample configuration of an RFC destination

 

Robert Heidasch

Robert is the chief innovation and technology lead in the global Accenture Technology Platform, which is responsible for SAP Leonardo and the new digital technology defining business value and driving the digital transformation of complex enterprise solution for Accenture diamond and strategic clients. Before that he was responsible as innovation and solution lead for the design and architecture of new business applications developed jointly by Accenture and SAP based on the newest SAP and non-SAP technology. Robert is the Accenture certified Senior Digital Architect and Senior Technology Architect. He is coauthor and trainer of a couple of SAP technology-related trainings for the in-memory platform and architecture of new business applications (e.g., SAP HANA, SAP Cloud Platform, and SAP Leonardo applications for solution architects and technical architects, all of which were provided by Accenture in Europe, the US, and Asia). Robert has more than 23 years’ experience designing and developing IT systems. He published several technical and business articles about SOA, SAP NetWeaver and its integration with non-SAP systems (e.g. Microsoft, Oracle, etc.), and SAP HANA technology. He is also an inventor of 38 patents in the US in the area of in-memory technology, artificial intelligence and machine learning, security, semantics, and SOA. He is a frequent speaker in international business conferences and SAP Forum. He is a subject matter expert in customer projects worldwide and has extended experience in team leadership in Europe, the US, and India.

You may contact the author at robert_heidasch@outlook.com.

If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.