Skip to main content
Rate this page

Destinations

Many applications on SAP Business Technology Platform (SAP BTP) communicate with other systems, e.g. line of business solutions. SAP BTP provides the concept of destinations for convenient communication between SAP BTP and other systems. A destination is an object with the following information, among others:

Destinations are managed separately from applications on SAP BTP and can be retrieved through the destination service at runtime. The reasons to separate destinations and application are manifold:

  • You can securely store authentication information that should not be part of application code.
  • You can update resource locations without touching application code.
  • Different customers may want to configure different systems.
  • Multiple applications might want to access the same systems.

The SAP Cloud SDK helps you to authenticate against the destination service and retrieve destinations into your application.

The SAP Cloud SDK supports OData and OpenApi services. For both service types the execute() methods triggers a request to a target system:

//OData
const responseOData = await BusinessPartner.requestBuilder()
  .getAll()
  .execute(myDestination);
//OpenApi
const responseOpenApi = await MyApi.myFunction().execute(myDestination);

myDestination is an SAP Cloud SDK representation of a destination. The given request is executed against myDestination.

For the rest of the document, we will discuss the different options on destination lookup. All statements equally apply to OData and OpenAPI based services.

Creating Destinations Manually

You can construct a destination object manually and pass the destination information directly to the execute() method. The minimal requirement towards a manually constructed destination is that you provide a url.

.execute({ url: 'https://example.com'})

This, however, is not recommended for productive use as you would loose the benefits of separating destinations from applications.

Referencing Destinations by Name

Instead of defining your destination manually, you can reference it by a name:

.execute({ destinationName: 'myDestination' })

The SAP Cloud SDK searches for the destination by its name in the following locations and in the following order:

  1. local environment variables
  2. service binding environment variables
  3. SAP BTP's destination service

The search stops, once a destination is found. Therefore, if a destination with the same name exists in multiple locations, the destination that occurs earliest during the search takes precedence before other destinations with the same name.

Local Environment Variable

This option is present for deployment and testing in a local environment outside the SAP BTP where no destination services are available. If a destinations environment variable is present it will be used for the destination lookup as described above. The value is expected to be a stringified JSON array, where the items adhere to the Destination interface. Example: "[{name: 'TESTINATION', url: 'http://url.hana.ondemand.com', username: 'DUMMY', password: 'dummy'}]".

The SAP Cloud SDK provides a setTestDestination(destination) function to add a destination to the environment variable for the current process programmatically. It takes a destination object, transforms it to a JSON object, and adds it to process.env.destinations.

import { setTestDestination } from '@sap-cloud-sdk/test-util';

setTestDestination({
  authentication: 'NoAuthentication',
  name: 'TESTINATION',
  isTrustingAllCertificates: false,
  url: 'https://mys4hana.com'
});

This would set a destination with the name TESTINATION. At runtime, the SAP Cloud SDK will check the environment variable for a destination with the given name and use it if present. Note that the SAP Cloud SDK offers also a mockTestDestination() method, which reads in a systems.json and credentials.json to create destinations. The advantage of files is that they can be excluded from the repository since they contain sensitive information.

AuthToken Forwarding

Usually, the destination service should be used in production to fetch a destination including an authentication token. In the case of frequent service to service communication, requesting the destination service every time for a target-specific JWT would mean a big overhead.

In such a case you can configure your destination targets to accept the initial request JWT and use this for all further calls. This makes the call to the destination service for a target-specific token redundant. If you configured your target system in such a way, you put a destination in the local environment variables to stop the lookup right away. Include the forwardAuthToken to the destination configuration and your initial JWT will be forwarded directly as Authorization header to the target systems without an extra round trip to the destination service. You can use the setTestDestination() method to set the destination in the environment variables:

setTestDestination({
  name: 'FORWARD-DESTINATION',
  url: 'https://mys4hana.com',
  forwardAuthToken: true
});

MyReqeust.execute({ destinationName: 'myDestination', jwt: 'forwardedJwt' });

Note that this approach is not suitable for multi-tenant scenarios, because only the destination service can return destinations for different tenants.

Service Binding Environment Variables

The service credentials, in other words VCAP_SERVICES environment variables, may contain a destination. If you want to use this information, the name of the service instance must be provided as the destination name. Currently, two services types are supported out of the box business-logging and s4-hana-cloud with the following transformation functions:

//business-logging
(serviceBinding) => {
    url: serviceBinding.credentials.writeUrl,
    authentication: 'OAuth2ClientCredentials',
    username: serviceBinding.credentials.uaa.clientid,
    password: serviceBinding.credentials.uaa.clientsecret
};

//s4-hana-cloud
(serviceBinding) => {
    url: serviceBinding.credentials.URL,
    authentication: 'BasicAuthentication',
    username: serviceBinding.credentials.User,
    password: serviceBinding.credentials.Password
};

Destination Service

In a productive environment, you will use a Destination service to retrieve destinations.

Authentication and JSON Web Token Retrieval

To access the destination service, the SAP Cloud SDK will first fetch an access token from the XSUAA service. The token retrieved from the XSUAA service is used to make a call to the destination service and receive the destinations. The destination service returns a destination with all relevant authentication information depending on the used authentication flow:

  • PrincipalPropagation
  • NoAuthentication
  • BasicAuthentication
  • OAuth2SAMLBearerAssertion
  • OAuth2UserTokenExchange
  • OAuth2ClientCredentials
  • OAuth2Password
  • ClientCertificateAuthentication
  • OAuth2JWTBearer

The SAP Cloud SDK automatically parses the response of the destination service and uses the provided authentication information for the request to the target system. For a simple service, this would be the end of the story.

Multi-Tenancy

However, the destination service is special in a way that it is a tenant aware service. Such services make it possible to build multi-tenant applications. So, what defines a tenant aware service?

Assume you want to build a simple application showing the 5 newest business-partner in an SAP S/4HANA system. You want to offer this application as a service to customers. Of course, you want to make this service cost-efficient and host it only once and let multiple customers use it. This leads now naturally to the requirement that your service needs to return the data related to the specific customers. A customer is represented by an account on the SAP BTP and a service considering the account is a tenant aware service.

Tenant aware services on the SAP BTP are offered to customers via a subscription which works on a high level as follows: If a customer wants to use a service, a subscription is created linking the customer account and the one account hosting the service. In the following the term subscriber account will be used for the accounts using a service and provider account for the one hosting it.

After this little definition detour, let's go back to the destination service and the SAP Cloud SDK. For simplicity an optional argument of the destination lookup has been neglected in the beginning:

.execute({destinationName: 'myDestination', jwt: 'yourJWT'})

The jwt argument takes the JSON web token (JWT) issued by an XSUAA as input. This token contains a field zid holding the tenant id which will be used in the lookup process. The lookup process done by the SAP Cloud SDK involves the following steps:

  • Request an access token for the destination service and a given tenant id from the XSUAA.
  • Due to the subscription between provider and subscriber, the XSUAA is allowed to issue the token.
  • The token allows for calling the destination service on behalf of the given tenant. The tenant and service information is encoded in the access token.
  • Make a call to the destination service using the obtained access token.
  • The destination maintained in the given tenant are returned.

If no token is given or the destination is not found in the subscriber account the provider account is used as a fallback. To control this fallback behavior a selection strategy can be passed to the destination lookup:

.execute({destinationName: 'myDestination', jwt: 'yourJWT'}, {selectionStrategy:'alwaysSubscriber'})

There are three selection strategies defined in the SAP Cloud SDK: alwaysSubscriber, alwaysProvider and subscriberFirst. The selection strategy can be passed as an optional argument to the .execute() method. The default value is subscriberFirst. The selection strategies can be used to control for which account a destination lookup is attempted:

  • AlwaysSubscriber: Only try to get destinations from the subscriber account. A valid JWT is mandatory to receive something.
  • AlwaysProvider: Only try to get destination from the provider account. A JWT is not needed. Even if you present a subscriber JWT the provider destination will be returned if present.
  • SubscriberFirst: Tries to get from the subscriber first using the JWT. If no valid JWT is provided or the destination is not found it tries the provider as described for AlwaysProvider.
note

One aspect has been left out for simplicity. In principle, it is possible to define destinations not only on the account level but also on the destination service level. These destinations are called instance destinations since they are tied to a service binding called instance on SAP BTP. In every request, these destinations are added to the destinations returned by the destination service.

Destination Lookup Without a JSON Web Token

There are situations where you do not have a JWT issued by the XSUAA but need to look a destination up e.g. in background processes. In such situations the property iss of the DestinationAccessorOptions can be used:

.execute(
  { destinationName: 'myDestination' },
  { iss: yourIssuerValue }
)

The value for iss is supposed to be the same as in a JWT issued from the XSUAA e.g. https://yourSubdomain.localhost:8080/uaa/oauth/token. In principle only the host of the URL is relevant but since the same parsing and replacement methods are used for the JWT handling, the URL has to be provided in the format above.

note

If a JWT is used in the destination lookup, a validation of the provided token is performed. This validation ensures that the JWT has not been manipulated. If only the iss is provided no such validation is performed. Note that the given subdomain value defines from which tenant destinations are fetched. So a wrong value may break the isolation for tenants. It is your responsibility as a developer to ensure that the provided value for the iss property is valid.

Additional Headers and Query Parameters on Destinations

The destination service has a convention to define static headers and query parameters on destinations. Create additional properties in your destination in the SAP BTP cockpit and define their values as follows:

  • URL.headers.<header-key> for headers
  • URL.queries.<query-key> for query parameters

Replace <header-key> and <query-key> with the name of your headers or query parameters and set the respective values.

Additional properties on destination

In the example above, the destination has an apiKey header with the value <my-api-key> and a language query parameter with the value EN.

The SAP Cloud SDK adds those additional headers and query parameters for every communication with the given destination.

Rules of Precedence

The SAP Cloud SDK adds headers and query parameters from different sources. Some sources take precedence over others (highest to lowest):

  1. custom: headers/query parameters added to a request directly
  2. additional properties: headers/query parameters defined on a destination
  3. internal: headers/query parameters built by the SAP Cloud SDK

Headers or query parameters built by the SAP Cloud SDK are overwritten by additional headers and query parameters on the destination. Custom headers and query parameters, however, overwrite the additional properties.

note

Header names keep their casing but overwrite other headers independent of casing, e.g. AUTHORIZATION overwrites authorization. This does not apply to query parameter names`.

Rate this page