The Destination Service API 

Use

With the Destination service, you can set up HTTP(S) connections from the SAP J2EE Engine to other servers. Web services also use the Destination service to establish connections. The data to use for the connection (target address and user authentication information) are specified in the Destination service as a destination entry.

Two types of destinations are supported: HTTP(S) and Web services. HTTP destinations support HTTP-Post and HTTP-Get requests to HTTP or HTTPS URLs. Web service destinations are automatically created for deployable Web service proxies and are used to configure the authentication data (see Incorporating Web Services).

You can either set up destinations manually using the Visual Administrator or you can use the service’s API to establish destinations programmatically.

This documentation applies to the programmatic use of the API to set up the destinations. For more information about using the Visual Administrator, see Destination Service in the Administration Manual.

Integration

Secure Storage

The URL and user authentication information specified in the destination entry is saved encrypted using the J2EE Engine’s Secure Storage service.

Using SSL for HTTPS Connections

HTTP destinations can also use the Secure Sockets Layer (SSL) protocol to establish secure connections to the target server. The Destination service uses the secure connection factory to establish these connections.

The corresponding public-key certificates are to be stored in a keystore entry in the Key Storage service. These include the trusted CA certificate to use to verify the target server’s server certificate and, if applicable, the user’s X.509 client certificate to use for authentication.

Logging

The Destination service uses the J2EE Engine’s logging API. Any debugging logs are written to the Destination service’s logs, as well as to the Secure Storage service’s logs and the HTTPS connection factory’s logs.

Authentication Methods

You specify the authentication method to use for a connection when you create the HTTP destination. The following authentication methods are supported:

·        None

If you use this option, then no authentication occurs with the connection.

·        Basic

With this option, then you must specify the user name and password to use for the connection. The user information is then sent with the request in an HTTP Basic Authentication header.

·        X.509 client certificates

In this case, SSL with mutual authentication is used to authenticate the client. To use this option, you must specify the public-key certificate from a keystore entry in the Key Storage service to use for the client authentication.

·        Logon Tickets

In this case, the current user must possess a logon ticket. The logon ticket is then sent with the request.

Prerequisites

·        If the destination data should be stored encrypted in secure storage, or if SSL should be used to secure the connection, then the full version of the SAP Java Cryptographic Toolkit must be installed on the J2EE Engine. For more information, see Deploying the SAP Java Cryptographic Toolkit in the Administration Manual.

The distribution of the SAP Java Cryptographic Toolkit is subject to and controlled by German export regulations and is not available to all customers. In addition, the library may be subject to local regulations of your own country that may further restrict the import, use and (re-)export of cryptographic software. If you have any further questions on this issue, contact your local SAP subsidiary.

If the SAP Java Cryptographic Toolkit is not deployed on the server then the data is stored in the secure storage area using base 64 encoding. However, SSL will not work.

·        If the connection uses SSL, then the user who runs the application must have access to the keys in the Key Storage service.

·        If you use logon tickets for user authentication, then:

¡        The servers involved in the connection must be configured for using logon tickets for authentication.

¡        The user must possess the logon ticket before using the connection specified by the destination. Therefore, the application using the destination must ensure that the user has a logon ticket. (Include the modules EvaluateTicketLoginModule and CreateTicketLoginModule in the application’s login module stack.)

·        Your application needs classloader references to tc~sec~destinations~service and tc~sec~destinations~interface.

Activities

You can use the Destination service API to create, delete, change or use destinations.

Creating a Destination

To create a destination:

...

       1.      Lookup a reference to the Destination service using the JNDI service.

       2.      Create a new destination (method: createDestination).

       3.      Adjust the destination’s parameters (method: set<parameter>).

       4.      Store the destination (method: storeDestination).

Using a Destination

To establish a connection using a destination:

...

       1.      Lookup a reference to the Destination service using the JNDI service.

       2.      Obtain a destination (method: getDestination).

       3.      Open a connection (method: getURLConnection).

See also:

Interfaces and Classes for Using the Destination Service API

Examples for Using the Destination Service API