SAP Business Technology Platform (BTP) offers a complete suite of tools and services to access on-premise systems such as SAP S/4HANA, SAP HANA On-Premise, any OData service, generic HTTP services, or any other service supporting the TCP/IP protocol. The SAP Cloud Application Programming Model (CAP) provides tools and guidance for developing and testing cloud services, prioritizing local development. The challenge of integrating on-premise services with a local CAP application development setup is where CAP’s value truly shines. The following blog serves as a comprehensive guide, detailing the steps to achieve this integration.
Install and configure the Cloud Connector
To establish a secure connection to on-premise services, it is essential to install the Cloud Connector within your local network environment. Ensure that the target on-premise system is accessible from this network, as the Cloud Connector will facilitate communication between your cloud applications and the on-premise services.
Cloud Connector installation
The Cloud Connector can be installed on variety of operating systems as described here.
Cloud Connector configuration
To facilitate the initial setup of connectivity between SAP BTP and the Cloud Connector, the authentication information has already been prepared. Download the authentication data file from your SAP BTP subbaccount:
- open your SAP BTP subaccount in your favourite browser
- navigate to "Cloud Connectors"
- press the button "Download Authentication Data"
Establish connection between Cloud Connector and your SAP BTP subaccount:
- open the Cloud Connector administration panel: https://localhost:8443/
- login with the default username and password: Administrator/manage, when prompted change the password following the instructions
- choose installation type: Master (Primary Installation) and provide description of your choice
- press "Add Subaccount" to connect to yout SAP BTP subaccount
- provide the internet proxy configuration if applicable and press "Next"
- choose "Configure using authentication data" and press "Next"
- choose "Add subaccount authentication data from file"
- press "Browse" and provide the previously downloaded authentication data file from your SAP BTP subaccount then press "Next"
- in the last dialog fill in the required information of your choice and press "Finish"
Your Cloud Connector is now available to your SAP BTP subaccount.
Let's expose the resources that need to be made visible in your SAP BTP subaccount:
- in the Cloud Connector Administration panel navigate to the connected subaccount
- choose "Cloud to On-Premise"
- in the "Access Control" tab press the Plus "+" button located in the header of the table "Mapping Virtual to Internal System"
- choose the type of the system to be exposed. In this guide a CAP OData endpoint will be used - choose "Non-SAP System"
- choose the appropriate protocol, in the current example it is "HTTP"
- provide internal host and port to expose, for example: "localhost" and "4004" and press "Next"
- choose "Allow Principal Propagation" if applicable
- select the Principal type, which is "Kerberos" by default
- choose which host to provide in the request header
- provide a description of your choice
- press "Finish"
The exposed host:port combination is now available, in addition resources must be exposed:
- in the Cloud Connector Administration panel navigate to the connected subaccount
- choose "Cloud to On-Premise"
- switch to tab "Access Control" in case it is not already selected by default
- in the table "Resources of localhost:4004" press the Plus "+" to add new resource
- provide the URL to expose, for example: "/" - the root path of the web server
- choose the "Access Policy", for example ""Path and All Sub-Paths" will allow access to any URL on that server
- press "Save"
The configuration is now complete. By checking the 'Cloud Connectors' in the relevant SAP BTP subaccount, you should see the already configured Cloud Connector and the exposed backend system, for example: 'localhost:4004'.
CAP Application setup
To access an on-premise backend system, the CAP application must utilize the destination and connectivity services provided by SAP BTP. If you don't already have a CAP application, you can easily set up a new one with the following command:
cds init sample --add sample && cd sample
Enable both destination and connectivity, and also deployment via mta with the following command:
cds add destination,connectivity,xsuaa,mta
Subsequent deployment will automatically create the required SAP BTP instances for the destination and connectivity services.
If you prefer to manually instantiate the destination and connectivity services, you can do so with the following commands:
cf create-service destination lite sample-destination
cf create-service-key sample-destination sample-destination-key
cf create-service connectivity lite sample-connectivity
cf create-service-key sample-connectivity sample-connectivity-key
To access the SAP BTP services locally in a hybrid development environment, bind the necessary SAP BTP services. For connectivity, set the proxy host to localhost, as it defaults to an internally accessible SAP BTP hostname (see Overwrite Cloud Service Credentials):
npx cds bind --to sample-connectivity --credentials "{ \"onpremise_proxy_host\": \"localhost\" }"
npx cds bind --to sample-destination
npx cds bind --to sample-auth
Accessing systems via the connectivity service requires a destination with proxy type OnPremise. The destination can be either on subaccount level or instance based and can be created either via mta or manually in the SAP BTP destination service UI by providing the following parameters, where the host:port must be the same as the previously configured Cloud Connector (localhost:4004) :
Name: 'on-prem-dest'
Type: 'HTTP'
Authentication: 'NoAuthentication'
URL: 'http://localhost:4004'
ProxyType: 'OnPremise'
Description: 'on-premise destination'
Destinations can be created alternatively programmatically utilizing the Destination REST API:
- install the Cloud SDK http client, xsenv and xssec packages required to create the destination
npm i -D "@sap-cloud-sdk/http-client"
npm i -D "@sap/xsenv"
npm i -D "@sap/xssec"
- create a new file named createNewDestination.js with the following content:
(async () => {
const xsenv = require('@sap/xsenv')
const xssec = require('@sap/xssec')
const destinationCredentials = xsenv.serviceCredentials({ tag: 'destination' })
const xsuaaService = new xssec.XsuaaService(destinationCredentials)
const token = await xsuaaService.fetchClientCredentialsToken()
const { executeHttpRequest } = require('@sap-cloud-sdk/http-client')
const destinationName = 'on-prem-dest'
const data = JSON.stringify({
Name: destinationName,
Type: 'HTTP',
Description: 'on-prem destination',
URL: 'http://localhost:4004',
ProxyType: 'OnPremise',
Authentication: 'NoAuthentication'
})
try {
const response = await executeHttpRequest({
url: destinationCredentials.uri + "/destination-configuration/v1/instanceDestinations" },{
method: 'POST',headers: {
"Authorization": "Bearer " + token.access_token,
'X-CSRF-Token': 'None'},
data
})
console.log("Create destination", destinationName, response.status, response.statusText)
} catch(e) {
console.log("Failed to create destination", destinationName, e.status, e.response?.data)
}
})()
- run the newly created script file with SAP BTP service bindings using the command:
cds bind --exec node createNewDestination.js
In order to use that destination in a CAP application, a new service needs to be defined with the destination specified as parameter. Add the following configuration to your package.json file providing the name of the already created destination:
"cds": {
"requires": {
"OnPremService": {
"kind": "odata",
"credentials": {
"destination": "on-prem-dest"
}
}
}
}
The connectivity proxy port should be forwarded to SAP BTP via a ssh tunnel. In order to open a ssh connection to SAP BTP an already deployed microservice is required. In case you do not have one then an initial deployment can be performed via the following command:
cds up
In case there is no current CAP application to deploy, a newly created CAP app can serve that purpose:
cds init sample --add sample,xsuaa && cd sample && npx cds up
Open a ssh tunnel to the SAP BTP microservice with the connectivity proxy port forwarded with the command:
cf ssh sample-srv -L 20003:connectivityproxy.internal.cf.eu12.hana.ondemand.com:20003
The created destination was configured as an HTTP endpoint with port 4004. To test the destination, ensure the CAP service is running locally on port 4004. Start the CAP service with the SAP BTP services bound by executing the following command in the root directory of your CAP project:
PORT=4004 cds bind --exec cds-serve --profile hybrid
Perform an initial destination check via the Destinations UI in SAP BTP by selecting the destination and then pressing the 'Check Destination' button.
Setup validation
With the Cloud Connector instance running locally and connected to your SAP BTP subaccount, a reachable SAP BTP destination, the tunneled connectivity proxy, and the locally running CAP service, you can perform the final validation of the setup.
Create a new file named testOnPremSystem.js with the following content. Adapt the service name and resource path in the get method to match your specific case:
(async () => {
const cds = require ('@sap/cds')
const onPremService = await cds.connect.to("OnPremService")
try {
let res = await onPremService.get("/odata/v4/test/OnPremService")
console.log(res)
} catch(e) {
console.log(e)
}
})()
Run the test with service bindings:
cds bind --exec node testOnPremService.js
With everything configured and running, the CAP application can be extended with functionality to access an on-premise system.
An already preconfigured and functional example containing scripts to ease the validation of the scenario is available on github in the following repository: github: on-prem-connectivity-example .
Bluesky
