Skip to main content

Transparent Proxy

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. The TransparentProxyDestination class enables applications to leverage these capabilities seamlessly.

Prerequisites​

Kubernetes Only

The Transparent Proxy is currently only available for Kubernetes-based environments.

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. The Transparent Proxy is available in Kyma environment as a dedicated module. Refer to Transparent Proxy in Kyma environment for instructions how to add the module.

Background Information​

The Transparent Proxy is a SAP BTP Connectivity component that acts as an intermediary between your application and target systems. The Transparent Proxy simplifies and unifies how your Kubernetes workloads connect to remote systems using SAP BTP destinations. It provides authentication, principal propagation, SOCKS5 handshake, and easy access to the destination target systems by exposing them as Kubernetes Services.

The Transparent Proxy obtains relevant destination configuration from the SAP Destination service. It uses this destination to forward the request to the target system or to the Connectivity Proxy for On-Premise destinations. Consequently, your app does not interact with SAP Destination service or Connectivity service. This means your application do not require bindings to these two services, everything is handled by the Transparent Proxy.

Creating Transparent Proxy Destinations​

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

1. Destination​

Allows you to connect to a concrete SAP destination. Setting generic headers is allowed but dynamic properties like destination name or fragments is not. As a prerequisite, you have to create a Destination Custom Resource inside the Kubernetes cluster. For more information how to use the Transparent Proxy, refer to Using the Transparent Proxy.

TransparentProxyDestination destination = TransparentProxyDestination
    .destination(<destination-custom-resource-name>.<destination-custom-resource-namespace>)
    .header("X-Custom-Header", "custom-value")
    .property("some-property-key", "some-value")
    .build();
Destination Custom Resource access

<destination-custom-resource-namespace> can be omitted if the destination custom resource is created in the same namespace as the application workload.

2. Gateway​

Allows you to connect to arbitrary SAP destinations you have access to. As a prerequisite, you have to create a Gateway Destination Custom Resource inside the Kubernetes cluster. For more information how to use the Transparent Proxy for this concrete scenario, refer to Destination Gateway.

TransparentProxyDestination destination = TransparentProxyDestination
    .gateway("my-destination", <destination-custom-resource-name>.<destination-custom-resource-namespace>)
    .fragmentName("my-fragment")
    .build();

Tenant Configuration​

The SAP Cloud SDK automatically sets 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:

Destination​

// Using a fixed tenant ID (automatically set by SAP Cloud SDK if not specified) // alternatively, .tenantSubdomain("..") can be used, but only one of the two options may be set

TransparentProxyDestination destination = TransparentProxyDestination
    .destination(<destination-custom-resource-name>.<destination-custom-resource-namespace>)
    .tenantId("my-tenant-id")
    .build();

Gateway​

// Using a fixed tenant ID (automatically set by SAP Cloud SDK if not specified)
// alternatively, .tenantSubdomain("..") can be used, but only one of the two options may be set
TransparentProxyDestination destination = TransparentProxyDestination
    .gateway("my-destination", <destination-custom-resource-name>.<destination-custom-resource-namespace>)
    .tenantId("my-tenant-id")
    .build();

Authorization Header Configuration​

The SAP Cloud SDK automatically sets 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:

Destination​

TransparentProxyDestination destination = TransparentProxyDestination
    .destination(<destination-custom-resource-name>.<destination-custom-resource-namespace>)
    .authorization("Bearer my-token")
    .build();

Gateway​

TransparentProxyDestination destination = TransparentProxyDestination
    .gateway("my-destination", <destination-custom-resource-name>.<destination-custom-resource-namespace>)
    .authorization("Bearer my-token")
    .build();

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

Migration from Traditional Destinations​

Migrating from traditional destination configurations:

Before (Traditional Destination)​

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

After (Transparent Proxy - Gateway)​

TransparentProxyDestination destination = TransparentProxyDestination
    .gateway("my-destination", <destination-custom-resource-name>.<destination-custom-resource-namespace>)
    .build();
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);

After (Transparent Proxy - Destination)​

TransparentProxyDestination destination = TransparentProxyDestination
    .destination(<destination-custom-resource-name>.<destination-custom-resource-namespace>)
    .build();
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);

Troubleshooting​

Common Issues​

  1. Missing destination name for gateway: Ensure the destination name is provided as the first parameter to .gateway(<destination-name>, <destination-custom-resource-name>.<destination-custom-resource-namespace>)
  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, see Troubleshooting

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