SAP BTP Destination Service
Centralised configuration management for all external system connections in SAP BTP. Destinations store connection URLs, authentication credentials, and proxy settings — enabling CAP and other BTP apps to connect to external systems without hardcoded configuration.
Executive Summary
The Destination Service is BTP's central registry for external system connection configurations. Instead of hardcoding URLs and credentials in application code, all connection details are stored as named Destinations — and applications look them up at runtime. This enables environment-specific configurations (one destination name, different URL per subaccount) and centralised credential management across all BTP applications.
Architecture & Configuration
- Service instance: created per subaccount (plan: lite) — bind to all applications that need external connectivity
- Destination types: HTTP, RFC (ABAP function modules), LDAP, Mail
- Authentication types: NoAuthentication, BasicAuthentication, OAuth2ClientCredentials, OAuth2SAMLBearerAssertion, PrincipalPropagation, ClientCertificateAuthentication
- Destination levels: subaccount-level (shared across all apps) or service-instance-level (app-specific scoping)
- Proxy types: Internet (direct), OnPremise (via Cloud Connector), PrivateLink
- CAP integration: .cdsrc.json [requires] section — CAP resolves Destination binding at runtime automatically
- App Router: uses Destinations for HTML5 application backend routing
- Destination REST API: programmatic read/write via OAuth2 client credentials
- Environment profiles: .cdsrc.json supports [production] and [development] credential blocks per destination name
Destination Configuration
This destination uses OAuth2SAMLBearerAssertion (principal propagation) via the Cloud Connector (OnPremise proxy). The token service URL points to the S/4HANA OAuth2 endpoint.
1// Destination configuration (set in BTP Cockpit or via API)
2{
3 "Name": "S4HANA_PROD",
4 "Type": "HTTP",
5 "URL": "https://s4hana-prod.corp.internal",
6 "Authentication": "OAuth2SAMLBearerAssertion",
7 "ProxyType": "OnPremise",
8 "audience": "https://s4hana-prod.corp.internal",
9 "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession",
10 "clientKey": "s4hana-oauth-client",
11 "tokenServiceURL": "https://s4hana-prod.corp.internal/sap/bc/sec/oauth2/token",
12 "tokenServiceUser": "OAUTH_CLIENT",
13 "tokenServicePassword": "<stored-securely>",
14 "HTML5.DynamicDestination": "true",
15 "WebIDEEnabled": "true",
16 "WebIDESystem": "S4H",
17 "WebIDEUsage": "odata_abap"
18}CAP Binding (.cdsrc.json)
CAP resolves the named destination at runtime using the Destination Service binding. Environment profiles allow the same service name to resolve to different backend systems per deployment environment.
1// .cdsrc.json — CAP service destination binding
2{
3 "requires": {
4 "API_SALES_ORDER_SRV": {
5 "kind": "odata-v2",
6 "model": "srv/external/API_SALES_ORDER_SRV",
7 "[production]": {
8 "credentials": {
9 "destination": "S4HANA_PROD",
10 "path": "/sap/opu/odata/sap/API_SALES_ORDER_SRV"
11 }
12 },
13 "[development]": {
14 "credentials": {
15 "destination": "S4HANA_DEV",
16 "path": "/sap/opu/odata/sap/API_SALES_ORDER_SRV"
17 }
18 }
19 }
20 }
21}[production] and [development] profile blocks let you use S4HANA_PROD in production and S4HANA_DEV in development without changing application code — just the deployment configuration.Destination API (Programmatic Access)
The Destination Service REST API enables CI/CD pipelines, Terraform, and operational scripts to read and validate destinations programmatically.
1# Read a destination programmatically
2# 1. Get access token
3TOKEN=$(curl -s -X POST \
4 "https://<subaccount>.authentication.eu10.hana.ondemand.com/oauth/token" \
5 -d "grant_type=client_credentials" \
6 -d "client_id=<client_id>" \
7 -d "client_secret=<client_secret>" | jq -r '.access_token')
8
9# 2. Read destination
10curl -s "https://destination-configuration.cfapps.eu10.hana.ondemand.com/destination-configuration/v1/destinations/S4HANA_PROD" \
11 -H "Authorization: Bearer $TOKEN" | jq .Enterprise Example (DEWA)
DEWA manages 23 Destinations across 4 production subaccounts. Each subaccount has its own S4HANA_PROD destination pointing to DEWA's S/4HANA 2023 system with different OAuth client keys per subaccount. OAuth2SAMLBearerAssertion enables SSO for all user-facing applications. 4 RFC destinations connect to legacy BAPIs that lack OData equivalents. Destination names follow the standard SYSTEM_ENV convention: S4HANA_PROD, ARIBA_PRD, FIELDGLASS_PRD. All destinations are managed via BTP CLI scripts stored in the team's infrastructure repository.
Security Considerations
Best Practices
Use SYSTEM_ENVIRONMENT convention (S4HANA_PROD, ARIBA_PRD, FIELDGLASS_PRD). Consistent names enable environment-based config switching in .cdsrc.json.
User-facing applications should use principal propagation — the logged-in user's identity flows to S/4HANA, enabling row-level access control and audit trail.
Scheduled jobs and integration scenarios that run without a user context should use OAuth2ClientCredentials — a dedicated service account identity.
Basic auth credentials are rotatable but credentials changes require destination updates. OAuth flows are more secure and support automatic token refresh.
Use BTP Terraform provider or BTP CLI scripts to manage destinations. Cockpit-only destinations are undocumented, unversioned, and hard to reproduce.