Skip to main content

Transparent Proxy Destinations

The SAP Cloud SDK supports connecting to systems through the Transparent Proxy, which provides enhanced connectivity features and simplified on-premise access in Kubernetes-based environments like Kyma. The TransparentProxyDestination class enables applications to leverage these capabilities seamlessly.

Prerequisites​

Kubernetes Only

The Transparent Proxy is currently only available for Kubernetes-based environments such as Kyma and Gardener.

Installation Required

Before using TransparentProxyDestination, ensure that the Transparent Proxy is installed and configured in your Kubernetes cluster. Refer to the official installation guide for setup instructions.

Background Information​

The Transparent Proxy is a connectivity component provided by SAP BTP that acts as an intermediary between your application and target systems. When using the Transparent Proxy your app performs requests against the Transparent Proxy without explicit authentication. This relies on the secure network communication provided by Kyma via Istio. The Transparent Proxy will obtain the relevant destination from the destination service. It will then use this destination to forward the request to the target system or to the Connectivity Proxy for On-Premise destinations. Consequently, your app itself does not interact with destination or connectivity service at all. This means your application pods do not require bindings to these two services.

Creating Transparent Proxy Destinations​

The TransparentProxyDestination class provides two types of builders for different use cases:

1. Static Destinations​

Static destinations connect directly to a specified URL. They allow setting generic headers but do not support dynamic properties like destination name or fragments.

TransparentProxyDestination destination = TransparentProxyDestination
    .staticDestination("https://my-service.com")
    .header("X-Custom-Header", "custom-value")
    .property("some-property-key", "some-value")
    .build();

2. Dynamic Destinations​

Dynamic destinations require both URL and destination name. They support dynamic properties like fragments.

TransparentProxyDestination destination = TransparentProxyDestination
    .dynamicDestination("my-destination", "https://proxy-gateway.com")
    .fragmentName("my-fragment")
    .build();

Tenant Configuration​

The SAP Cloud SDK will automatically set the current tenant as tenant ID on a per-request basis.

In case a fixed tenant should be used, you can manually set it as follows:

// Using a fixed tenant ID (automatically set by SDK if not specified)
// alternatively, .tenantSubdomain("..") can be used, but only one of the two options may be set
TransparentProxyDestination destination = TransparentProxyDestination
    .dynamicDestination("my-destination", "https://proxy-gateway.com")
    .tenantId("my-tenant-id")
    .build();

Authorization Header Configuration​

The SAP Cloud SDK will automatically set the current user's authorization token in the Authorization header on a per-request basis.

In case a fixed authorization token should be used, you can manually set it as follows:

// Dynamic destination with authorization method
TransparentProxyDestination destination = TransparentProxyDestination
    .dynamicDestination("my-destination", "https://proxy-gateway.com")
    .authorization("Bearer my-fixed-token")
    .build();

// Static destination with authorization method
TransparentProxyDestination destination = TransparentProxyDestination
    .staticDestination("https://my-service.com")
    .authorization("Bearer my-fixed-token")
    .build();

Note: When you manually set authorization, it will override the SAP Cloud SDK automatic token handling.

Migration from Traditional Destinations​

When migrating from traditional destination configurations:

Before (Traditional Destination)​

Destination destination = DestinationAccessor.getDestination("my-destination");
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);

After (Transparent Proxy - Dynamic)​

TransparentProxyDestination destination = TransparentProxyDestination
    .dynamicDestination("my-destination", "https://proxy-gateway.com")
    .build();
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);

After (Transparent Proxy - Static)​

TransparentProxyDestination destination = TransparentProxyDestination
    .staticDestination("https://my-service.com")
    .build();
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);

Troubleshooting​

Common Issues​

  1. Missing destination name for dynamic destinations: Ensure the destination name is provided as the first parameter to .dynamicDestination("destination-name", "gateway-url")
  2. Tenant context not available: Verify tenant information is properly set in the request context
  3. Authentication failures: Check that authentication headers and parameters are correctly configured
  4. Network connectivity: Verify that the Transparent Proxy is accessible from your environment

Evaluating Transparent Proxy Headers​

When using proxy servers it can be difficult to troubleshoot issues as it is often not obvious where exactly the error occurred. For example, with the Transparent Proxy errors might occur on the target system (e.g. OData service), the Destination Service or the Transparent Proxy itself.

To make troubleshooting easier the Transparent Proxy adds additional response headers to provide more information about where an error occurred. For the above example of executing OData requests you can access the response headers as follows:

try {
    // execute OData request
} catch (ODataResponseException e) {
    System.out.println(e.getHttpCode());
    // the Transparent Proxy will attach additional response headers in case an error occurred
    System.out.println(e.getHttpHeaders());
}

List of headers added by the Transparent Proxy​

  • X-Error-Origin - the source of the error
  • X-Proxy-Server - the proxy server (Transparent Proxy)
  • X-Error-Message - thorough error message
  • X-Error-Internal-Code - set only when the source of the error is the XSUAA or Destination service. The value is the HTTP code returned from one of these services.
  • X-Request-Id is sent with the response in all requests, both successful and failed

For more information about the Transparent Proxy itself, refer to the official SAP documentation.