connectivity_service.pdf
0 likes111 views
This document provides an overview of SAP BTP Connectivity for applications in the Cloud Foundry environment. It describes the Connectivity and Destination services that provide connectivity functionality, connectivity scenarios including connecting applications and HANA databases to on-premise systems, and user roles. The document also references sections on initial setup, developing applications, monitoring, security and the Cloud Connector component.
![1 Connectivity
SAP BTP Connectivity: overview, features, restrictions.
Note
This documentation refers to SAP BTP, Cloud Foundry environment. If you are looking for information
about the Neo environment, see Connectivity for the Neo Environment.
Content
In this Topic
Hover over the elements for a description. Click an element for more information.
● Overview [page 4]
● Features [page 4]
● Restrictions [page 5]
In this Guide
Hover over the elements for a description. Click an element for more information.
● Connectivity in the Cloud Foundry Environment [page 7]
● Cloud Connector [page 267]
● Connectivity Support [page 581]
SAP BTP Connectivity
Connectivity PUBLIC 3](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-3-320.jpg)
![Overview
SAP BTP Connectivity allows SAP BTP applications to securely access remote services that run on the Internet
or on-premise. This component:
● Allows subaccount-specific configuration of application connections via destinations.
● Provides a Java API that application developers can use to consume remote services.
● Allows you to make connections to on-premise systems, using the Cloud Connector.
● Lets you establish a secure tunnel from your on-premise network to applications on SAP BTP, while you
keep full control and auditability of what is exposed to the cloud.
● Supports both the Neo and the Cloud Foundry environment for application development on SAP BTP.
A typical scenario for connectivity from your on-premise network to SAP BTP looks like this:
● Your company owns a global account on SAP BTP and one or more subaccounts that are assigned to this
global account.
● Using SAP BTP, you subscribe to or deploy your own applications.
● To connect to these applications from your on-premise network, the Cloud Connector administrator sets
up a secure tunnel to your company's subaccount on SAP BTP.
● The platform ensures that the tunnel can only be used by applications that are assigned to your
subaccount.
● Applications assigned to other (sub)accounts cannot access the tunnel. It is encrypted via transport layer
security (TLS), which guarantees connection privacy.
Back to Content [page 3]
Features
4 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-4-320.jpg)
![SAP BTP Connectivity supports the following protocols and scenarios:
Protocol Scenario
HTTP(S) Exchange data between your cloud application and Internet
services or on-premise systems.
● Create and configure HTTP destinations to make Web
connections.
● Connect to on-premise systems via HTTP, using the
Cloud Connector.
RFC Invoke on-premise ABAP function modules via RFC.
● Create and configure RFC destinations.
● Make connections to back-end systems via RFC, using
the Cloud Connector.
TCP Access on-premise systems via TCP-based protocols using a
SOCKS5 proxy.
Back to Content [page 3]
Restrictions
General [page 5]
Protocols [page 6]
Cloud Foundry Environment [page 6]
Cloud Connector [page 7]
Note
For information about general SAP BTP restrictions, see Prerequisites and Restrictions.
General
SAP BTP Connectivity
Connectivity PUBLIC 5](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-5-320.jpg)
![Topic Restriction
Java Connector To develop a Java Connector (JCo) application for RFC com
munication, your SDK local runtime must be hosted by a 64-
bit JVM, on a x86_64 operating system (Microsoft Windows
OS, Linux OS, or Mac OS X).
On Windows platforms, you must install the Microsoft Vis
ual Studio C++ 2013 runtime libraries (vcredist_x64.exe),
see Visual C++ Redistributable Packages for Visual Studio
2013 .
Ports For Internet connections, you are allowed to use any port
>1024. For cloud to on-premise solutions there are no port
limitations.
Destination Configuration ● You can use destination configuration files with exten
sion .props, .properties, .jks, and .txt, as
well as files with no extension.
● If a destination configuration consists of a keystore or
truststore, it must be stored in JKS files with a stand
ard .jks extension.
Back to Restrictions [page 5]
Protocols
For the cloud to on-premise connectivity scenario, the following protocols are currently supported:
Protocol Info
HTTP HTTPS is not needed, since the tunnel used by the Cloud
Connector is TLS-encrypted.
RFC You can communicate with SAP systems down to SAP R/3
release 4.6C. Supported runtime environment is SAP Java
Buildpack with a minimal version of 1.8.0.
TCP You can use TCP-based communication for any client that
supports SOCKS5 proxies.
Back to Restrictions [page 5]
Cloud Foundry Environment
Topic Restriction
Service Channels Service channels are supported only for SAP HANA data
base, see Using Service Channels [page 482].
E-Mail E-mail functions are not supported.
Back to Restrictions [page 5]
6 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-6-320.jpg)
![Cloud Connector
Topic Restriction
Scenarios To learn in which system landscapes you can set up the
Cloud Connector, see Extended Scenarios [page 271].
Installation To check all software and hardware restrictions for working
with the Cloud Connector, see Prerequisites [page 274].
Back to Restrictions [page 5]
Back to Content [page 3]
Related Information
Connectivity in the Cloud Foundry Environment [page 7]
Cloud Connector [page 267]
Connectivity via Reverse Proxy [page 579]
Connectivity Support [page 581]
1.1 Connectivity in the Cloud Foundry Environment
Consuming SAP BTP Connectivity for your application in the Cloud Foundry environment: Overview.
Note
This documentation refers to SAP BTP, Cloud Foundry environment. If you are looking for information
about the Neo environment, see Connectivity for the Neo Environment.
Hover over the elements for a description. Click an element for more information.
SAP BTP Connectivity
Connectivity PUBLIC 7](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-7-320.jpg)
![● What Is SAP BTP Connectivity? [page 8]
● What's New for Connectivity [page 14]
● Initial Setup [page 38]
● Monitoring and Troubleshooting [page 266]
● Security [page 266]
● Developing Applications [page 164]
1.1.1 What Is SAP BTP Connectivity?
Use SAP BTP Connectivity for your application in the Cloud Foundry environment: available services,
connectivity scenarios, user roles.
Content
Hover over the elements for a description. Click an element for more information.
● Services [page 8]
● Scenarios [page 9]
● User Roles [page 9]
Services
SAP BTP Connectivity provides two services for the Cloud Foundry environment, the Connectivity service and
the Destination service.
The Destination service and the Connectivity service together provide virtually the same functionality that is
included in the Connectivity service of the Neo environment.
In the Cloud Foundry environment however, this functionality is split into two separate services:
● The Connectivity service provides a connectivity proxy that you can use to access on-premise resources.
● Using the Destination service, you can retrieve and store the technical information about the target
resource (destination) that you need to connect your application to a remote service or system.
You can use both services together as well as separately, depending on the needs of your specific scenario.
Back to Content [page 8]
8 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-8-320.jpg)
![Scenarios
● Use the Connectivity service to connect your application or an SAP HANA database to on-premise
systems:
○ Set up on-premise communication via HTTP or RFC for your cloud application.
○ Use a service channel to connect to an SAP HANA database on SAP BTP from your on-premise
system, see Configure a Service Channel for an SAP HANA Database [page 483].
● Use the Destination service:
○ To retrieve technical information about destinations that are required to consume the Connectivity
service (optional), or
○ To provide destination information for connecting your Cloud Foundry application to any other Web
application (remote service). This scenario does not require the Connectivity service.
Back to Content [page 8]
User Roles
In this document, we refer to different types of user roles – responsibility roles and technical roles.
Responsibility roles describe the required user groups and their general tasks in the end-to-end setup process.
Configuring technical roles, you can control access to the dedicated cloud management tools by assigning
specific permissions to users.
Responsibility Roles [page 9]
Technical Roles [page 10]
Responsibility Roles
The end-to-end use of the Connectivity service and the Destination service requires these user groups:
● Application operators - are responsible for productive deployment and operation of an application on SAP
BTP. Application operators are also responsible for configuring the remote connections (destination and
trust management) that an application might need, see Initial Setup [page 38].
● Application developers - develop a connectivity-enabled SAP BTP application by consuming the
Connectivity service and/or the Destination service, see Developing Applications [page 164].
● IT administrators - set up the connectivity to SAP BTP in your on-premise network, using the Cloud
Connector [page 267].
Some procedures on the SAP BTP can be done by developers as well as by application operators. Others may
include a mix of development and operation tasks. These procedures are labeled using icons for the respective
task type.
SAP BTP Connectivity
Connectivity PUBLIC 9](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-9-320.jpg)
![Task Types
Operator Developer Operator and/or Devel
oper
Technical Roles
To perform connectivity tasks in the Cloud Foundry environment, the following technical roles apply:
Technical Roles [Feature Set A] [page 10]
Technical Roles [Feature Set B] [page 11]
Note
To apply the correct technical roles, you must know on which cloud management tools feature set (A or B)
your account is running. For more information on feature sets, see Cloud Management Tools — Feature Set
Overview.
Technical Roles [Feature Set A]
Technical Connectivity Roles and Operations [Feature Set A]
Level
Operation (SAP BTP Cockpit or Cloud
Connector) Role
Subaccount Connect a Cloud Connector to a sub
account (Cloud Connector)
One of these roles:
● Global Account member
See Add Members to Your Global
Account.
● Security Administrator (must be
Global Account member or Cloud
Foundry Org/Space member)
See Managing Security Adminis
trators in Your Subaccount [Fea
ture Set A].
Disconnect a Cloud Connector (cock
pit)
View Cloud Connectors connected to a
subaccount (cockpit)
Manage destinations (all CRUD opera
tions) on subaccount level (cockpit)
View destinations (read operations) on
subaccount level (cockpit)
Manage certificates (all CRUD opera
tions) on subaccount level (cockpit)
View certificates (read operations) on
subaccount level (cockpit)
Generate or renew the subaccount
key pair for trust management (cock
pit)
Download the subaccount key pair for
trust management (cockpit)
10 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-10-320.jpg)
![Level
Operation (SAP BTP Cockpit or Cloud
Connector) Role
Service instance Manage destinations (all CRUD opera
tions) on service instance level (cock
pit)
One of these roles:
● Org Manager
● Space Manager
● Space Developer
See User and Member Management.
View destinations (read operations) on
service instance level (cockpit)
Manage certificates (all CRUD opera
tions) on service instance level (cock
pit)
View certificates (read operations) on
service instance level (cockpit)
Back to Technical Roles [page 10]
Back to User Roles [page 9]
Technical Roles [Feature Set B]
Feature set B provides dedicated roles for specific operations. They can be assigned to custom role
collections, but some of them are also available in default role collections.
Technical Connectivity Roles and Operations [Feature Set B] [page 11]
Default Role Collections [Feature Set B] [page 13]
Note
To see the Destination editor, you must have at least the Destination Viewer role or both the Destination
Configuration Viewer and the Destination Certificate Viewer roles.
Technical Connectivity Roles and Operations [Feature Set B]
Level
Operation (SAP BTP Cockpit or Cloud
Connector) Role
Subaccount Connect a Cloud Connector to a sub
account (Cloud Connector)
Cloud Connector Administrator
Manage destinations (all CRUD opera
tions) on subaccount level (cockpit)
One of these roles:
● Destination Administrator
● Destination Configuration Adminis
trator
View destinations (read operations) on
subaccount level (cockpit)
One of these roles:
● Destination Viewer
● Destination Configuration Viewer
SAP BTP Connectivity
Connectivity PUBLIC 11](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-11-320.jpg)
![Level
Operation (SAP BTP Cockpit or Cloud
Connector) Role
Manage certificates (all CRUD opera
tions) on service instance level (cock
pit)
One of these roles:
● Destination Administrator
● Destination Certificate Administra
tor
plus one of these roles:
● Org Manager
● Space Manager
● Space Developer
See User and Member Management.
View certificates (read operations) on
service instance level (cockpit)
One of these roles:
● Destination Viewer
● Destination Certificate Viewer
plus one of these roles:
● Org Manager
● Space Manager
● Space Developer
See User and Member Management.
Back to Technical Roles [Feature Set B] [page 11]
Default Role Collections [Feature Set B]
Default Role Collection Connectivity Roles Included
Subaccount Administrator ● Cloud Connector Administrator
● Destination Administrator
Subaccount Viewer ● Cloud Connector Auditor
● Destination Viewer
Cloud Connector Administrator Cloud Connector Administrator
Destination Administrator Destination Administrator
Connectivity and Destination Administrator ● Cloud Connector Administrator
● Destination Administrator
Back to Technical Roles [Feature Set B] [page 11]
Back to Technical Roles [page 10]
Back to User Roles [page 9]
Back to Content [page 8]
SAP BTP Connectivity
Connectivity PUBLIC 13](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-13-320.jpg)
![Related Information
What's New for Connectivity [page 14]
Initial Setup [page 38]
Developing Applications [page 164]
Security [page 266]
Monitoring and Troubleshooting [page 266]
Security Administration: Managing Authentication and Authorization
1.1.2 What's New for Connectivity
Find the latest features, enhancements and bug fixes for SAP BTP Connectivity .
What's New for Connectivity
Related Information
2020 Connectivity (Archive) [page 14]
2019 Connectivity (Archive) [page 23]
2018 Connectivity (Archive) [page 30]
2017 Connectivity (Archive) [page 34]
1.1.2.1 2020 Connectivity (Archive)
14 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-14-320.jpg)
![Techni
cal
Com
ponent
Capa
bility
Envi
ron
ment Title Description Type
Availa
ble as
of
Con
nectiv
ity
Integra
tion
Neo
Cloud
Foun
dry
Cloud
Con
nector
En
hance
ments
Release of Cloud Connector 2.11.3:
● If the user sapadm exists on a system, the installation on Li
nux assigns it to the sccgroup, which is a prerequisite for sol
ution management integration to work properly, see Config-
ure Solution Management Integration [page 494].
● Restoring a backup has been improved. See Configuration
Backup [page 498].
● The HTTP session store size has been reduced. You can han
dle higher loads with a given heap size.
● Cipher suite configuration has been improved. Also, there is a
new security status entry for cipher suites, see Recommen
dations for Secure Setup [page 299].
Chang
ed
2018-1
2-06
Con
nectiv
ity
Integra
tion
Neo HTTP
Desti
nations
The OAuth2 Client Credentials grant type is supported by the
Destinations editor in the SAP Cloud Platform cockpit as well as by
the client Java APIs ConnectivityConfiguration,
AuthenticationHeaderProvider and
HttpDestination, available in SAP Cloud Platform Neo run
times.
See OAuth Client Credentials Authentication.
Chang
ed
2018-1
0-11
Con
nectiv
ity
Integra
tion
Cloud
Foun
dry
User
Propa
gation
The connectivity service supports the SaaS application subscrip
tion flow and can be declared as a dependency in the get depend
encies subscription callback, also via MTA (multi-target)-bundled
applications.
See Consuming the Connectivity Service (Cloud Foundry Environ
ment) and Configure Principal Propagation via User Exchange To
ken (Cloud Foundry Environment).
Chang
ed
2018-0
9-27
Con
nectiv
ity
Integra
tion
Neo
Cloud
Foun
dry
Cloud
Con
nector
2.11.2
Release of Cloud Connector 2.11.2
● SNC configuration now provides the value of the environment
variable SECUDIR, which you need for the usage of the SAP
Cryptographic Library (SAPCRYPTOLIB). See Initial Configu-
ration (RFC).
● On Linux, the RPM (Red Hat Package Manager) now ensures
that the configuration of the interaction with the SAP Host
Agent (used for the Solution Manager integration) is ad
justed. See Configure Solution Management Integration.
● The Cloud Connector shadow instance now provides a config-
uration option for the connection and request timeout that
may occur during health check against the master instance.
See Master and Shadow Administration.
Chang
ed
2018-0
8-16
SAP BTP Connectivity
Connectivity PUBLIC 33](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-33-320.jpg)
![28 September 2017 - Connectivity
New
The destination service (Beta) is available in the Cloud Foundry environment. See Consuming the Destination Service
[page 189].
3 August 2017 - Connectivity
Enhancement
Cloud Connector
Release of SAP Cloud Platform Cloud Connector 2.10.1.
● The URLs of HTTP requests can now be longer than 4096 bytes.
● SAP Solution Manager can be integrated with one click of a button if the host agent is installed on a Cloud Connec
tor machine. See the Solution Management section in Monitoring [page 516].
● The limitation that only 100 subaccounts could be managed with the administration UI has been removed. See Man
aging Subaccounts [page 328].
Fix
Cloud Connector
● The regression of 2.10.0 has been fixed, as principal propagation now works for RFC.
● The cloud user store works with group names that contain a backslash () or a slash (/).
● Proxy challenges for NT LAN Manager (NTLM) authentication are ignored in favor of Basic authentication.
● The back-end connection monitor works when using a JVM 7 as a runtime of Cloud Connector.
SAP BTP Connectivity
Connectivity PUBLIC 35](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-35-320.jpg)
![25 May 2017 - Connectivity
Enhancement
Cloud Connector
Release of SAP HANA Cloud connector 2.10.0.1
● Support of connectivity to an SAP Cloud Platform Cloud Foundry environment.
● Support of direct connectivity with S/4HANA Cloud systems. You can open a Service Channel to an S/4HANA Cloud
system in order to use Communication Scenarios requiring RFC communication to S/4HANA Cloud. See Configure
a Service Channel for RFC [page 487].
● Support of arbitrary protocols via the possibility to configure a TCP access control entry. SAP Cloud Platform Con
nectivity is offering a SOCKS5 proxy, with which you can address such exposed hosts. See Using the TCP Protocol
for Cloud Applications.
● Support for disaster recovery events of SAP Cloud Platform regions. For each subaccount you can configure a dis
aster recovery subaccount for a disaster region. In case of a disaster, the disaster recovery account can be switched
active immediately using the exact same configuration. See Configure a Disaster Recovery Subaccount [page 336].
● In the access control settings you can add further constraints for RFC based communication to ABAP systems: an
administrator can configure, which clients shall be exposed and can define which users should not be able to access
the system via Cloud Connector. See Configure Access Control (RFC) [page 377].
● You can generate self-signed certificates for CA and system certificate so that you can setup demo scenarios with
principal propagation without the need of using lengthy openSSL or keytool command sequences. See Configure a
CA Certificate for Principal Propagation [page 344] and Initial Configuration (HTTP) [page 319].
● A first set of monitoring HTTP APIs have been introduced: The state of all subaccount connections, a back-end con
nection monitor and a performance overview monitor. See Monitoring APIs [page 524].
● On Windows platforms, Cloud Connector 2.10 now requires Visual Studio 2013 runtime libraries.
Fix
Cloud Connector
● The is no longer a bottleneck that could lengthen the processing times of requests to exposed back-end systems,
after many hours under high load when using principal propagation, connection pooling, and many concurrent ses
sions.
● Session management is no longer terminating early active sessions in principal propagation scenarios.
● On Windows 10 hardware metering in virtualized environments shows hard disk and CPU data.
11 May 2017 - Connectivity
New
In case the remote server supports only TLS 1.2, use this property to ensure that your scenario will work. As TLS 1.2 is
more secure than TLS 1.1, the default version used by HTTP destinations, consider switching to TLS 1.2.
36 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-36-320.jpg)
![30 March 2017 - Connectivity
Enhancement
The release of SAP Cloud Platform Cloud Connector 2.9.1 includes the following improvements:
● UI renovations based on collected customer feedback. The changes include rounding offs, fixes of wrong/odd be
haviors, and adjustments of controls. For example, in some places tables were replaced by sap.ui.table.Table for bet
ter experience with many entries.
● You can trigger the creation of a thread dump from the Log and Trace Files view.
● The connection monitor graphic for idle connections was made easier to understand.
Fix
● When configuring authentication for LDAP, the alternate host settings are no longer ignored.
● The email configuration for alerts is processing correctly the user and password for access to the email server.
● Some servers used to fail to process HTTP requests when using the HTTP proxy approach (HTTP Proxy for On-
Premise Connectivity) on the SAP Cloud Platform side.
● A bottleneck was removed that could lengthen the processing times of requests to exposed back-end systems un
der high load when using principal propagation.
● The Cloud Connector accepts passwords that contain the '§' character when using authentication-mode password.
16 March 2017 - Connectivity
Enhancement
Update of JCo runtime for SAP Cloud Platform. See Connectivity [page 3].
Fix
A java.lang.NullPointerException might have occurred when using a JCoRepository instance in
roundtrip optimization mode (will be used if the JCo property jco.use_repository_roundtrip_optimization was set to 1 at
its creation time). The NullPointerException was either thrown when trying to execute a JCoFunction object,
which has been created by such a repository instance, or even earlier when querying the meta data for a JCoFunction,
JCoFunctionTemplate or a JCoRecordMetaData object from an AS ABAP back-end system. Only certain complex data
structures and table parameter definitions were affected by this bug.
Older Release Notes
● 2016
● 2015
● 2014
SAP BTP Connectivity
Connectivity PUBLIC 37](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-37-320.jpg)
![● 2013
1.1.3 Initial Setup
Manage destinations and authentication for applications in the Cloud Foundry environment.
Task Description
Managing Destinations [page 38] Manage HTTP destinations for Cloud Foundry applications in
the SAP BTP cockpit.
HTTP Destinations [page 64] You can choose from a broad range of authentication types
for HTTP destinations, to meet the requirements of your
specific communication scenario.
RFC Destinations [page 110] Use RFC destinations to communicate with an on-premise
ABAP system via the RFC protocol.
Principal Propagation [page 121] Use principal propagation (user propagation) to securely for
ward cloud users to a back-end system (single sign-on).
Set up Trust Between Systems [page 124] Download and configure X.509 certificates as a prerequisite
for user propagation from the Cloud Foundry environment to
the Neo environment or to a remote system outside SAP
BTP, like S/4HANA Cloud, C4C, Success Factors, and oth
ers.
Multitenancy in the Connectivity Service [page 156] Manage destinations for multitenancy-enabled applications
that require a connection to a remote service or on-premise
application.
Create and Bind a Connectivity Service Instance [page 159] To use the Connectivity service in your application, you must
first create and bind an instance of the service.
Create and Bind a Destination Service Instance [page 161] To use the Destination service in your application, you must
first create and bind an instance of the service.
1.1.3.1 Managing Destinations
To manage destinations for your application, choose a procedure that fits best your requirements.
There are various ways to manage destinations. Each method is characterized by different prerequisites and
limitations. Before choosing a method, you should evaluate them and decide which one is the most appropriate
for your particular scenario. The following table compares the available methods:
38 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-38-320.jpg)
![Method
Create
from
Scratch
Create
from Tem
plate
Create
from File
(Import)
Save to File
(Export) Update Delete Clone
Check Con
nection
Using the
Destina
tions Editor
in the Cock
pit [page
39]
Yes Yes Yes Yes Yes Yes Yes Yes
Destination
Service
REST API
[page 59]
Yes No Yes Yes Yes Yes No No
Create Des
tinations
Using the
MTA De
scriptor
[page 59]
Yes Limited No No Yes No No No
Create Des
tinations on
Service In
stance Cre
ation [page
63]
Yes No No No Yes No No No
1.1.3.1.1 Using the Destinations Editor in the Cockpit
Use the Destinations editor in the SAP BTP cockpit to configure HTTP, RFC or mail destinations in the Cloud
Foundry environment.
The Destinations editor lets you manage destinations on subaccount or service instance level.
You can use a destination to:
● Connect your Cloud Foundry application to the Internet (via HTTP), as well as to an on-premise system
(via HTTP or RFC).
● Send and retrieve e-mails, configuring a mail destination.
● Create a destination for subscription-based scenarios, pointing to your service instance. For more
information, see Destinations Pointing to Service Instances [page 51].
Prerequisites
1. You are logged into the SAP BTP cockpit.
2. You have the required authorizations. See User Roles [page 9].
SAP BTP Connectivity
Connectivity PUBLIC 39](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-39-320.jpg)
![3. Make sure the following is fulfilled:
○ Service instance level – you must have created a Destination service instance, see Create and Bind a
Destination Service Instance [page 161].
○ Subaccount level – no specific prerequisites.
For more information, see Access the Destinations Editor [page 40].
Restrictions
● A destination name must be unique for the current application. It must contain only alphanumeric
characters, underscores, and dashes. The maximum length is 200 characters.
● The currently supported destination types are HTTP, RFC and MAIL.
○ HTTP Destinations [page 64] - provide data communication via the HTTP protocol and are used for
both Internet and on-premise connections.
○ RFC Destinations [page 110] - make connections to ABAP on-premise systems via RFC protocol using
the Java Connector (JCo) as API.
○ Mail destinations - specify an e-mail provider for sending and retrieving e-mails.
Tasks
● Create Destinations from Scratch [page 42]
● Create Destinations from a Template [page 51]
● Check the Availability of a Destination [page 53]
● Clone Destinations [page 54]
● Edit and Delete Destinations [page 55]
● Use Destination Certificates [page 56]
● Import Destinations [page 57]
● Export Destinations [page 58]
Related Information
Destination Examples [page 48]
1.1.3.1.1.1 Access the Destinations Editor
Access the Destinations Editor in the SAP BTP cockpit to create and manage destinations in the Cloud Foundry
environment.
40 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-40-320.jpg)
![You can edit destinations at two different levels:
● Subaccount level
● Service instance level
On subaccount level, you can specifiy a destination for the entire subaccount, defining the used
communication protocol and more properties, like authentication method, proxy type and URL.
On service instance level, you can reuse this destination for a specific space and adjust the URL if required. You
can also create a new destination only on service instance level that is specific to the selected service instance
and its assigned applications.
Prerequisites
● You are logged into the SAP BTP cockpit.
● You have the required authorizations. See User Roles [page 9].
Procedure
Access on Subaccount Level
1. In the cockpit, select your Global Account and your subaccount name from the Subaccount menu in the
breadcrumbs.
2. From the left-side panel, choose Connectivity Destinations .
Access on Service Instance Level
Note
To perform these steps, you must have created a Destination service instance in your space, see Create and
Bind a Destination Service Instance [page 161]. On service instance level, you can set destinations only for
Destination service instances.
1. In the cockpit, choose your Global Account from the Region Overview and select a Subaccount.
Note
The Cloud Foundry Organization must be enabled.
2. From the Spaces section, select a space name.
3. From the left-side menu, choose Services Service Instances .
4. Choose the Actions icon for a Destination service instance and select View Dashboard.
SAP BTP Connectivity
Connectivity PUBLIC 41](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-41-320.jpg)
![5. On the Destinations screen, you can create new destinations or edit existing ones.
See also section Create and Bind a Service Instance from the Cockpit in Create and Bind a Destination Service
Instance [page 161].
Related Information
Create Destinations from Scratch [page 42]
Create Destinations from a Template [page 51]
Check the Availability of a Destination [page 53]
Clone Destinations [page 54]
Edit and Delete Destinations [page 55]
Use Destination Certificates [page 56]
Import Destinations [page 57]
Export Destinations [page 58]
1.1.3.1.1.2 Create Destinations from Scratch
Use the Destinations editor in the SAP BTP cockpit to configure destinations from scratch.
Configuring destinations from scratch provides the complete set of editing functions. While this requires
deeper technical knowledge of the scenario and the required connection configuration, it is the most flexible
procedure and lets you create any type of supported destination.
42 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-42-320.jpg)
![To Create Destinations from a Template [page 51], in contrast, you do not need this deeper knowledge for
configuration, but edting options are limited by the available templates.
Related Information
Create HTTP Destinations [page 43]
Create RFC Destinations [page 44]
Create Mail Destinations [page 46]
Destination Examples [page 48]
1.1.3.1.1.2.1 Create HTTP Destinations
Create HTTP destinations in the Destinations editor (SAP BTP cockpit).
Prerequisites
You have logged into the cockpit and opened the Destinations editor.
Procedure
1. Choose New Destination.
Note
In section Destination Configuration, do not change the default tab Blank Template, unless you want
to create a destination for a specific service instance in a subscription-based scenario. For more
information, see Destinations Pointing to Service Instances [page 51].
2. Enter a destination name.
3. From the <Type> dropdown menu, choose HTTP.
4. The <Description> field is optional.
5. Specify the destination URL.
6. From the <Proxy Type> dropdown box, select Internet or OnPremise, depending on the connection
you need to provide for your application.
Note
For more information, see also HTTP Destinations [page 64].
SAP BTP Connectivity
Connectivity PUBLIC 43](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-43-320.jpg)
![7. From the <Authentication> dropdown box, select the authentication type you need for the connection.
For details, see HTTP Destinations [page 64].
Note
If you set an HTTPS destination, you need to also add a Trust Store. For more information, see Use
Destination Certificates [page 56].
8. (Optional) If you are using more than one Cloud Connector for your subaccount, you must enter the
<Location ID> of the target Cloud Connector.
See also Managing Subaccounts [page 328] (section Procedure, step 4).
9. (Optional) You can enter additional properties.
a. In the Additional Properties panel, choose New Property.
b. Enter a key (name) or choose one from the dropdown menu and specify a value for the property. You
can add as many properties as you need.
c. To delete a property, choose the button next to it.
Note
For a detailed description of specific properties for SAP Business Application Studio (formerly known
as SAP Web IDE), see Connecting to External Systems.
10. When you are ready, choose the Save button.
Related Information
Edit and Delete Destinations [page 55]
Destination Examples [page 48]
1.1.3.1.1.2.2 Create RFC Destinations
How to create RFC destinations in the Destinations editor (SAP BTP cockpit).
Prerequisites
You have logged into the cockpit and opened the Destinations editor.
44 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-44-320.jpg)
![Procedure
1. Choose New Destination.
Note
In section Destination Configuration, do not change the default tab Blank Template. Tab Service
Instance only applies for HTTP destinations.
2. Enter a destination name.
3. From the <Type> dropdown menu, choose RFC.
4. The <Description> field is optional.
5. From the <Proxy Type> dropdown box, select Internet or OnPremise, depending on the connection
you need to provide for your application.
Note
Using <Proxy Type> Internet , you can connect your application to any target service that is
exposed to the Internet. <Proxy Type> OnPremise requires the Cloud Connector to access
resources within your on-premise network.
6. Enter credentials for <User> and <Password>.
7. (Optional) Enter an <Alias User> name. See also User Logon Properties [page 111].
8. (Optional) Enter credentials for <Repository User> and <Repository Password>, if you want to use
a different user for repository lookups. See also Repository Configuration [page 115].
9. (Optional) If you are using more than one Cloud Connector for your subaccount, you must enter the
<Location ID> of the target Cloud Connector.
See also Managing Subaccounts [page 328] (section Procedure, step 4).
10. Depending on the proxy type of your RFC destination, specify at least the following JCo properties in
section Additional Properties.
a. In the Additional Properties panel, choose New Property.
b. Add each required property from the dropdown menu and specify its value:
Proxy Type Property Description
OnPremise Load Balancing Connections
jco.client.r3name Three-letter system ID of your back
end ABAP system (as configured in
the Cloud Connector).
jco.client.mshost Message server host (as configured in
the Cloud Connector).
jco.client.group (Optional) The group of application
servers that is used (logon group). If
not specified, the group PUBLIC is
used.
SAP BTP Connectivity
Connectivity PUBLIC 45](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-45-320.jpg)
![Proxy Type Property Description
jco.client.client Three-digit ABAP client number (de
fines the client of the target ABAP sys
tem).
Direct Connections
jco.client.ashost Application server name of your tar
get ABAP system (as configured in
the Cloud Connector).
jco.client.sysnr Instance number of the application
server (as configured in the Cloud
Connector).
jco.client.client Three-digit ABAP client number (de
fines the client of the target ABAP sys
tem).
Internet jco.client.wshost WebSocket RFC server host on which
the target ABAP system is running.
The system must be exposed to the
Internet.
jco.client.wsport WebSocket RFC server port on which
the target ABAP system is listening.
jco.client.client Three-digit ABAP client number (de
fines the client of the target ABAP sys
tem).
For a detailed description of RFC-specific properties (JCo properties), see RFC Destinations [page 110].
11. Press Save.
Related Information
Edit and Delete Destinations [page 55]
Destination Examples [page 48]
Cloud Connector [page 267]
1.1.3.1.1.2.3 Create Mail Destinations
Create mail destinations in the Destinations editor (SAP BTP cockpit).
Prerequisites
You have logged into the cockpit and opened the Destinations editor.
46 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-46-320.jpg)
![Procedure
1. Choose New Destination.
Note
In section Destination Configuration, do not change the default tab Blank Template. Tab Service
Instance only applies for HTTP destinations.
2. Enter a destination name.
3. From the Type dropdown menu, choose MAIL.
4. The Description field is optional.
5. Specify the destination URL.
6. From the Proxy Type dropdown box, select Internet or OnPremise, depending on the connection you
need to provide for your application.
Note
To access a mail server located in your own network (via Cloud Connector), choose OnPremise. To
access an external mail server, choose Internet.
7. Optional: You can enter additional properties.
a. In the Additional Properties panel, choose New Property.
b. Enter a key (name) or choose one from the dropdown menu and specify a value for the property. You
can add as many properties as you need. Each key of an additional property must start with "mail.".
c. To delete a property, choose the button next to it.
8. When you are ready, choose the Save button.
Related Information
Edit and Delete Destinations [page 55]
Destination Examples [page 48]
Cloud Connector [page 267]
SAP BTP Connectivity
Connectivity PUBLIC 47](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-47-320.jpg)
![1.1.3.1.1.2.4 Destination Examples
Find configuration examples for HTTP and RFC destinations in the Cloud Foundry environment, using different
authentication types.
Content
HTTP Destination (Internet, Client Certificate Authentication) [page 48]
HTTP Destination (Internet, OAuth2SAMLBearerAssertion) [page 49]
HTTP Destination (On-Premise) [page 49]
RFC Destination [page 50]
Mail Destination (Internet) [page 50]
Mail Destination (On-Premise) [page 50]
Example: HTTP Destination (Internet, Client Certificate Authentication)
Back to Content [page 48]
48 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-48-320.jpg)
![Example: HTTP Destination (Internet, OAuth2SAMLBearerAssertion)
Back to Content [page 48]
Example: HTTP Destination (On-Premise)
Back to Content [page 48]
SAP BTP Connectivity
Connectivity PUBLIC 49](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-49-320.jpg)
![Example: RFC Destination
The following main properties correspond to the relevant additional properties:
User → jco.client.user
Password → jco.client.passwd
Repository password → jco.destination.repository.passwd
Note
For security reasons, do not use these additional properties but use the corresponding main properties'
fields.
Back to Content [page 48]
Example: Mail Destination (Internet)
Back to Content [page 48]
Example: Mail Destination (On-Premise)
50 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-50-320.jpg)
![Back to Content [page 48]
Related Information
HTTP Destinations [page 64]
RFC Destinations [page 110]
1.1.3.1.1.3 Create Destinations from a Template
Use a template to configure destinations with scenario-specific input data in the SAP BTP cockpit.
If you want to create several destinations for a common scenario, you can use a template that provides the
scenario-specific input data. The Destination service uses the template to configure the destinations
accordingly.
Currently, the following template ist available for destination configuration:
Destinations Pointing to Service Instances [page 51]
1.1.3.1.1.3.1 Destinations Pointing to Service Instances
Create a destination for subscription-based scenarios that points to your service instance.
Note
This feature is applicable for a selected set of the most commonly used services (from a Destination
service perspective). If you would like to use this feature for a service which is not yet supported, let us
know by opening a support ticket, see Connectivity Support [page 581].
In the meantime, you can follow the steps described in Create Destinations from Scratch [page 42].
Usually, in the Cloud Foundry environment, you consume service instances by binding them to your
applications. However, in subscription-based scenarios this is not always possible. If you have purchased a
subscription to an SaaS application that runs in a provider's subaccount, you cannot bind your service instance
to this application.
SAP BTP Connectivity
Connectivity PUBLIC 51](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-51-320.jpg)
![In this case, you must create a destination that points to your service instance. Applications can consume this
destination through a subscription to gain access to your service instance.
If you create such a destination from scratch, you must provide a service key for your instance, look up the
credentials, and enter these values in the newly created destination.
Using the Destinations Pointing to Service Instances template, you only have to select the corresponding
service instance.
Note
This procedure only applies for HTTP destinations on subaccount level.
Prerequisites
● You have a service instance which you want to make accessible to applications you are subscribed to.
● You have the Space Developer role in the space where this service instance resides.
● You have logged in to the cockpit and opened the Destinations editor on subaccount level. See Access the
Destinations Editor [page 40].
Procedure
1. Choose New Destination.
2. Select the tab Service Instance in the Destination Configuration section.
3. In the <Service Instance> dropdown list, you find all the service instances, grouped by space, where
you have the role Space Developer.
4. Select a service instance.
5. Give the destination configuration a name and, optionally, a description.
6. (Optional) You can specify additional properties.
7. Choose Next.
A service key for that service instance is automatically generated, using the naming convention
<service_instance_name>-service-key. If the key name already exists, it is reused. A new destination with
pre-filled fields is previewed, using the given service instance data. Do not change the values of these
fields.
8. If you want to create a destination with these values, choose Save. Otherwise, choose Cancel.
Result
You have a destination pointing to your service instance. If you delete this service instance or its service key, the
destination stops working.
52 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-52-320.jpg)
![Error Messages for OnPremise Destinations
Error Message Reason Action
Backend status could not be deter
mined.
● The Cloud Connector version is
less than 2.7.1.
● The Cloud Connector is not con
nected to the subaccount.
● The backend returns an HTTP sta
tus code above or equal to 500
(server error).
● The Cloud Connector is not config-
ured properly.
● Upgrade the Cloud Connector to
version 2.7.1 or higher.
● Connect the Cloud Connector to
the corresponding subaccount.
● Check the server status (availabil
ity) of the backend system.
● Check the basic Cloud Connector
configuration steps:
Initial Configuration [page 312]
Backend is not available in the list of de
fined system mappings in Cloud
Connector.
The Cloud Connector is not configured
properly.
Check the basic Cloud Connector con
figuration steps:
Initial Configuration [page 312]
Resource is not accessible in Cloud
Connector or backend is not reachable.
The Cloud Connector is not configured
properly.
Check the basic Cloud Connector con
figuration steps:
Initial Configuration [page 312]
Backend is not reachable from Cloud
Connector.
Cloud connector configuration is ok but
the backend is not reachable.
Check the backend (server) availability.
1.1.3.1.1.5 Clone Destinations
How to clone destinations in the Destinations editor (SAP BTP cockpit).
Prerequisites
You have previously created or imported an HTTP destination in the Destinations editor of the cockpit.
Procedure
1. In the Destinations editor, go to the existing destination which you want to clone.
2. Choose the icon.
54 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-54-320.jpg)
![3. The editor automatically creates and opens a new destination that contains all the properties of the
selected one.
4. You can modify some parameters if you need.
5. When you are ready, choose the Save button.
Related Information
Export Destinations [page 58]
Destination Examples [page 48]
1.1.3.1.1.6 Edit and Delete Destinations
How to edit and delete destinations in the Destinations editor (SAP BTP cockpit).
Prerequisites
You have previously created or imported an HTTP destination in the Destinations editor of the cockpit.
Procedure
● Edit a destination:
1. To edit a created or imported destination, choose the button.
2. You can edit the main parameters as well as the additional properties of a destination.
3. Choose the Save button. The changes will take effect in up to five minutes.
Tip
For complete consistency, we recommend that you first stop your application, then apply your
destination changes, and then start again the application. Also, bear in mind that these steps will
cause application downtime.
● Delete a destination:
To remove an existing destination, choose the button. The changes will take effect in up to five minutes.
Related Information
Export Destinations [page 58]
SAP BTP Connectivity
Connectivity PUBLIC 55](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-55-320.jpg)
![Destination Examples [page 48]
1.1.3.1.1.7 Use Destination Certificates
Maintain truststore and keystore certificates in the Destinations editor (SAP BTP cockpit).
Prerequisites
You have logged into the cockpit and opened the Destinations editor. For more information, see Access the
Destinations Editor [page 40].
Context
You can upload, add and delete certificates for your connectivity destinations. Bear in mind that:
● You can only use JKS, PFX and P12 files for destination key store, and JKS, CRT, CER, DER for destination
trust store.
● You can add certificates only for HTTPS destinations. Truststore can be used for all authentication types.
Keystore is available only for ClientCertificateAuthentication and
OAuth2SAMLBearerAssertion.
● An uploaded certificate file should contain the entire certificate chain.
Procedure
Uploading Certificates
1. Choose the Certificates button.
2. Choose Upload Certificate.
3. Browse to the certificate file you need to upload.
The certificate file is added.
Note
You can upload a certificate during creation or editing of a destination, by clicking the Upload and Delete
Certificates link.
56 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-56-320.jpg)
![Adding Certificates to Destinations
1. Create a new destination, or open an existing one for editing.
2. In the URL field, enter an HTTPS address.
3. You can use the default JDK truststore or select another one from the dropdown menu. If the menu is
empty, you can upload a certificate on the fly. To omit this property, you can set TrustAll=true.
4. If you choose Authentication = ClientCertificateAuthentication, you need to also provide a
keystore.
Deleting Certificates
1. Choose the Certificates button or click the Upload and Delete Certificates link.
2. Select the certificate you want to remove and choose Delete Selected.
3. Upload another certificate, or close the Certificates window.
More Information
Create HTTP Destinations [page 43]
Edit and Delete Destinations [page 55]
Import Destinations [page 57]
1.1.3.1.1.8 Import Destinations
How to import destinations in the Destinations editor (SAP BTP cockpit).
Prerequisites
You have previously created an HTTP destination.
Note
The Destinations editor allows importing destination files with extension .props, .properties, .jks,
and .txt, as well as files with no extension. Destination files must be encoded in ISO 8859-1 character
encoding.
SAP BTP Connectivity
Connectivity PUBLIC 57](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-57-320.jpg)
![Procedure
1. Log into the cockpit and open the Destinations editor.
2. Choose Import from File.
3. Browse to a configuration file that contains destination configuration.
○ If the configuration file contains valid data, it is displayed in the Destinations editor with no errors. The
Save button is enabled so that you can successfully save the imported destination.
○ If the configuration file contains invalid properties or values, under the relevant fields in the
Destinations editor are displayed error messages in red which prompt you to correct them accordingly.
Related Information
Edit and Delete Destinations [page 55]
Destination Examples [page 48]
1.1.3.1.1.9 Export Destinations
Export destinations from the Destinations editor in the SAP BTP cockpit to backup or reuse a destination
configuration.
Prerequisites
You have created a destination in the Destinations editor.
Procedure
1. Log into the cockpit and open the Destinations editor.
2. Select a destination and choose the button.
3. Browse to the location on your local file system where you want to save the new destination.
○ If the destination does not contain client certificate authentication, it is saved as a single configuration
file.
○ If the destination provides client certificate data, it is saved as an archive, which contains the main
configuration file and a JKS file.
58 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-58-320.jpg)
![Related Information
Edit and Delete Destinations [page 55]
Destination Examples [page 48]
1.1.3.1.2 Destination Service REST API
Destination service REST API specification for the SAP Cloud Foundry environment.
The Destination service provides a REST API that you can use to read and manage destinations and certificates
on all available levels. This API is documented in the SAP API Business Hub .
It shows all available endpoints, the supported operations, parameters, possible error cases and related status
codes, etc. You can also execute requests using the credentials (for example, the service key) of your
Destination service instance, see Create and Bind a Destination Service Instance [page 161].
1.1.3.1.3 Create Destinations Using the MTA Descriptor
Use the multitarget-application (MTA) descriptor to manage destinations for complex deployments.
Content
● Concept [page 59]
● Content Deployment [page 60]
● Create a Destination on Service Instance Creation [page 63]
Concept
When modeling a multitarget application (MTA), you can create and update destinations from your MTA
descriptor.
For more information on MTA, see Multitarget Applications in the Cloud Foundry Environment.
Back to Content [page 59]
SAP BTP Connectivity
Connectivity PUBLIC 59](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-59-320.jpg)
![This option lets you:
● Reference a service instance and a service key
● Specify a destination name
● Enter a description for the resulting destination (optional)
● Add additional properties and override default properties (optional)
As a result, a destination is created, based on the properties in the referenced service key.
Note
This function is equivalent to the Destinations Pointing to Service Instances [page 51] template.
Caution
This feature is applicable for a selected set of the most commonly used services (from a Destination
service perspective). If you would like to use this feature for a service which is not yet supported, let us
know by opening a support ticket, see Connectivity Support [page 581].
In the meantime, you can follow the steps described in Create Destinations from Scratch [page 42].
The descriptor has the following structure:
Name: <name> # name of the destination
Description: <description> # optional, a description for the destination
Authentication: <auth> # optional for some services (the default is service
specific). Some services require the Authentication to be specified, like the
workflow service. The allowed authentication types are also service-specific
ServiceInstanceName: <instance name> # the name of the service instance to which
the destination will be created
ServiceKeyName: <service key name> # the service key of the instance targeted by
ServiceInstanceName which will be used as the source for the destination values
AdditionalProp1: value1 # optional
...
AdditionalPropN: valueN # optional
Destination Pointing to a Resource Protected by an XSUAA Service Instance
This option lets you:
● Reference a service instance and a service key
● Specify a destination name
● Enter a description for the resulting destination (optional)
● Specify the URL of the target resource
● Add additional properties and override default properties (optional)
As a result, a destination is created with the token service configuration based on the properties in the
referenced service key, while the URL will be the one specified when modeling the destination.
The descriptor has the following structure:
Name: <name> # name of the destination
Description: <description> # optional, a description for the destination
SAP BTP Connectivity
Connectivity PUBLIC 61](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-61-320.jpg)
![type: org.cloudfoundry.managed-service
parameters:
service: xsuaa
service-name: xsuaa_service
service-plan: application
config:
xsappname: "myApp"
- name: workflow_service
type: org.cloudfoundry.managed-service
parameters:
service: workflow
service-name: workflow_service
service-plan: lite
- name: destination-service
type: org.cloudfoundry.managed-service
parameters:
service: destination
service-name: my-destination-service
service-plan: lite
Back to Content [page 59]
Create a Destination on Service Instance Creation
The MTA descriptor lets you create service instances and provide a JSON configuration for this operation. You
can use this functionality to create a Destination service instance with a JSON, and include the required data to
create or update destinations.
For more details, see Use a Config.JSON to Create or Update a Destination Service Instance [page 163].
Back to Content [page 59]
1.1.3.1.4 Create Destinations on Service Instance Creation
Use a JSON to create or update a destination when creating a Destination service instance.
When creating or updating a service instance of the Destination service, you can provide a JSON object with
various configurations. One of the sections of this JSON lets you create or update destinations. Other
operations, like deleting a destination, are not supported by this method.
For more information, see Use a Config.JSON to Create or Update a Destination Service Instance [page 163].
SAP BTP Connectivity
Connectivity PUBLIC 63](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-63-320.jpg)
![1.1.3.2 HTTP Destinations
Find information about HTTP destinations for Internet and on-premise connections (Cloud Foundry
environment).
Destination Levels
The runtime tries to resolve a destination in the order: Subaccount Level → Service Instance Level.
Destinations for Subscribed Applications
In subscription-based scenarios, it is not always possible to consume a service instance by binding it to your
application. In this case, you must create a destination pointing to your service instance. For more information,
see Destinations Pointing to Service Instances [page 51].
Proxy Types
The proxy types supported by the Connectivity service are:
● Internet - The application can connect to an external REST or SOAP service on the Internet.
● OnPremise - The application can connect to an on-premise back-end system through the Cloud
Connector.
The proxy type used for a destination is specified by the destination property ProxyType. The default value is
Internet.
Proxy Settings for Your Local Runtime
If you work in your local development environment behind a proxy server and want to use a service from the
Internet, you need to configure your proxy settings on JVM level. To do this, proceed as follows:
1. On the Servers view, double-click the added server and choose Overview to open the editor.
2. Click the Open Launch Configuration link.
3. Choose the (x)=Arguments tab page.
4. In the VM Arguments box, add the following row:
-Dhttp.proxyHost=yourproxyHost -Dhttp.proxyPort=yourProxyPort -
Dhttps.proxyHost=yourproxyHost -Dhttps.proxyPort=yourProxyPort
5. Choose OK.
6. Start or restart your SAP HANA Cloud local runtime.
64 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-64-320.jpg)
![Configuring Authentication
When creating an HTTP destination, you can use different authentication types for access control:
● Server Certificate Authentication [page 65]
● Principal Propagation SSO Authentication [page 68]
● OAuth SAML Bearer Assertion Authentication [page 70]
● Client Authentication Types for HTTP Destinations [page 77]
● OAuth Client Credentials Authentication [page 80]
● OAuth User Token Exchange Authentication [page 86]
● SAP Assertion SSO Authentication [page 91]
● OAuth Password Authentication [page 96]
● OAuth JWT Bearer Authentication [page 100]
● SAML Assertion Authentication [page 105]
Related Information
OAuth with X.509 Client Certificates [page 109]
Create HTTP Destinations [page 43]
1.1.3.2.1 Server Certificate Authentication
Create and configure a Server Certificate destination for an application in the Cloud Foundry environment.
Context
The server certificate authentication is applicable for all client authentication types, described below.
Note
TLS 1.2 became the default TLS version of HTTP destinations. If an HTTP destination is consumed by a java
application the change will be effective after restart. All HTTP destinations that use the HTTPS protocol and
have ProxyType=Internet can be affected. Previous TLS version can be used by configuring an additional
property TLSVersion=TLSv1.0 or TLSVersion=TLSv1.1.
SAP BTP Connectivity
Connectivity PUBLIC 65](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-65-320.jpg)
![Property Description
HostnameVerifier Optional property. It has two values: Strict and BrowserCompatible. This
property specifies how the server hostname matches the names stored inside the
server's X.509 certificate. This verifying process is only applied if TLS or SSL pro
tocols are used and is not applied if the TrustAll property is specified. The de
fault value (used if no value is explicitly specified) is Strict.
● Strict HostnameVerifier works in the same way as Oracle Java 1.4,
Oracle Java 5, and Oracle Java 6-rc. It is also similar to Microsoft Internet Ex
plorer 6. This implementation appears to be compliant with RFC 2818 for
dealing with wildcards. A wildcard such as "*.foo.com" matches only subdo
mains at the same level, for example "a.foo.com". It does not match deeper
subdomains such as "a.b.foo.com".
● BrowserCompatible HostnameVerifier works in the same way as
Curl and Mozilla Firefox. The hostname must match either the first common
name (CN) or any of the subject-alts. A wildcard can occur in the CN and in
any of the subject-alts.
The only difference between BrowserCompatible and Strict is that a wild
card (such as ".foo.com") with BrowserCompatible matches all subdomains,
including "a.b.foo.com".
For more information about these Java classes, see Package
org.apache.http.conn.ssl .
In case <TrustAll> = TRUE, the <HostnameVerifier> property is ignored so
you can omit it.
Note
You can upload trust store JKS files using the same command as for uploading destination configuration
property files. You only need to specify the JKS file instead of the destination configuration file.
Note
Connections to remote services which require Java Cryptography Extension (JCE) unlimited strength
jurisdiction policy are not supported.
Configuration
● Managing Destinations [page 38]
Related Information
Client Authentication Types for HTTP Destinations [page 77]
SAP BTP Connectivity
Connectivity PUBLIC 67](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-67-320.jpg)
![1.1.3.2.2 Principal Propagation SSO Authentication
Forward the identity of a cloud user from a Cloud Foundry application to a backend system to enable single
sign-on (SSO).
Context
A PrincipalPropagation destination enables single sign-on (SSO) by forwarding the identity of a cloud user to
the Cloud Connector, and from there to the target on-premise system. In this way, the cloud user's identity can
be provided without manual logon.
Note
This authentication type applies only for on-premise connectivity.
Configuration Steps
You can create and configure a PrincipalPropagation destination by using the properties listed below, and
deploy it on SAP BTP. For more information, see Managing Destinations [page 38].
Properties
The following credentials need to be specified:
Property Description
Name Destination name. Must be unique for the destination level.
Type Destination type. Use HTTP for all HTTP(S) destinations.
URL Virtual URL of the protected on-premise application.
Authentication Authentication type. Use PrincipalPropagation as a
value.
ProxyType You can only use proxy type OnPremise.
CloudConnectorLocationId As of Cloud Connector 2.9.0, you can connect multiple
Cloud Connectors to a subaccount as long as their location
ID is different. The location ID specifies the Cloud
Connector over which the connection is opened. The
default value is an empty string identifying the Cloud
Connector that is connected without any location ID. This is
also valid for all Cloud Connector versions prior to 2.9.0.
68 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-68-320.jpg)
![Property Description
only provides the configured properties. The
expectation for the client-side processing logic is to
parse and use them. If you are using higher-level
libraries and tools, please check if they support this
convention.
Example
Name=OnPremiseDestination
Type=HTTP
URL= http://virtualhost:80
Authentication=PrincipalPropagation
ProxyType=OnPremise
Related Information
Principal Propagation [page 121]
1.1.3.2.3 OAuth SAML Bearer Assertion Authentication
Create and configure an OAuth SAML Bearer Assertion destination for an application in the Cloud Foundry
environment.
Context
You can call an OAuth2-protected remote system/API and propagate a user ID to the remote system by using
the OAuth2SAMLBearerAssertion authentication type. The Destination service provides functionality for
automatic token retrieval and caching, by automating the construction and sending of the SAML assertion.
This simplifies application development, leaving you with only constructing the request to the remote system
by providing the token, which is fetched for you by the Destination service. For more information, see User
Propagation via SAML 2.0 Bearer Assertion Flow [page 200].
70 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-70-320.jpg)
![Property Description
(Deprecated) SystemUser User to be used when requesting an access token from the
OAuth authorization server. If this property is not specified,
the currently logged-in user is used.
Caution
This property is deprecated and will be removed soon.
We recommend that you work on behalf of specific
(named) users instead of working with a technical user.
As an alternative for technical user communication, we
strongly recommend that you use one of these authenti
cation types:
● Basic Authentication (see Client Authentication
Types for HTTP Destinations [page 77])
● Client Certificate Authentication (see Client Au
thentication Types for HTTP Destinations [page
77])
● OAuth Client Credentials Authentication [page 80]
To extend an OAuth access token's validity, consider us
ing an OAuth refresh token.
authnContextClassRef Value of the AuthnContextClassRef tag, which is part
of generated OAuth2SAMLBearerAssertion authenti
cation. For more information, see SAML 2.0 specification .
Additional
nameQualifier Security domain of the user for which access token is re
quested.
companyId Company identifier.
assertionIssuer Issuer of the SAML assertion.
nameIdFormat Value of the NameIdFormat tag, which is part of gener
ated OAuth2SAMLBearerAssertion authentication.
For more information, see SAML 2.0 specification .
userIdSource When this property is set, the generated SAML2 assertion
uses the currently logged-in user as a value for the NameId
tag. See User Propagation via SAML 2.0 Bearer Assertion
Flow [page 200].
scope The value of the OAuth 2.0 scope parameter, expressed as a
list of space-delimited, case-sensitive strings.
SAP BTP Connectivity
Connectivity PUBLIC 73](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-73-320.jpg)
![audience=cubetree.com
nameQualifier=www.successfactors.com
apiKey=<apiKey>
The response for "find destination" contains an authTokens object in the format given below. For more
information on the fields in authTokens, see "Find Destination" Response Structure [page 196].
Sample Code
"authTokens": [
{
"type": "Bearer",
"value": "eyJhbGciOiJSUzI1NiIsInR5cC...",
"http_header": {
"key":"Authorization",
"value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..."
}
}
]
Related Information
Create HTTP Destinations [page 43]
Destination Examples [page 48]
Exchanging User JWTs via OAuth2UserTokenExchange Destinations [page 204]
1.1.3.2.4 Client Authentication Types for HTTP
Destinations
Find details about client authentication types for HTTP destinations in the Cloud Foundry environment.
Context
This section lists the supported client authentication types and the relevant supported properties.
No Authentication
This is used for destinations that refer to a service on the Internet or an on-premise system that does not
require authentication. The relevant property value is:
SAP BTP Connectivity
Connectivity PUBLIC 77](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-77-320.jpg)
![Authentication=NoAuthentication
Note
When a destination is using HTTPS protocol to connect to a Web resource, the JDK truststore is used as
truststore for the destination.
Basic Authentication
This is used for destinations that refer to a service on the Internet or an on-premise system that requires basic
authentication. The relevant property value is:
Authentication=BasicAuthentication
The following credentials need to be specified:
Property Description
User User name
Password Password
Preemptive If this property is not set or is set to TRUE (that is, the default behavior is to use
preemptive sending), the authentication token is sent preemptively. Otherwise, it
relies on the challenge from the server (401 HTTP code). The default value (used
if no value is explicitly specified) is TRUE. For more information about preemp
tiveness, see http:/
/tools.ietf.org/html/rfc2617#section-3.3 .
Note
When a destination is using the HTTPS protocol to connect to a Web resource, the JDK truststore is used as
truststore for the destination.
Note
Basic Authentication and No Authentication can be used in combination with
ProxyType=OnPremise. In this case, also the CloudConnectorLocationId property can be specified.
As of Cloud Connector 2.9.0, you can connect multiple Cloud Connectors to a subaccount as long as their
location ID is different. The value defines the location ID identifying the Cloud Connector over which the
connection shall be opened. The default value is the empty string identifying the Cloud Connector that is
connected without any location ID. This is also the case for all Cloud Connector versions prior to 2.9.0.
The response for "find destination" contains an authTokens object in the format given below. For more
information on the fields in authTokens, see "Find Destination" Response Structure [page 196].
78 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-78-320.jpg)
![ Sample Code
"authTokens": [
{
"type": "Basic",
"value": "dGVzdDpwYXNzMTIzNDU=",
"http_header": {
"key":"Authorization",
"value":"Basic dGVzdDpwYXNzMTIzNDU="
}
}
]
Client Certificate Authentication
This is used for destinations that refer to a service on the Internet. The relevant property value is:
Authentication=ClientCertificateAuthentication
The following credentials need to be specified:
Property Description
KeyStore.Source Optional. Specifies the storage location of the certificate to be used by the client.
Supported values are:
● ClientProvided: The key store is managed by the client (the application
itself).
● DestinationService: The key store is managed by the Destination
service.
If the property is not set, the key store is managed by the Destination service (de
fault).
KeyStoreLocation The name of the key store file that contains the client certificate(s) for client cer
tificate authentication against a remote server. This property is optional if
KeyStore.Source is set to ClientProvided.
KeyStorePassword Password for the key store file specified by KeyStoreLocation. This property
is optional if KeyStoreLocation is used in combination with
KeyStore.Source, and KeyStore.Source is set to ClientProvided.
Note
You can upload KeyStore JKS files using the same command for uploading destination configuration
property file. You only need to specify the JKS file instead of the destination configuration file.
SAP BTP Connectivity
Connectivity PUBLIC 79](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-79-320.jpg)
![Configuration
● Managing Destinations [page 38]
Related Information
Server Certificate Authentication [page 65]
1.1.3.2.5 OAuth Client Credentials Authentication
Create and configure an OAuth2ClientCredentials destination to consume OAuth-protected resources from a
Cloud Foundry application.
SAP BTP supports applications to use the OAuth client credentials flow for consuming OAuth-protected
resources.
The client credentials are used to request an access token from an OAuth authorization server.
Note
The retrieved access token is cached and auto-renovated. When a token is about to expire, a new token is
created shortly before the expiration of the old one.
Configuration Steps
You can create and configure an OAuth2ClientCredentials destination using the properties listed below, and
deploy it on SAP BTP. To create and configure a destination, follow the steps described in Managing
Destinations [page 38].
Properties
The table below lists the destination properties required for the OAuth2ClientCredentials authentication type.
Property Description
Required
Name Destination name. Must be unique for the destination level.
80 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-80-320.jpg)
![Property Description
tokenServiceURL.queries.<query-key> A static key prefix used as a namespace grouping of
tokenServiceUrl's query parameters. Its values will be
sent to the token service during token retrieval. For each
query paramester's key you must add a 'tokenServi
ceURL.queries' prefix separated by dot delimiter. For exam
ple:
Sample Code
{
...
"tokenServiceURL.queries.<query-
key-1>" : "<query-value-1>",
...
"tokenServiceURL.queries.<query-
key-N>": "<query-value-N>",
}
tokenService.KeyStoreLocation Contains the name of the certificate configuration to be
used. This property is required when using client certificates
for authentication. See OAuth with X.509 Client Certificates
[page 109].
tokenService.KeyStorePassword Contains the password for the certificate configuration (if
one is needed) when using client certificates for authentica
tion. See OAuth with X.509 Client Certificates [page 109].
82 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-82-320.jpg)
![Property Description
URL.queries.<query-key> A static key prefix used as a namespace grouping of URL's
query parameters whose values will be sent to the target
endpoint. For each query parameter's key, you must add a
URL.queries prefix separated by dot-delimiter. For exam
ple:
Sample Code
{
...
"URL.queries.<query-key-1>" :
"<query-value-1>",
...
"URL.queries.<query-key-N>":
"<query-value-N>",
}
Note
This is a naming convention. As the call to the target
endpoint is performed on the client side, the service
only provides the configured properties. The expecta
tion for the client-side processing logic is to parse and
use them. If you are using higher-level libraries and
tools, please check if they support this convention.
Note
When the OAuth authorization server is called, it accepts the trust settings of the destination, see Server
Certificate Authentication [page 65].
When using an SAP BTP Neo OAuth service (https://api.{landscape-domain}/oauth2/apitoken/v1?
grant_type=client_credentials or oauthasservices.{landscape-domain}/oauth2/
apitoken/v1?grant_type=client_credentials) as TokenServiceURL, or any other OAuth token
service which accepts client credentials only as authorization header, you must set the clientId and
clientSecret values also for the tokenServiceUser and tokenServicePassword properties.
Example: Neo OAuth Token Service
Sample Code
URL=https://api.{landscape-domain}/desired-service-path
Name=sapOAuthCC
TrustAll=true
84 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-84-320.jpg)
![ProxyType=Internet
Type=HTTP
Authentication=OAuth2ClientCredentials
tokenServiceURL=(https://api.{landscape-domain}/oauth2/apitoken/v1?
grant_type=client_credentials
tokenServiceUser=clientIdValue
tokenServicePassword=secretValue
clientId=clientIdValue
clientSecret=secretValue
Example: OAuth Token Service Accepting Client Credentials as Body
Sample Code
URL=https://demo.sapjam.com/OData/OData.svc
Name=sap_jam_odata
TrustAll=true
ProxyType=Internet
Type=HTTP
Authentication=OAuth2ClientCredentials
tokenServiceURL=http://demo.sapjam.com/api/v1/auth/token
tokenServiceUser=tokenserviceuser
tokenServicePassword=pass
clientId=clientId
clientSecret=secret
Example: AuthTokens Object Response
The response for "find destination" contains an authTokens object in the format given below. For more
information on the fields in authTokens, see "Find Destination" Response Structure [page 196].
Sample Code
"authTokens": [
{
"type": "Bearer",
"value": "eyJhbGciOiJSUzI1NiIsInR5cC...",
"http_header": {
"key":"Authorization",
"value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..."
}
}
]
SAP BTP Connectivity
Connectivity PUBLIC 85](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-85-320.jpg)
![1.1.3.2.6 OAuth User Token Exchange Authentication
Learn about the OAuth2UserTokenExchange authentication type for HTTP destinations in the Cloud Foundry
environment: use cases, supported properties and ways to retrieve an access token in an automated way.
Content
Overview [page 86]
Properties [page 86]
Example: AuthTokens Object Response [page 90]
Overview
When a user is logged into an application that needs to call another application and pass the user context, the
caller application must perform a user token exchange.
The user token exchange is a sequence of steps during which the initial user token is handed over to the
authorization server and, in exchange, another access token is returned.
The calling application first receives a refresh token out of which the actual user access token is created. The
resulting user access token contains the user and tenant context as well as technical access metadata, like
scopes, that are required for accessing the target application.
Using the OAuth2UserTokenExchange authentication type, the Destination service performs all these steps
automatically, which lets you simplify your application development in the Cloud Foundry environment.
Back to Content [page 86]
Properties
To configure a destination of this type, you must specify all the required properties. You can create destinations
of this type via the cloud cockpit (Access the Destinations Editor [page 40]) or the Destination Service REST
API [page 59].
The following table shows the required properties along with their semantics.
86 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-86-320.jpg)
![Field/Parameter JSON Key Input/Description
Required
URL URL URL of the target endpoint.
Token
Service URL
tokenServi
ceURL
The URL of the token service, against which the token exchange is performed. De
pending on the Token Service URL Type, this property is interpreted in dif
ferent ways during the automatic token retrieval:
● For Dedicated, the token service URL is taken as is.
● For Common, the token service URL is searched for the tenant placeholder
{tenant}.
{tenant} is resolved as the subdomain of the subaccount on behalf of which
the caller is performing the call. If the placeholder is not found, {tenant} is
inserted as a subdomain of the token service URL.
See Automated Access Token Retrieval [page 205] for information about how
the tenant is determined.
The subaccount subdomain is mandated during creation of the subaccount,
see Create a Subaccount.
Examples of interpreting the token service URL for the token service URL type
Common, if the call to the Destination service is on behalf of a subaccount subdo
main with value mytenant:
● https://authentication.us10.hana.ondemand.com/oauth/
token → https://
mytenant.authentication.us10.hana.ondemand.com/oauth/
token
● https://
{tenant}.authentication.us10.hana.ondemand.com/oauth/
token → https://
mytenant.authentication.us10.hana.ondemand.com/oauth/
token
● https://authentication.myauthserver.com/tenant/
{tenant}/oauth/token → https://
authentication.myauthserver.com/tenant/mytenant/
oauth/token
● https://oauth.{tenant}.myauthserver.com/token →
https://oauth.mytenant.myauthserver.com/token
Name Name Name of the destination. Must be unique for the destination level.
Description Description A human-readable description of the destination.
Client
Secret
clientSecret OAuth 2.0 client secret to be used for the user access token exchange.
Client ID clientId OAuth 2.0 client ID to be used for the user access token exchange.
Authenticati
on
Authentication OAuth2UserTokenExchange in this case.
SAP BTP Connectivity
Connectivity PUBLIC 87](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-87-320.jpg)
![Field/Parameter JSON Key Input/Description
URL.headers
.<header-
key>
A static key prefix used as a namespace grouping of the URL's HTTP headers whose
values will be sent to the target endpoint. For each HTTP header's key, you must add
a URL.headers prefix separated by dot-delimiter. For example:
Sample Code
{
...
"URL.headers.<header-key-1>" : "<header-
value-1>",
...
"URL.headers.<header-key-N>": "<header-value-
N>",
}
Note
This is a naming convention. As the call to the target endpoint is performed on
the client side, the service only provides the configured properties. The expecta
tion for the client-side processing logic is to parse and use them. If you are using
higher-level libraries and tools, please check if they support this convention.
URL.queries
.<query-
key>
A static key prefix used as a namespace grouping of URL's query parameters whose
values will be sent to the target endpoint. For each query parameter's key, you must
add a URL.queries prefix separated by dot-delimiter. For example:
Sample Code
{
...
"URL.queries.<query-key-1>" : "<query-
value-1>",
...
"URL.queries.<query-key-N>": "<query-value-N>",
}
Note
This is a naming convention. As the call to the target endpoint is performed on
the client side, the service only provides the configured properties. The expecta
tion for the client-side processing logic is to parse and use them. If you are using
higher-level libraries and tools, please check if they support this convention.
tokenServic
e.KeyStoreL
ocation
Contains the name of the certificate configuration to be used. This property is re
quired when using client certificates for authentication. See OAuth with X.509 Client
Certificates [page 109].
SAP BTP Connectivity
Connectivity PUBLIC 89](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-89-320.jpg)
![Field/Parameter JSON Key Input/Description
tokenServic
e.KeyStoreP
assword
Contains the password for the certificate configuration (if one is needed) when using
client certificates for authentication. See OAuth with X.509 Client Certificates [page
109].
x_user_toke
n.jwks
Base64-encoded JSON web key set, containing the signing keys which are used to
validate the JWT provided in the X-User-Token header.
For more information, see JWK Set Format .
x_user_toke
n.jwks_uri
URI of the JSON web key set, containing the signing keys which are used to validate
the JWT provided in the X-User-Token header.
For more information, see OpenID Connect Discovery .
Back to Content [page 86]
Example: AuthTokens Object Response
The response for "find destination" contains an authTokens object in the format given below. For more
information on the fields in authTokens, see "Find Destination" Response Structure [page 196].
Sample Code
"authTokens": [
{
"type": "Bearer",
"value": "eyJhbGciOiJSUzI1NiIsInR5cC...",
"http_header": {
"key":"Authorization",
"value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..."
}
}
]
Back to Content [page 86]
Related Information
Exchanging User JWTs via OAuth2UserTokenExchange Destinations [page 204]
90 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-90-320.jpg)
![1.1.3.2.7 SAP Assertion SSO Authentication
Create and configure an SAP Assertion SSO destination for an application in the Cloud Foundry environment.
Caution
Authentication type SAP Assertion SSO is deprecated and will be removed soon. The recommended
authentication types for establishing single sign-on (SSO) are:
● Principal Propagation SSO Authentication [page 68] for on-premise connections.
● OAuth SAML Bearer Assertion Authentication [page 70] or SAML Assertion Authentication [page 105]
for Internet connections.
Context
By default, all SAP systems accept SAP assertion tickets for user propagation.
Note
For more information, see Authentication Assertion Tickets.
The aim of the SAPAssertionSSO destination is to generate such an assertion ticket in order to propagate the
currently logged-on SAP BTP user to an SAP backend system. You can only use this authentication type if the
user IDs on both sides are the same. The following diagram shows the elements of the configuration process on
the SAP BTP and in the corresponding backend system:
SAP BTP Connectivity
Connectivity PUBLIC 91](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-91-320.jpg)
![Configuration Steps
1. Configure the backend system to accept SAP assertion tickets signed by a trusted x.509 key pair. For
more information, see Configuring a Trust Relationship for SAP Assertion Tickets.
2. Create and configure an SAPAssertionSSO destination using the properties listed below in the SAP BTP
Destination service. For more information, see:
○ Access the Destinations Editor [page 40]
○ Create HTTP Destinations [page 43]
○ Destination service REST API
Properties
The following credentials must be specified:
Property Description
Required
Name Destination name. It must be the same as the destination
name you use in the configuration tools, that is, Destinations
editor (cockpit).
Type Destination type. Use HTTP for all HTTP(S) destination.
URL URL of the protected resource on the called application.
Authentication Authentication type. Use SAPAssertionSSO as a value.
IssuerSID This system ID should be trusted by the backend system.
IssuerClient This client ID should be trusted by the backend system.
RecipientSID System ID (SID) of the backend system.
RecipientClient Client ID of the backend system.
Certificate A base64 encoded certificate that is trusted by the SAP sys
tem.
SigningKey A base64 encoded signing/private key that is trusted by the
SAP system.
92 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-92-320.jpg)
![Property Description
URL.queries.<query-key> A static key prefix used as a namespace grouping of URL's
query parameters whose values will be sent to the target
endpoint. For each query parameter's key, you must add a
URL.queries prefix separated by dot-delimiter. For exam
ple:
Sample Code
{
...
"URL.queries.<query-key-1>" :
"<query-value-1>",
...
"URL.queries.<query-key-N>":
"<query-value-N>",
}
Note
This is a naming convention. As the call to the target
endpoint is performed on the client side, the service
only provides the configured properties. The expecta
tion for the client-side processing logic is to parse and
use them. If you are using higher-level libraries and
tools, please check if they support this convention.
Example
{
"Name": "weather",
"Type": "HTTP",
"Authentication": "SAPAssertionSSO",
"IssuerSID": "JAV",
"IssuerClient": "000",
"RecipientSID": "SAP",
"RecipientClient": "100",
"Certificate": "MIICiDCCAkegAwI...rvHTQ==",
"SigningKey": "MIIBSwIB...RuqNKGA="
}
The response for "find destination" contains an authTokens object in the format given below. For more
information on the fields in authTokens, see "Find Destination" Response Structure [page 196].
Sample Code
"authTokens": [
{
SAP BTP Connectivity
Connectivity PUBLIC 95](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-95-320.jpg)
!["type": "MYSAPSSO2",
"value": "AjExMDACAANKQVYDA...",
"http_header": {
"key":"MYSAPSSO2",
"value":"AjExMDACAANKQVYDA..."
}
}
]
1.1.3.2.8 OAuth Password Authentication
Learn about the OAuth password authentication type for HTTP destinations in the Cloud Foundry environment:
use cases, supported properties and examples.
Content
Overview [page 96]
Properties [page 96]
Example: OAuth Token Service [page 99]
Overview
SAP BTP provides support for applications to use the OAuth password grant flow for consuming OAuth-
protected resources.
The client credentials as well as the user name and password are used to request an access token from an
OAuth server, referred to as token service below. Access token retrieval is performed automatically by the
Destination service when using the "find destination" REST endpoint.
Back to Content [page 96]
Properties
The table below lists the destination properties needed for the OAuth2Password authentication type.
96 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-96-320.jpg)
![Property Description
tokenServiceU
RL.queries.<q
uery-key>
A static key prefix used as a namespace grouping of tokenServiceUrl's query parameters. Its
values will be sent to the token service during token retrieval. For each query paramester's key you
must add a 'tokenServiceURL.queries' prefix separated by dot delimiter. For example:
Sample Code
{
...
"tokenServiceURL.queries.<query-key-1>" : "<query-
value-1>",
...
"tokenServiceURL.queries.<query-key-N>": "<query-value-N>",
}
tokenService.
KeyStoreLocat
ion
Contains the name of the certificate configuration to be used. This property is required when using
client certificates for authentication. See OAuth with X.509 Client Certificates [page 109].
tokenService.
KeyStorePassw
ord
Contains the password for the certificate configuration (if one is needed) when using client certifi-
cates for authentication. See OAuth with X.509 Client Certificates [page 109].
URL.headers.<
header-key>
A static key prefix used as a namespace grouping of the URL's HTTP headers whose values will be
sent to the target endpoint. For each HTTP header's key, you must add a URL.headers prefix sepa
rated by dot-delimiter. For example:
Sample Code
{
...
"URL.headers.<header-key-1>" : "<header-value-1>",
...
"URL.headers.<header-key-N>": "<header-value-N>",
}
Note
This is a naming convention. As the call to the target endpoint is performed on the client side, the
service only provides the configured properties. The expectation for the client-side processing
logic is to parse and use them. If you are using higher-level libraries and tools, please check if they
support this convention.
98 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-98-320.jpg)
![Property Description
URL.queries.<
query-key>
A static key prefix used as a namespace grouping of URL's query parameters whose values will be
sent to the target endpoint. For each query parameter's key, you must add a URL.queries prefix
separated by dot-delimiter. For example:
Sample Code
{
...
"URL.queries.<query-key-1>" : "<query-value-1>",
...
"URL.queries.<query-key-N>": "<query-value-N>",
}
Note
This is a naming convention. As the call to the target endpoint is performed on the client side, the
service only provides the configured properties. The expectation for the client-side processing
logic is to parse and use them. If you are using higher-level libraries and tools, please check if they
support this convention.
Note
When the OAuth server is called, the caller side trusts the server based on the trust settings of the
destination. For more information, see Server Certificate Authentication [page 65].
Back to Content [page 96]
Example: OAuth Token Service
Sample Code
{
"Name": "SapOAuthPassGrant",
"Type": "HTTP",
"URL": "https://myapp.cfapps.sap.hana.ondemand.com/mypath",
"ProxyType": "Internet",
"Authentication": "OAuth2Password",
"clientId": "my-client-id",
"clientSecret": "my-client-pass",
"User": "my-username",
"Password": "my-password",
"tokenServiceURL": "https://authentication.sap.hana.ondemand.com/oauth/
token"
}
SAP BTP Connectivity
Connectivity PUBLIC 99](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-99-320.jpg)
![The response for "find destination" contains an authTokens object in the format given below. For more
information on the fields in authTokens, see "Find Destination" Response Structure [page 196].
Sample Code
"authTokens": [
{
"type": "Bearer",
"value": "eyJhbGciOiJSUzI1NiIsInR5cC...",
"http_header": {
"key":"Authorization",
"value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..."
}
}
]
Back to Content [page 96]
1.1.3.2.9 OAuth JWT Bearer Authentication
Learn about the OAuth JWT bearer authentication type for HTTP destinations in the Cloud Foundry
environment: use cases, supported properties and examples.
Content
Overview [page 100]
Properties [page 101]
Example: AuthTokens Object Response [page 105]
Overview
To allow an application to call another application, passing the user context, and fetch resources, the caller
application must pass an access token. In this authorization flow, the initial user token is passed to the OAuth
server as input data. This process is performed automatically by the Destination service, which helps
simplifying the application development: You only have to construct the right request to the target URL, by
using the outcome (another access token) of the service-side automation.
Back to Content [page 100]
100 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-100-320.jpg)
![Properties
To configure a destination of this authentication type, you must specify all the required properties. You can do
this via SAP BTP cockpit (see Create HTTP Destinations [page 43]), or using the Destination Service REST API
[page 59]. The following table shows the properties along with their semantics.
Field/Parameter
(Cockpit) JSON Key Description
Required
Authenticati
on
Authentication OAuth2JWTBearer in this case.
Client ID clientId OAuth 2.0 client ID to be used for the user access token exchange.
Client
Secret
clientSecret OAuth 2.0 client secret to be used for the user access token exchange.
Name Name Name of the destination. Must be unique for the destination level.
Proxy Type ProxyType Choose Internet. OnPremise is not supported for this authentication type.
SAP BTP Connectivity
Connectivity PUBLIC 101](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-101-320.jpg)
![Field/Parameter
(Cockpit) JSON Key Description
Token
Service URL
tokenServi
ceURL
The URL of the token service, against which the token exchange is performed. De
pending on the Token Service URL Type, this property is interpreted in dif
ferent ways during the automatic token retrieval:
● For Dedicated, the token service URL is taken as is.
● For Common, the token service URL is searched for the tenant placeholder
{tenant}.
{tenant} is resolved as the subdomain of the subaccount on behalf of which
the caller is performing the call. If the placeholder is not found, {tenant} is
inserted as a subdomain of the token service URL.
See Automated Access Token Retrieval [page 205] for information about how
the tenant is determined.
The subaccount subdomain is mandated during creation of the subaccount,
see Create a Subaccount.
Examples of interpreting the token service URL for the token service URL type
Common, if the call to the Destination service is on behalf of a subaccount subdo
main with value mytenant:
● https://authentication.us10.hana.ondemand.com/oauth/
token → https://
mytenant.authentication.us10.hana.ondemand.com/oauth/
token
● https://
{tenant}.authentication.us10.hana.ondemand.com/oauth/
token → https://
mytenant.authentication.us10.hana.ondemand.com/oauth/
token
● https://authentication.myauthserver.com/tenant/
{tenant}/oauth/token → https://
authentication.myauthserver.com/tenant/mytenant/
oauth/token
● https://oauth.{tenant}.myauthserver.com/token →
https://oauth.mytenant.myauthserver.com/token
Token
Service URL
Type
tokenServi
ceURLType
● Choose Dedicated if the token service URL serves only a single tenant.
● Choose Common if the token service URL serves multiple tenants.
Type Type Choose HTTP (for HTTP or HTTPS communication).
URL URL URL of the target endpoint.
Optional
Description Description A human-readable description of the destination.
Additional
102 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-102-320.jpg)
![Field/Parameter
(Cockpit) JSON Key Description
URL.headers
.<header-
key>
A static key prefix used as a namespace grouping of the URL's HTTP headers whose
values will be sent to the target endpoint. For each HTTP header's key, you must add
a URL.headers prefix separated by dot-delimiter. For example:
Sample Code
{
...
"URL.headers.<header-key-1>" : "<header-
value-1>",
...
"URL.headers.<header-key-N>": "<header-value-
N>",
}
Note
This is a naming convention. As the call to the target endpoint is performed on
the client side, the service only provides the configured properties. The expecta
tion for the client-side processing logic is to parse and use them. If you are using
higher-level libraries and tools, please check if they support this convention.
URL.queries
.<query-
key>
A static key prefix used as a namespace grouping of URL's query parameters whose
values will be sent to the target endpoint. For each query parameter's key, you must
add a URL.queries prefix separated by dot-delimiter. For example:
Sample Code
{
...
"URL.queries.<query-key-1>" : "<query-
value-1>",
...
"URL.queries.<query-key-N>": "<query-value-N>",
}
Note
This is a naming convention. As the call to the target endpoint is performed on
the client side, the service only provides the configured properties. The expecta
tion for the client-side processing logic is to parse and use them. If you are using
higher-level libraries and tools, please check if they support this convention.
tokenServic
e.KeyStoreL
ocation
Contains the name of the certificate configuration to be used. This property is re
quired when using client certificates for authentication. See OAuth with X.509 Client
Certificates [page 109].
104 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-104-320.jpg)
![Field/Parameter
(Cockpit) JSON Key Description
tokenServic
e.KeyStoreP
assword
Contains the password for the certificate configuration (if one is needed) when using
client certificates for authentication. See OAuth with X.509 Client Certificates [page
109].
Back to Content [page 100]
Example: AuthTokens Object Response
The response for "find destination" contains an authTokens object in the format given below. For more
information on the fields in authTokens, see "Find Destination" Response Structure [page 196].
Sample Code
"authTokens": [
{
"type": "Bearer",
"value": "eyJhbGciOiJSUzI1NiIsInR5cC...",
"http_header": {
"key":"Authorization",
"value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..."
}
}
]
Back to Content [page 100]
1.1.3.2.10 SAML Assertion Authentication
Create and configure an SAML Assertion destination for an application in the Cloud Foundry environment.
Context
The Destination service lets you generate SAML assertions as per SAML 2.0 specification. You can retrieve a
generated SAML assertion from the Destination service by using the SAMLAssertion authentication type,
whereas OAuth SAML Bearer Assertion Authentication [page 70] sends the generated SAML assertion to an
OAuth server to get a token. The Destination service provides functionality for caching the generated SAML
assertion for later use, and caching by the app whenever needed, which helps simplifying application
development.
SAP BTP Connectivity
Connectivity PUBLIC 105](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-105-320.jpg)
![Properties
The table below lists the destination properties for the SAMLAssertion authentication type.
Property Description
Required
Name Name of the destination. Must be unique for the destination
level.
Type Destination type. Choose HTTP for all HTTP(S) destinations.
URL URL of the target endpoint.
ProxyType Choose Internet or OnPremise.
Authentication Authentication type. Use SAMLAssertion as value.
audience Value of the Audience tag, which is part of the generated
SAML assertion. For more information, seeSAML 2.0 specifi-
cation .
authnContextClassRef Value of the AuthnContextClassRef tag, which is part
of generated SAML assertion. For more information, see
SAML 2.0 specification .
Additional
clientKey Key that identifies the consumer to the authorization server.
nameQualifier When this property is set, the NameQualifier under the
NameId tag of the generated SAML assertion is determined
in accordance to the value.
companyId Company identifier.
assertionIssuer Issuer of the SAML assertion.
nameIdFormat Value of the NameIdFormat tag, which is part of gener
ated SAML Assertion. For more information, see SAML 2.0
specification .
userIdSource When this property is set, the user ID in the NameId tag of
the generated SAML assertion is determined in accordance
to the value of this attribute. For more information, see User
Propagation via SAML 2.0 Bearer Assertion Flow [page 200].
x_user_token.jwks Base64-encoded JSON web key set, containing the signing
keys which are used to validate the JWT provided in the X-
User-Token header.
For more information, see JWK Set Format .
x_user_token.jwks_uri URI of the JSON web key set, containing the signing keys
which are used to validate the JWT provided in the X-User-
Token header.
For more information, see OpenID Connect Discovery .
106 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-106-320.jpg)
![Property Description
URL.queries.<query-key> A static key prefix used as a namespace grouping of URL's
query parameters whose values will be sent to the target
endpoint. For each query parameter's key, you must add a
URL.queries prefix separated by dot-delimiter. For exam
ple:
Sample Code
{
...
"URL.queries.<query-key-1>" :
"<query-value-1>",
...
"URL.queries.<query-key-N>":
"<query-value-N>",
}
Note
This is a naming convention. As the call to the target
endpoint is performed on the client side, the service
only provides the configured properties. The expecta
tion for the client-side processing logic is to parse and
use them. If you are using higher-level libraries and
tools, please check if they support this convention.
Example
The connectivity destination below provides HTTP access to the OData API of the SuccessFactors Jam.
Name=destinationSamlAssertion
Type=HTTP
URL=https://myXXXXXX-api.s4hana.ondemand.com
Authentication=SAMLAssertion
ProxyType=Internet
audience=https://myXXXXXX.s4hana.ondemand.com
authnContextClassRef=urn:oasis:names:tc:SAML:2.0:ac:classes:X509
The response for "find destination" contains an authTokens object in the format given below. For more
information on the fields in authTokens, see "Find Destination" Response Structure [page 196].
Sample Code
"authTokens": [
{
"type": "SAML2.0",
"value": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZ...",
108 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-108-320.jpg)
!["http_header": {
"key":"Authorization",
"value":"SAML2.0 PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZ..."
}
}
]
Related Information
Create HTTP Destinations [page 43]
Destination Examples [page 48]
Exchanging User JWTs via OAuth2UserTokenExchange Destinations [page 204]
1.1.3.2.11 OAuth with X.509 Client Certificates
Use an X.509 certificate instead of a secret to authenticate against the authentication server.
To perform mutual TLS, you can use an X.509 client certificate instead of a client secret when connecting to
the authorization server. To do so, you must create a certificate configuration containing a valid X.509 client
certificate or a keystore, and link it to the destination configuration using these properties:
Property Description
tokenService.KeyStoreLocation Contains the name of the certificate configuration to be
used. This property is required.
tokenService.KeyStorePassword Contains the password for the certificate configuration (if
one is needed).
Caution
Mutual TLS with an X.509 client certificate is performed only if the tokenService.KeyStoreLocation
property is set in the destination configuration. Otherwise, the client secret is used.
Supported Certificate Configuration Formats
● Java Keystore (.jks): Requires the tokenService.KeyStorePassword property.
● PKCS12 (.pfx or .p12): Requires the tokenService.KeyStorePassword property.
● PEM-encoded X.509 client certificate and private key (.crt, .cer and .pem): The certificate configuration
can contain several valid X.509 certificates and private keys.
SAP BTP Connectivity
Connectivity PUBLIC 109](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-109-320.jpg)
![Supported OAuth Flows
● OAuth Client Credentials Authentication [page 80]
● OAuth Password Authentication [page 96]
● OAuth User Token Exchange Authentication [page 86]
● OAuth JWT Bearer Authentication [page 100]
1.1.3.3 RFC Destinations
RFC destinations provide the configuration required for communication with an on-premise ABAP system via
Remote Function Call. The RFC destination data is used by the Java Connector (JCo) version that is available
within SAP BTP to establish and manage the connection.
RFC Destination Properties
The RFC destination specific configuration in SAP BTP consists of properties arranged in groups, as described
below. The supported set of properties is a subset of the standard JCo properties in arbitrary environments.
The configuration data is divided into the following groups:
● User Logon Properties [page 111]
● Pooling Configuration [page 113]
● Repository Configuration [page 115]
● Target System Configuration [page 115]
● Parameters Influencing Communication Behavior [page 120]
The minimal configuration contains user logon properties and information identifying the target host. This
means you must provide at least a set of properties containing this information.
Example
Name=SalesSystem
Type=RFC
jco.client.client=000
jco.client.lang=EN
jco.client.user=consultant
jco.client.passwd=<password>
jco.client.ashost=sales-system.cloud
jco.client.sysnr=42
jco.destination.pool_capacity=5
jco.destination.peak_limit=10
110 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-110-320.jpg)
![Related Information
Invoking ABAP Function Modules via RFC [page 208]
1.1.3.3.1 User Logon Properties
JCo properties that cover different types of user credentials, as well as the ABAP system client and the logon
language.
The currently supported logon mechanism uses user or password as credentials.
Property Description
jco.client.client Represents the client to be used in the ABAP system. Valid
format is a three-digit number.
jco.client.lang Optional property. Represents the logon language. If the
property is not provided, the user's or system's default lan
guage is used. Valid values are two-character ISO language
codes or one-character SAP language codes.
jco.client.user Represents the user to be used for logging on to the ABAP
system. Max. 12 characters long.
Note
When working with the Destinations editor in the cock
pit, enter the value in the <User> field. Do not enter it as
additional property.
jco.client.alias_user Represents the user to be used for logging on to the ABAP
system. Either jco.client.user or
jco.client.alias_user must be specified. The alias
user may be up to 40 characters long.
Note
When working with the Destinations editor in the cock
pit, enter the value in the <Alias User> field. Do not
enter it as additional property.
SAP BTP Connectivity
Connectivity PUBLIC 111](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-111-320.jpg)
![Content
Overview [page 116]
Proxy Types [page 116]
Direct Connection [page 117]
Load Balancing Connection [page 117]
WebSocket Connection [page 118]
Overview
You can use the following configuration types alternatively:
● Direct connection to an ABAP application server
● Load balancing connection to a group of ABAP application servers via a message server
● WebSocket connection to an ABAP application server (RFC over Internet)
Note
When using a WebSocket connection, the target ABAP system must be exposed to the Internet.
Depending on the configuration you use, different properties are mandatory or optional.
To improve performance, consider using optional properties additionally, such as
jco.client.serialization_format. For more information, see JCo documentation .
Back to Content [page 116]
Proxy Types
The field <Proxy Type> lets you choose between Internet and OnPremise. When choosing OnPremise,
the RFC communication is routed over a Cloud Connector that is connected to the subaccount. When choosing
Internet, the RFC communciation is done over a WebSocket connection.
Back to Content [page 116]
116 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-116-320.jpg)
![Direct Connection
To use a direct connection (connection without load balancing) to an application server over Cloud Connector,
you must set the value for <Proxy Type> to OnPremise.
Property Description
jco.client.ashost Represents the application server host to be used. For con
figurations on SAP BTP, the property must match a virtual
host entry in the Cloud Connector Access Control configura-
tion. The property indicates that a direct connection is es
tablished.
jco.client.sysnr Represents the so-called "system number" and has two dig
its. It identifies the logical port on which the application
server is listening for incoming requests. For configurations
on SAP BTP, the property must match a virtual port entry in
the Cloud Connector Access Control configuration.
Note
The virtual port in the above access control entry must
be named sapgw<##>, where <##> is the value of
sysnr.
jco.client.client Three-digit ABAP client number. Defines the client of the tar
get ABAP system.
Back to Content [page 116]
Load Balancing Connection
To use load balancing to a system over Cloud Connector, you must set the value for <Proxy Type> to
OnPremise.
Property Description
jco.client.mshost Represents the message server host to be used. For configu-
rations on SAP BTP, the property must match a virtual host
entry in the Cloud Connector Access Control configuration.
The property indicates that load balancing is used for estab
lishing a connection.
jco.client.group Optional property. Identifies the group of application servers
that is used, the so-called "logon group". If the property is
not specified, the group PUBLIC is used.
SAP BTP Connectivity
Connectivity PUBLIC 117](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-117-320.jpg)
![Property Description
jco.client.r3name Represents the three-character system ID of the ABAP sys
tem to be addressed. For configurations on SAP BTP, the
property must match a virtual port entry in the Cloud
Connector Access Control configuration.
Note
The virtual port in the above access control entry must
be named sapms<###>, where <###> is the value of
r3name.
jco.client.msserv Represents the port on which the message server is listening
for incoming requests. you can use this property as an alter
native to jco.client.r3name. One of these two must
be present. For configurations on SAP BTP, the property
must match a virtual port entry in the Cloud Connector
Access Control configuration. You can therefore avoid look
ups in the /etc/services file (<Install_Drive>
WindowsSystem32driversetcservices) on
the Cloud Connector host.
jco.client.client Three-digit ABAP client number. Defines the client of the tar
get ABAP system.
Back to Content [page 116]
WebSocket Connection
To use a direct connection over WebSocket, you must set the value for <Proxy Type> to Internet.
Prerequisites
● Your target system is an ABAP server as of S/4HANA (on-premise) version 1909, or a cloud ABAP system.
● Your SAP Java buildpack version is at least 1.26.0.
Property Description
jco.client.wshost Represents the WebSocket RFC server host on which the tar
get ABAP system is running. The system must be exposed to
the Internet.
jco.client.wsport Represents the WebSocket RFC server port on which the tar
get ABAP system is listening.
jco.client.client Three-digit ABAP client number. Defines the client of the tar
get ABAP system.
118 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-118-320.jpg)
![Property Description
jco.client.tls_trust_all If set to 1, all server certificates are considered trusted dur
ing TLS handshake. If set to 0, either a dedicated trust store
must be configured, or the JDK trust store is used as default.
Default value is 0.
Note
We recommend that you do not use value 1 ("trust all")
in productive scenarios, but only for demo/test pur
poses.
<Trust Store Location>
1. When used in local environment
2. When used in cloud environment
If you don't want to use the default JDK trust store (option
Use default JDK truststore is unchecked), you must enter a
<Trust Store Location>. This field indicates the path to
the JKS file which contains trusted certificates (Certificate
Authorities) for authentication against a remote client.
1. The relative path to the JKS file. The root path is the
server's location on the file system.
2. The name of the JKS file.
Note
If the <Trust Store Location> is not specified, the
JDK trust store is used as a default trust store for the
destination.
<Trust Store Password> Password for the JKS trust store file. This field is mandatory
if <Trust Store Location> is used.
Note
You can upload trust store JKS files using the same command as for uploading destination configuration
property files. You only need to specify the JKS file instead of the destination configuration file.
Note
Connections to remote services which require Java Cryptography Extension (JCE) unlimited strength
jurisdiction policy are not supported.
See also WebSocket RFC (ABAP Platform documentation).
Back to Content [page 116]
SAP BTP Connectivity
Connectivity PUBLIC 119](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-119-320.jpg)
![Property Description
jco.client.network Defines which network type is expected to be used for the
destination.The property impacts the serialization behavior
of function module data, see SAP Note 2372888 . Valid
values are WAN and LAN. The default value is LAN.
1.1.3.4 Principal Propagation
Enable single sign-on (SSO) by forwarding the identity of cloud users to a remote system or service (Cloud
Foundry environment).
Content
Overview [page 121]
Scenario: Cloud to On-Premise [page 122]
Configuration: Cloud to On-Premise [page 123]
Scenario: Cloud to Cloud [page 123]
Configuration: Cloud to Cloud [page 124]
Overview
The Connectivity and Destination services let you forward the identity of a cloud user to a remote system. This
process is called principal propagation (also known as user propagation or user principal propagation). It uses a
JSON Web token (JWT) as exchange format for the user information.
Two scenarios are supported: Cloud to on-premise (using the Connectivity service) and cloud to cloud (using
the Destination service).
● Cloud to on-premise: The user is propagated from a cloud application to an on-premise system using a
destination configuration with authentication type PrincipalPropagation.
Note
This scenario requires the Cloud Connector to connect to your on-premise system.
● Cloud to cloud: The user is propagated from a cloud application to another remote (cloud) system using a
destination configuration with authentication type OAuth2SAMLBearerAssertion.
For more information on setting up destinations, see Create HTTP Destinations [page 43].
SAP BTP Connectivity
Connectivity PUBLIC 121](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-121-320.jpg)
![Back to Content [page 121]
Scenario: Cloud to On-Premise
1. A user logs in to the cloud application. Its identity is established by an identity provider (this can be the
default IdP for the subaccount or another trusted IdP).
2. The cloud application then uses a user exchange token to propagate the user to the Connectivity service.
See also Configure Principal Propagation via User Exchange Token [page 174].
Optionally, the application may use the Destination service to externalize the connection configuration that
points to the target on-premise system. See also Consuming the Destination Service [page 189].
3. The Connectivity service forwards the JWT (that represents the user) to the Cloud Connector.
4. The Cloud Connector receives the JWT, verifies it, extracts the attributes, and uses its STS (security token
service) component to issue a new token (for example, an X.509 certificate) with the same or similar
attributes to assert the identity to the backend (BE1-BEm). The Cloud Connector and the cloud application
share the same trust settings, see Set Up Trust for Principal Propagation [page 341].
5. The Cloud Connector sends the new token (for example, an X.509 certificate) to the backend system.
Back to Content [page 121]
122 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-122-320.jpg)
![Configuration: Cloud to On-Premise
Task Type Task
Operator
Set Up Trust for Principal Propagation [page 341] (Cloud
Connector)
Configure Principal Propagation for HTTPS [page 347]
(Cloud Connector)
Configure a Subject Pattern for Principal Propagation [page
359] (Cloud Connector)
Developer
Configure Principal Propagation via User Exchange Token
[page 174] (Connectivity service)
Back to Content [page 121]
Scenario: Cloud to Cloud
1. A user logs in to the cloud application. Its identity is established by an identity provider (this can be the
default IdP for the subaccount or another trusted IdP).
2. When the application retrieves an OAuthSAMLBearer destination, the user is made available to the
Destination Service by means of a user exchange JWT. The service then wraps the user identity in a SAML
assertion, signs it with the subaccount's private key and sends it to the specified OAuth token service.
SAP BTP Connectivity
Connectivity PUBLIC 123](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-123-320.jpg)
![3. The OAuth token service accepts the SAML assertion and returns an OAuth access token. In turn, the
Destination service returns both the destination and the access token to the requesting application.
4. The application uses the destination properties and the access token to consume the remote API.
You can set up user propagation for connections to applications in different cloud systems or environments.
Find the basic configuration steps and typical use cases in section Configuration: Cloud to Cloud [page 124].
Back to Content [page 121]
Configuration: Cloud to Cloud
Task Type Task
Operator
Set up Trust Between Systems [page 124]
Operator and/or Developer
User Propagation via SAML 2.0 Bearer Assertion Flow [page
200] (Destination service)
Use Cases: Cloud to Cloud
● Scenario: User Propagation from the Cloud Foundry Environment to SAP S/4HANA Cloud [page 126]
● Scenario: User Propagation from the Cloud Foundry Environment to SAP SuccessFactors [page 135]
● Scenario: User Propagation between Cloud Foundry Applications [page 141]
● Scenario: User Propagation from the Cloud Foundry Environment to the Neo Environment [page 149]
Back to Content [page 121]
1.1.3.4.1 Set up Trust Between Systems
Download and configure X.509 certificates as a prerequisite for user propagation from the Cloud Foundry
environment.
Setting up a trust scenario for user propagation requires the exchange of public keys and certificates between
the affected systems, as well as the respective trust configuration within these systems. This enables you to
use an HTTP destination with authentication type OAuth2SAMLBearerAssertion for the communication.
124 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-124-320.jpg)
![A trust scenario can include user propagation from the Cloud Foundry environment to another SAP BTP
environment, to another Cloud Foundry subaccount, or to a remote system outside SAP BTP, like S/4HANA
Cloud, C4C, Success Factors, and others.
Set Up a Certificate [page 125]
Renew a Certificate [page 125]
Set Up a Certificate
Download and save locally the identifying X509 certificate of the subaccount in the Cloud Foundry
environment.
1. In the cloud cockpit, log on with Administrator permission.
2. Navigate to your subaccount in the Cloud Foundry environment.
3. From the left-side menu, choose Connectivity Destinations .
4. Choose the Download Trust button and save locally the X.509 certificate that identifies this subaccount.
5. Configure the downloaded X.509 certificate in the target system to which you want to propagate the user.
Renew a Certificate
If the X.509 certificate validity is about to expire, you can renew the certificate and extend its validity by
another 2 years.
1. In the cloud cockpit, log on with Administrator permission.
2. Navigate to your subaccount in the Cloud Foundry environment.
3. From the left-side menu, choose Connectivity Destinations .
4. Choose the Renew Trust button to trigger a renewal of the existing X509 certificate.
SAP BTP Connectivity
Connectivity PUBLIC 125](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-125-320.jpg)
![5. Choose the Download Trust button and save locally the X.509 certificate that identifies this subaccount.
6. Configure the renewed X.509 certificate in the target system to which you want to propagate the user.
Related Information
Principal Propagation from the Cloud Foundry to the Neo Environment
Scenario: User Propagation from the Cloud Foundry Environment to SAP S/4HANA Cloud [page 126]
Scenario: User Propagation from the Cloud Foundry Environment to SAP SuccessFactors [page 135]
1.1.3.4.2 Scenario: User Propagation from the Cloud
Foundry Environment to SAP S/4HANA Cloud
Configure user propagation (single sign-on), using OAuth communication from the SAP BTP Cloud Foundry
environment to S/4HANA Cloud. As OAuth mechanism, you use the OAuth 2.0 SAML Bearer Assertion Flow.
Steps
Scenario [page 126]
Prerequisites [page 127]
Configuration Tasks [page 128]
Scenario
As a customer, you own an SAP BTP global account and have created at least one subaccount therein. Within
the subaccount, you have deployed a Web application. Authentication against the Web application is based on a
trusted identity provider (IdP) that you need to configure for the subaccount.
On the S/4HANA Cloud side, you own an S/4HANA ABAP tenant. Authentication against the S/4HANA ABAP
tenant is based on the trusted IdP which is always your Identity Authentication Service (IAS) tenant. Typically,
you will configure this S/4HANA Cloud Identity tenant to forward authentication requests to your corporate IdP.
126 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-126-320.jpg)
![Prerequisites
● You have an S/4HANA Cloud tenant and a user with the following business catalogs assigned:
Business Role ID Area
SAP_BCR_CORE_COM Communication Management
SAP_BCR_CORE_IAM Identity and Access Management
SAP_BCR_CORE_EXT Extensibility
● You have administrator permission for the configured S/4HANA Cloud IAS tenant.
● You have a subaccount and PaaS tenant in the SAP BTP Cloud Foundry environment.
Next Step
● Configuration Tasks [page 128]
SAP BTP Connectivity
Connectivity PUBLIC 127](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-127-320.jpg)
![1.1.3.4.2.1 Configuration Tasks
Perform these steps to set up user propagation between S/4HANA Cloud and the SAP BTP Cloud Foundry
environment.
Tasks
1. Configure Single Sign-On between S/4HANA Cloud and the Cloud Foundry Organization on SAP BTP [page
128]
2. Configure OAuth Communication [page 128]
3. Configure Communication Settings in S/4HANA Cloud [page 129]
4. Configure Communication Settings in SAP BTP [page 132]
5. Consume the Destination and Execute the Scenario [page 135]
Configure Single Sign-On between S/4HANA Cloud and the Cloud Foundry
Organization on SAP BTP
To configure SSO with S/4HANA you must configure trust between the S/4HANA IAS tenant and theCloud
Foundry organization, see Manually Establish Trust and Federation Between UAA and Identity Authentication.
Configure OAuth Communication
Download the certificate from your Cloud Foundry subaccount on SAP BTP.
1. From the SAP BTP cockpit, choose Cloud Foundry environment your global account .
2. Choose or create a subaccount, and from your left-side subaccount menu, go to Connectivity
Destinations .
3. Press the Download Trust button.
128 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-128-320.jpg)
![Back to Tasks [page 128]
Configure Communication Settings in S/4HANA Cloud
1. Create a Communication User
1. In your S/4HANA Cloud launchpad, choose the application Maintain Communication Users.
2. From the User List view, create a new user.
3. Set <User Name>, <Password> and <Description>.
4. Copy this password, you will need it in a later step.
5. Press the Save on the bottom of the screen.
6. Close the Communication Users application.
SAP BTP Connectivity
Connectivity PUBLIC 129](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-129-320.jpg)
![3. In the popup, choose a scenario. For our example, we use SAP_COM_0013. Set the arrangement name,
for example SAP_COM_0013_MY_TEST.
4. In the Common Data section of the configuration screen, select the <Communication System> that
you have created in the step before. The communication user is added automatically in the Inbound
Communication section, and the <Authentication Method> is set to OAuth 2.0.
5. In the Outbound Services section, go to Launch SAP Web IDE and uncheck the Active checkbox of the
field <Service Status>.
6. Save your settings and go back to the launchpad.
Back to Tasks [page 128]
Configure Communication Settings in SAP BTP
1. From the SAP BTP cockpit, choose Cloud Foundry environment your global account .
2. Choose your subaccount, and from the left-side subaccount menu, go to Connectivity Destinations .
3. Press the New Destination button.
4. Enter the following parameters for your destination:
132 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-132-320.jpg)
![Parameter Value
Token Service URL For this field, you need the part of the URL before /
sap/... that you copied before from Communications
Arrangements service URL/service interface:
https://my300117-
api.s4hana.ondemand.com/sap/bc/sec/
oauth2/token?
scope=ADT_0001%20%2fUI5%2fAPP_INDEX_000
1%20%2fIWFND%2fSG_MED_CATALOG_0002
Note
This URL is pointing to the scope of the Inbound
Services of the communication scenario that we have
defined when creating the communication arrange
ment. The scopes have a fixed naming and are sepa
rated by %20 for the space and %2f for the slash :
○ ADT_001: scope of the Gateway service for ADT.
○ /UI5/APP_INDEX_0001: scope of the UI2
App Index.
○ /IWFND/SG_MED_CATALOG_0002: scope of
the Catalog service version 2.0.
Token Service User The same user as for the Client Key parameter.
Token Service Password The password for the communication user.
System User This parameter is not used, leave the field empty.
authnContextClassRef urn:oasis:names:tc:SAML:
2.0:ac:classes:X509
Back to Tasks [page 128]
134 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-134-320.jpg)
![Consume the Destination and Execute the Scenario
To perform the scenario and execute the request from the source application towards the target application,
proceed as follows:
1. Decide on where the user identity will be located when calling the Destination service. For details, see User
Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. This will determine how exactly you will
perform step 2.
2. Execute a "find destination" request from the source application to the Destination service. For details, see
Consuming the Destination Service [page 189] and the REST API documentation .
3. From the Destination service response, extract the access token and URL, and construct your request to
the target application. See "Find Destination" Response Structure [page 196] for details on the structure of
the response from the Destination service.
Back to Tasks [page 128]
1.1.3.4.3 Scenario: User Propagation from the Cloud
Foundry Environment to SAP SuccessFactors
Configure user propagation from the SAP BTP Cloud Foundry environment to SAP SuccessFactors.
Steps
Scenario [page 135]
Prerequisites [page 136]
Concept Overview [page 136]
Create an OAuth Client in SAP SuccessFactors [page 137]
Create and Consume a Destination for the Cloud Foundry Application [page 139]
Scenario
● From an application in the SAP BTP Cloud Foundry environment, you want to consume OData APIs
exposed by SuccessFactors modules.
SAP BTP Connectivity
Connectivity PUBLIC 135](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-135-320.jpg)
![Next Steps
● Create an OAuth Client in SAP SuccessFactors [page 137]
● Create and Consume a Destination for the Cloud Foundry Application [page 139]
1.1.3.4.3.1 Create an OAuth Client in SAP SuccessFactors
Create an OAuth client in SuccessFactors for user propagation from the SAP BTP Cloud Foundry environment.
1. Download the X.509 certificate from your Cloud Foundry subaccount:
In the cloud cockpit, navigate to your Cloud Foundry subaccount and from the left-side subaccount menu,
choose Connectivity Destinations . Choose Download Trust to get the certificate for this subaccount.
SAP BTP Connectivity
Connectivity PUBLIC 137](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-137-320.jpg)
![Next Step
● Create and Consume a Destination for the Cloud Foundry Application [page 139]
1.1.3.4.3.2 Create and Consume a Destination for the Cloud
Foundry Application
Create and consume an OAuth2SAMLBearerAssertion destination for your Cloud Foundry application.
Create the Destination
1. In the cloud cockpit, navigate to your Cloud Foundry subaccount and from the left-side subaccount menu,
choose Connectivity Destinations . Choose New Destination and enter a name Then provide the
following settings:
○ <URL>: URL of the SuccessFactors OData API you want to consume.
○ <Authentication>: OAuth2SAMLBearerAssertion
○ <Audience>: www.successfactors.com
○ <Client Key>: API Key of the OAuth client you created in SuccessFactors.
SAP BTP Connectivity
Connectivity PUBLIC 139](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-139-320.jpg)
![○ <Token Service URL>: API endpoint URL for the SuccessFactors instance, followed by /oauth/
token and the URL parameter company_id with the company ID, for example https://
apisalesdemo2.successfactors.eu/oauth/token?company_id=SFPART019820.
2. Enter three additional properties:
○ apiKey: the API Key of the OAuth client you created in SuccessFactors.
○ authnContextClassRef: urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession
○ nameIdFormat:
○ urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified, if the user ID will be
propagated to a SuccessFactors application, or
○ urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, if the user e-mail will be
propagated to SuccessFactors.
Consume the Destination and Execute the Scenario
To perform the scenario and execute the request from the source application towards the target application,
proceed as follows:
1. Decide on where the user identity will be located when calling the Destination service. For details, see User
Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. This will determine how exactly you will
perform step 2.
2. Execute a "find destination" request from the source application to the Destination service. For details, see
Consuming the Destination Service [page 189] and the REST API documentation .
3. From the Destination service response, extract the access token and URL, and construct your request to
the target application. See "Find Destination" Response Structure [page 196] for details on the structure of
the response from the Destination service.
140 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-140-320.jpg)
![1.1.3.4.4 Scenario: User Propagation between Cloud
Foundry Applications
Propagate the identity of a user between Cloud Foundry applications that are located in different subaccounts
or regions.
Steps
Scenario [page 141]
Prerequisites [page 141]
Concept [page 142]
Procedure [page 144]
1. Assemble IdP Metadata for Subaccount 1 [page 144]
2. Establish Trust between Subaccount 1 and Subaccount 2 [page 145]
3. Create an OAuthSAMLBearerAssertion Destination for Application 1 [page 146]
4. Consume the Destination and Execute the Scenario [page 148]
Scenario
● You have deployed an application in a Cloud Foundry environment (application 1).
● You want to call another Cloud Foundry application (application 2) in a different subaccount, in the same
or another region.
● You want to propagate the identity of the user that is logged in to application 1, to application 2.
Back to Steps [page 141]
Prerequisites
● You have two applications (application 1 and application 2) deployed in Cloud Foundry spaces in different
subaccounts in the same region or even in different regions.
● You have an instance of the Destination service bound to application 1.
● You have a user JWT (JSON Web Token) in application 1 where the call to application 2 is performed.
Back to Steps [page 141]
SAP BTP Connectivity
Connectivity PUBLIC 141](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-141-320.jpg)
![Concept
The identity of a user logged in to application 1 is established by an identity provider (IdP) of the respective
subaccount (subaccount 1).
Note
You can use the default IdP for the Cloud Foundry subaccount or a custom-configured IdP.
When the application retrieves an OAuthSAMLBearer destination, the user is made available to the Cloud
Foundry Destination service by means of a user exchange JWT. See also User Propagation via SAML 2.0 Bearer
Assertion Flow [page 200].
The service then wraps the user identity in a SAML assertion, signs it with subaccount 1's private key (which is
part of the special key pair for the subaccount, maintained by the Destination service) and sends it to the
authentication endpoint of subaccount 2, which hosts application 2.
To make the authentication endpoint accept the SAML assertion and return an access token, you must set up a
trust relationship between the two subaccounts, by using subaccount 1's public key. You can achieve this by
assembling the SAML IdP metadata, using subaccount 1's public key and setting up a new trust configuration
for subaccount 2, which is based on that metadata.
This way, users propagated from application 1 can be verified by subaccount 2's IdP before granting them
access tokens with their respective scopes in the context of subaccount 2.
The authentication endpoint accepts the SAML assertion and returns an OAuth access token. In turn, the
Destination service returns both the destination configuration and the access token to the requesting
application (application 1). Application 1 then uses the destination properties and the access token to call
application 2.
Option 1 - Setting up Trust between Subaccounts in the Same Region
142 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-142-320.jpg)
![Back to Steps [page 141]
Procedure
Assemble IdP Metadata for Subaccount 1
1. Download the X.509 certificate of subaccount 1. For instructions, see Set up Trust Between Systems [page
124]. The content of the file is shown as:
-----BEGIN CERTIFICATE-----<content>-----END CERTIFICATE-----
Below, we refer to the value of <content> as ${S1_CERTIFICATE}.
2. In the cockpit, navigate to the overview page of subaccount 1. For details, see Navigate in the Cockpit. Here
you can see the landscape domain, subaccount ID and subdomain. Below, we refer to the landscape
domain as ${S1_LANDSCAPE_DOMAIN}, to the subaccount ID as ${S1_SUBACCOUNT_ID} and to the
subdomain as ${S1_SUBDOMAIN}.
3. In your browser, call https://${S1_SUBDOMAIN}.authentication.${S1_LANDSCAPE_DOMAIN}/
saml/metadata and download the XML file. Within the XML file you can find the following structure:
Sample Code
<?xml version="1.0" encoding="UTF-8"?>
...
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:
2.0:bindings:URI" Location="https://${S1_SUBDOMAIN}.authentication.$
{S1_LANDSCAPE_DOMAIN}/oauth/token/alias/<alias>" index="1"/>
...
Below, we refer to the value of <alias> as ${S1_ALIAS}.
4. Assemble the new IdP metadata for subaccount 1 by replacing the ${...} placeholders in the following
template with the values determined in the previous steps:
Sample Code
<ns3:EntityDescriptor
ID="cfapps.${S1_LANDSCAPE_DOMAIN}/${S1_SUBACCOUNT_ID}"
entityID="cfapps.${S1_LANDSCAPE_DOMAIN}/${S1_SUBACCOUNT_ID}"
xmlns="http://www.w3.org/2000/09/xmldsig#"
144 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-144-320.jpg)
![xmlns:ns2="http://www.w3.org/2001/04/xmlenc#"
xmlns:ns4="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:ns3="urn:oasis:names:tc:SAML:2.0:metadata">
<ns3:SPSSODescriptor AuthnRequestsSigned="true"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<ns3:KeyDescriptor use="signing">
<KeyInfo>
<KeyName>${S1_ALIAS}</KeyName>
<X509Data>
<X509Certificate>
${S1_CERTIFICATE}
</X509Certificate>
</X509Data>
</KeyInfo>
</ns3:KeyDescriptor>
</ns3:SPSSODescriptor>
<ns3:IDPSSODescriptor
WantAuthnRequestsSigned="true"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<ns3:KeyDescriptor use="signing">
<KeyInfo>
<KeyName>${S1_ALIAS}</KeyName>
<X509Data>
<X509Certificate>
${S1_CERTIFICATE}
</X509Certificate>
</X509Data>
</KeyInfo>
</ns3:KeyDescriptor>
</ns3:IDPSSODescriptor>
</ns3:EntityDescriptor>
Back to Steps [page 141]
Establish Trust between Subaccount 1 and Subaccount 2
1. In the cockpit, navigate to the overview page for subaccount 2.
2. From the left panel, select Security Trust Configuration . Choose New Trust Configuration. For details,
see Establish Trust and Federation with UAA Using Any SAML Identity Provider.
3. Paste the assembled IdP metadata for subaccount 1 in the <Metadata> text box and uncheck Available for
User Logon.
SAP BTP Connectivity
Connectivity PUBLIC 145](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-145-320.jpg)
![4. Choose Parse.
5. Enter a <Name> for the trust configuration and choose Save.
Note
Additionally, you must add users to this new trust configuration and assign appropriate scopes to them.
Back to Steps [page 141]
Create an OAuthSAMLBearerAssertion Destination for Application 1
1. In the cockpit, navigate to the overview page for subaccount 2.
2. Here you can see the landscape domain, subaccount ID and subdomain of subaccount 2. Below, we refer to
the landscape domain as ${S2_LANDSCAPE_DOMAIN}, to the subaccount ID as ${S2_SUBACCOUNT_ID}
and to the subdomain as ${S2_SUBDOMAIN}.
146 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-146-320.jpg)
![Property Value
Token Service URL Type Dedicated
Token Service User The clientid of the XSUAA instance in subaccount 2. Can
be acquired via a binding or service key.
Token Service Password The clientsecret of the XSUAA instance in subaccount 2.
Can be acquired via a binding or service key.
authnContextClassRef urn:oasis:names:tc:SAML:
2.0:ac:classes:PreviousSession
Additional Properties
Property Value
nameIdFormat urn:oasis:names:tc:SAML:1.1:nameid-
format:emailAddress
Example
7. Choose Save.
Back to Steps [page 141]
Consume the Destination and Execute the Scenario
To perform the scenario and execute the request from application 1, targeting application 2, proceed as follows:
1. Decide on where the user identity will be located when calling the Destination service. For details, see User
Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. This will determine how exactly you will
perform step 2.
2. Execute a "find destination" request from application 1 to the Destination service. For details, see
Consuming the Destination Service [page 189] and the REST API documentation .
148 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-148-320.jpg)
![3. From the Destination service response, extract the access token and URL, and construct your request to
application 2. See "Find Destination" Response Structure [page 196] for details on the structure of the
response from the Destination service.
Back to Steps [page 141]
1.1.3.4.5 Scenario: User Propagation from the Cloud
Foundry Environment to the Neo Environment
Propagate the identity of a user from a Cloud Foundry application to a Neo application.
Steps
Scenario [page 149]
Prerequisites [page 150]
Concept [page 150]
Procedure [page 151]
1. Configure a Local Service Provider for the Neo Subaccount [page 151]
2. Establish Trust between Cloud Foundry and Neo Subaccounts [page 152]
3. Create an OAuth Client for the Neo Application [page 154]
4. Create an OAuth2SAMLBearerAssertion Destination for the Cloud Foundry Application [page 154]
5. Consume the Destination and Execute the Scenario [page 156]
Scenario
● You have deployed an application in the Cloud Foundry environment.
● You want to consume OAuth protected APIs exposed by an application deployed in the Neo environment.
● You want to propagate the identity of the user logged in to the Cloud Foundry application, to the Neo
application.
Back to Steps [page 149]
SAP BTP Connectivity
Connectivity PUBLIC 149](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-149-320.jpg)
![Prerequisites
● You have deployed an application in the Cloud Foundry environment.
● You have bound an instance of the Destination Service to the application.
● You have bound an instance of the XSUAA service with the application plan to the application.
● You have deployed an application in the Neo environment.
Back to Steps [page 149]
Concept
The identity of a user logged in to the Cloud Foundry application is established by an identity provider (IdP).
Note
You can use the default IdP of the Cloud Foundry subaccount or any trusted IdP, for example, the Neo
subaccount IdP.
When the application retrieves an OAuthSAMLBearer destination, the user is made available to Cloud Foundry
Destination service by means of a user exchange JWT (JSON Web Token).
The service then wraps the user identity in a SAML assertion, signs it with the Cloud Foundry subaccount
private key and sends it to the token endpoint of the OAuth service for the Neo application.
To make the Neo application accept the SAML assertion, you must set up a trust relationship between the Neo
subaccount and the Cloud Foundry subaccount public key. You can achieve this by adding the Cloud Foundry
subaccount X.509 certificate as trusted IdP in the Neo subaccount. Thus, the Cloud Foundry application starts
acting as an IdP and any users propagated by it are accepted by the Neo application, even users that do not
exist in the IdP.
The OAuth service accepts the SAML assertion and returns an OAuth access token. In turn, the Destination
service returns both the destination and the access token to the requesting application. The application then
uses the destination properties and the access token to consume the remote API.
150 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-150-320.jpg)
![Back to Steps [page 149]
Procedure
Configure a Local Service Provider for the Neo Subaccount
1. In the cockpit, navigate to your Neo subaccount, choose Security Trust from the left menu, and go to
tab Local Service Provider on the right. For <Configuration Type>, select Custom and choose Generate
Key Pair.
2. Save the configuration.
SAP BTP Connectivity
Connectivity PUBLIC 151](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-151-320.jpg)
![ Note
IMPORTANT: When you choose Custom for the Local Service Provider type, the default IdP (SAP ID service)
will no longer be available. If your scenario requires login to the SAP ID service as well, you can safely skip
this step and leave the default settings for the Local Service Provider.
Back to Steps [page 149]
Establish Trust between Cloud Foundry and Neo Subaccounts
1. Download the X.509 certificate of the Cloud Foundry subaccount:
In the cockpit, navigate to your Cloud Foundry subaccount and choose Connectivity Destinations .
Press Download Trust to get the certificate for this subaccount.
2. Configure trust in the Neo subaccount:
In the cockpit, navigate to your Neo subaccount, choose Trust from the left menu, and select the
Application Identity Provider tab on the right. Then choose Add Trusted Identity Provider.
152 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-152-320.jpg)
![In the <Name> field, enter the cfapps host followed by the subaccount GUID, for example
cfapps.sap.hana.ondemand.com/bf7f2876-5080-40ad-a56b-fff3ee5cff9d. This information is
available in the cockpit, on the overview page of your Cloud Foundry subaccount:
In the <Signing Certificate> field, paste the X.509 certificate you downloaded in step 1. Make sure
you remove the BEGIN CERTIFICATE and END CERTIFICATE strings. Then check Only for IDP-Initiated SSO
and save the configuration:
Back to Steps [page 149]
SAP BTP Connectivity
Connectivity PUBLIC 153](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-153-320.jpg)
![Create an OAuth Client for the Neo Application
1. In the cockpit, navigate to the Neo subaccount, choose Security OAuth from the left menu, select
tab Client, and choose Register New Client:
2. Enter a <Name> for the client.
3. In the <Subscription> field, select your Neo application.
4. For <Authorization Grant> select Authorization Code.
5. Check the Confidential checkbox and provide a secret for the OAuth client.
Note
Make sure you remember the secret, because it will not be visible later.
6. <Redirect URI> is irrelevant for the OAuth SAML Bearer Assertion flow, so you can provide any URL in
the Cloud Foundry application.
Back to Steps [page 149]
Create an OAuth2SAMLBearerAssertion Destination for the Cloud Foundry Application
1. In the cockpit, navigate to the Cloud Foundry subaccount, choose Connectivity Destinations from
the left menu, select the Client tab and press New Destination.
2. Enter a <Name> for the destination, then provide:
○ <URL>: the URL of the Neo application/API you want to consume.
154 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-154-320.jpg)
![Back to Steps [page 149]
Consume the Destination and Execute the Scenario
To perform the scenario and execute the request from the source application towards the target application,
proceed as follows:
1. Decide on where the user identity will be located when calling the Destination service. For details, see User
Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. This will determine how exactly you will
perform step 2.
2. Execute a "find destination" request from the source application to the Destination service. For details, see
Consuming the Destination Service [page 189] and the REST API documentation .
3. From the Destination service response, extract the access token and URL, and construct your request to
the target application. See "Find Destination" Response Structure [page 196] for details on the structure of
the response from the Destination service.
Back to Steps [page 149]
1.1.3.5 Multitenancy in the Connectivity Service
Using multitenancy for Cloud Foundry applications that require a connection to a remote service or on-premise
application.
Endpoint Configuration
Applications that require a connection to a remote service can use the Connectivity service to configure HTTP
or RFC endpoints. In a provider-managed application, such an endpoint can either be once defined by the
application provider (Provider-Specific Destination [page 157]), or by each application subscriber (Subscriber-
Specific Destination [page 158]).
156 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-156-320.jpg)
![If the application needs to use the same endpoint, independently from the current application subscriber, the
destination that contains the endpoint configuration is uploaded by the application provider. If the endpoint
should be different for each application subscriber, the destination can be uploaded by each particular
application subscriber.
Note
This connectivity type is fully applicable also for on-demand to on-premise connectivity.
Destination Levels
You can configure destinations simultaneously on two levels: subaccount and service instance. This means that
it is possible to have one and the same destination on more than one configuration level. For more information,
see Managing Destinations [page 38].
Destination lookup according to the level, when configured on:
Level Lookup
Subaccount level Looked up on subaccount level, no matter which destination
service instance is used.
Service instance level Lookup via particular service instance (in provider or sub
scriber subaccount associated with this service instance).
When the application accesses the destination at runtime, the Connectivity service does the following:
● For a destination associated with a provider subaccount:
1. Checks if the destination is available on the service instance level. If there is no destination found, it
2. Searches the destination on subaccount level.
● For a destination associated with a subscriber subaccount:
1. Checks if the destination is available on the subscription level. If there is no destination found, it
2. Searches the destination on subaccount level.
Back to Top [page 156]
Provider-Specific Destination
SAP BTP Connectivity
Connectivity PUBLIC 157](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-157-320.jpg)
![Back to Top [page 156]
Subscriber-Specific Destination
Back to Top [page 156]
Related Information
Developing Multitenant Applications in the Cloud Foundry Environment
158 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-158-320.jpg)
![1.1.3.6 Create and Bind a Connectivity Service Instance
To use the Connectivity service in your application, you need an instance of the service.
Prerequisites
When using service plan “lite”, quota management is no longer required for this service. From any subaccount
you can consume the service using service instances without restrictions on the instance count.
Previously, access to service plan “lite” has been granted via entitlement and quota management of the
application runtime. It has now become an integral service offering of SAP BTP to simplify its usage. See also
Entitlements and Quotas.
Procedure
You have two options for creating a service instance – using the CLI or using the SAP BTP cockpit:
● Create and Bind a Service Instance from the CLI [page 159]
○ Example [page 159]
○ Result [page 161]
● Create and Bind a Service Instance from the Cockpit [page 160]
○ Result [page 161]
Create and Bind a Service Instance from the CLI
Use the following CLI commands to create a service instance and bind it to an application:
1. cf marketplace
2. cf create-service connectivity <service-plan> <service-name>
3. cf bind-service <app-name> <service-name>
Back to Procedure [page 159]
Example
To bind an instance of the Connectivity service "lite" plan to application "myapp", use following commands on
the Cloud Foundry command line:
SAP BTP Connectivity
Connectivity PUBLIC 159](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-159-320.jpg)
![cf create-service connectivity lite myinstance
cf bind-service myapp myinstance
Back to Procedure [page 159]
Create and Bind a Service Instance from the Cockpit
Assuming that you have already deployed your application to the platform, follow these steps to create a
service instance and bind it to an application:
1. In the SAP BTP Cockpit, navigate to your application.
2. From the left navigation menu, choose Service Bindings.
3. Choose the Bind Service button.
4. The Bind Service wizard appears.
5. Select the Service from the catalog radio button, then choose Next.
6. From the list of available services, select Connectivity, then choose Next.
7. On the next page of the wizard, select the Create new instance radio button.
8. Leave <Plan> lite selected and choose Next.
9. The next page is used for specifying user-provided parameters in JSON format. If you do not want to do
that, skip this step by choosing Next.
10. In the <Instance Name> textbox, enter an unique name for your service instance.
11. Choose Finish.
160 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-160-320.jpg)
![Back to Procedure [page 159]
Result
When the binding is created, the application gets the corresponding connectivity credentials in its environment
variables:
Sample Code
"VCAP_SERVICES": {
"connectivity": [
{
"credentials": {
"onpremise_proxy_host": "10.0.85.1",
"onpremise_proxy_port": "20003",
"onpremise_proxy_http_port": "20003",
"clientid": "sb-connectivity-app",
"clientsecret": "KXqObiN6d9gLA4cS2rOVAahPCX0=",
"token_service_url": "<token_service_url>",
},
"label": "connectivity",
"name": "conn-lite",
"plan": "default",
"provider": null,
"syslog_drain_url": null,
"tags": [
"connectivity",
"conn",
"connsvc"
],
"volume_mounts": []
}
],
Note
"onpremise_proxy_http_port" replaces the deprecated variable "onpremise_proxy_port", which
will be removed soon. Same goes for "token_service_url", which replaces "url".
Back to Procedure [page 159]
1.1.3.7 Create and Bind a Destination Service Instance
To use the Destination service in your application, you need an instance of the service.
SAP BTP Connectivity
Connectivity PUBLIC 161](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-161-320.jpg)
![Concept
To consume the Destination service, you must provide the appropriate credentials through a service instance
and a service binding/service key. The Destination service is publicly visible and cross-consumable from
several environments and provides the service plan lite to all those environments. Provisioning a service
instance and service key is done in the standard way for the respective environment, see:
● Cloud Foundry: Using Services in the Cloud Foundry Environment
● Kyma: Using Services in the Kyma Environment
● Kubernetes: Consuming SAP BTP Services in Kubernetes with SAP Service Manager Broker Proxy (Service
Catalog)
● Other environments: Consuming Services in Other Environments Using the SAP Service Manager
Instances
In all environments, the Destination service lets you provide a configuration JSON during instance creation or
update.
Using a Configuration JSON
You can pass a configuration JSON during instance creation or update to modify some of the default settings of
the instance and/or provide some content to be created during the operation.
The detailed structure of the configuration JSON is described in Use a Config.JSON to Create or Update a
Destination Service Instance [page 163].
Troubleshooting
If you get this failure message:
Failed to create all provided configurations. Will delete all on instance level,
for configurations on subaccount level you can set policies to handle
duplicates: "existing_destinations_policy" with value "update|fail|ignore" and
"existing_certificates_policy" with value "fail|ignore".
the root cause may be:
● A provided destination or certificate with the same name already exists in this subaccount. Solution: set
policies on subaccount level to update or ignore in case of conflicts.
"existing_destinations_policy": "update|fail|ignore"
"existing_certificates_policy: "fail|ignore"
● A client input error occurred. Solution: check the input, apply correction and try again.
● An internal server error occurred. In this case, please try again later or report a support incident.
162 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-162-320.jpg)
![1.1.3.7.1 Use a Config.JSON to Create or Update a
Destination Service Instance
Configure specific parameters in a config.json file to create or update a Destination service instance.
When creating or updating a Destination service instance, you can configure the following settings, which are
part of the config.json input file (see Open Service Broker API ), both via SAP BTP cockpit or Cloud
Foundry command line interface (CLI):
Parameter Value Description
init_data JSON The data (destinations, certificates) to
initialise or update the service instance
with. The data can be stored on both
service instance data and subaccount
data.
HTML5Runtime_enabled Boolean Indicates whether the SAP BTP HTML5
runtime should be enabled to work with
the service instance on behalf of the
HTML5 applications associated with it
during deployment.
Find the config.json structure below:
Sample Code
{
"HTML5Runtime_enabled" : "true",
"init_data" : {
"subaccount" : {
"existing_destinations_policy": "update|fail|ignore",
"existing_certificates_policy": "fail|ignore",
"destinations" : [
{
...
}
],
"certificates" : [
{
...
}
]
},
"instance" : {
"existing_destinations_policy": "update|fail|ignore",
"existing_certificates_policy": "fail|ignore",
"destinations" : [
{
...
}
],
"certificates" : [
{
SAP BTP Connectivity
Connectivity PUBLIC 163](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-163-320.jpg)
![...
}
]
}
}
}
1.1.4 Developing Applications
Consume the Connectivity service and the Destination service from an application in the Cloud Foundry
environment.
Task Description
Consuming the Connectivity Service [page 164] Connect your Cloud Foundry application to an on-premise
system.
Consuming the Destination Service [page 189] Retrieve and store externalized technical information about
the destination that is required to consume a target remote
service from your application.
Invoking ABAP Function Modules via RFC [page 208] Call a remote-enabled function module (RFM) in an on-
premise or cloud ABAP server from your Cloud Foundry ap
plication, using the RFC protocol.
1.1.4.1 Consuming the Connectivity Service
Connect your Cloud Foundry application to an on-premise system via HTTP.
Note
To use the Connectivity service with a protocol other than HTTP, see
● Invoking ABAP Function Modules via RFC [page 208]
● Using the TCP Protocol for Cloud Applications [page 180]
Tasks
164 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-164-320.jpg)
![Task Type Task
Operator and/or Developer
Overview [page 165]
Prerequisites [page 166]
Developer
Basic Steps [page 167]
1. Read Credentials from the Environment Variables [page
168]
2. Provide the Destination Information [page 168]
3. Set up the HTTP Proxy for On-Premise Connectivity
[page 169]
Operator and/or Developer
Additional Steps [page 171]
● Authentication against the On-Premise System [page
171]
● Specify a Cloud Connector Location ID [page 171]
● Multitenancy in the Connectivity Service [page 172]
Overview
Using the Connectivity service, you can connect your Cloud Foundry application to an on-premise system
through the Cloud Connector. To achieve this, you must provide the required information about the target
system (destination), and set up an HTTP proxy that lets your application access the on-premise system.
SAP BTP Connectivity
Connectivity PUBLIC 165](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-165-320.jpg)
![Back to Tasks [page 164]
Prerequisites
● You must be a Global Account member to connect through the Connectivity service with the Cloud
Connector. See Add Members to Your Global Account.
Also Security Administrators (which must be either Global Account members or Cloud Foundry
Organization/Space members) can do it. See Managing Security Administrators in Your Subaccount
[Feature Set A].
Note
To connect a Cloud Connector to your subaccount, you must currently be a Security Administrator.
● You have installed and configured a Cloud Connector in your on-premise landscape for to the scenario you
want to use. See Installation [page 273] and Configuration [page 311].
166 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-166-320.jpg)
![● You have deployed an application in a landscape of the Cloud Foundry environment that complies with the
Business Application Pattern.
● Your application is secured as described in .
● The Connectivity service is a regular service in the Cloud Foundry environment. Therefore, to consume the
Connectivity service from an application, you must create a service instance and bind it to the application.
See Create and Bind a Connectivity Service Instance [page 159].
● To get the required authorization for making on-premise calls through the connected Cloud Connector, the
application must be bound to an instance of the xsuaa service using the service plan 'application'. The
xsuaa service instance acts as an OAuth 2.0 client and grants user access to the bound application. Make
sure you set the xsappname property to the name of the application when creating the instance. Find a
detailed guide for this procedure in section 3. Creation of the Authorization & Trust Management Instance
(aka XSUAA) of the SCN blog How to use SAP BTP Connectivity and Cloud Connector in the Cloud Foundry
environment .
Note
Currently, the only supported protocol for connecting the Cloud Foundry environment to an on-premise
system is HTTP. HTTPS is not needed, since the tunnel used by the Cloud Connector is TLS-encrypted.
Back to Tasks [page 164]
Basic Steps
To consume the Connectivity service from your Cloud Foundry application, perform the following basic steps:
1. Read Credentials from the Environment Variables [page 168]
2. Provide the Destination Information [page 168]
3. Set up the HTTP Proxy for On-Premise Connectivity [page 169]
Back to Tasks [page 164]
SAP BTP Connectivity
Connectivity PUBLIC 167](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-167-320.jpg)
![Read Credentials from the Environment Variables
Consuming the Connectivity service requires credentials from the xsuaa and Connectivity service instances
which are bound to the application. By binding the application to service instances of the xsuaa and
Connectivity service as described in the prerequisites, these credentials become part of the environment
variables of the application. You can access them as follows:
Sample Code
JSONObject jsonObj = new JSONObject(System.getenv("VCAP_SERVICES"));
JSONArray jsonArr = jsonObj.getJSONArray("<service name, not the instance
name>");
JSONObject credentials =
jsonArr.getJSONObject(0).getJSONObject("credentials");
Note
If you have multiple instances of the same service bound to the application, you must perform additional
filtering to extract the correct credential from jsonArr. You must go through the elements of jsonArr and
find the one matching the correct instance name.
This code stores a JSON object in the credentials variable. Additional parsing is required to extract the value for
a specific key.
Note
We refer to the result of the above code block as connectivityCredentials, when called for
connectivity, and xsuaaCredentials for xsuaa.
Back to Tasks [page 164]
Provide the Destination Information
To consume the Connectivity service, you must provide some information about your on-premise system and
the system mappings for it in the Cloud Connector. You require the following:
● The endpoint in the Cloud Connector (virtual host and virtual port) and accessible URL paths on it
(destinations). See Configure Access Control (HTTP) [page 370].
168 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-168-320.jpg)
![● The required authentication type for the on-premise system. See HTTP Destinations [page 64].
● Depending on the authentication type, you may need a username and password for accessing the on-
premise system. For more details, see Client Authentication Types for HTTP Destinations [page 77].
● (Optional) You can use a location Id. For more details, see section Specify a Cloud Connector Location ID
[page 171].
We recommend that you use the Destination service (see Consuming the Destination Service [page 189]) to
procure this information. However, using the Destination service is optional. You can also provide (look up) this
information in another appropriate way.
Back to Tasks [page 164]
Set up the HTTP Proxy for On-Premise Connectivity
Proxy Setup
The Connectivity service provides a standard HTTP proxy for on-premise connectivity that is accessible by any
application. Proxy host and port are available as the environment variables <onpremise_proxy_host> and
<onpremise_proxy_http_port>. You can set up the on-premise HTTP proxy like this:
Sample Code
// get value of "onpremise_proxy_host" and "onpremise_proxy_http_port" from
the environment variables
// and create on-premise HTTP proxy
String connProxyHost =
connectivityCredentials.getString("onpremise_proxy_host");
int connProxyPort =
Integer.parseInt(credentials.getString("onpremise_proxy_http_port"));
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(connProxyHost,
connProxyPort));
// create URL to the remote endpoint you like to call:
// virtualhost:1234 is defined as an endpoint in the Cloud Connector, as
described in the Required Information section
URL url = new URL("http://virtualhost:1234");
// create the connection object to the endpoint using the proxy
// this does not open a connection but only creates a connection object,
which can be modified later, before actually connecting
urlConnection = (HttpURLConnection) url.openConnection(proxy);
Note
"onpremise_proxy_http_port" replaces the deprecated variable "onpremise_proxy_port", which
will be removed soon.
SAP BTP Connectivity
Connectivity PUBLIC 169](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-169-320.jpg)
![@Override
public String getName() {
return "dummyPrincipalName"; // There is no principal in the
client credentials authorization grant but a non-empty name is still required.
}
}).build();
OAuth2AuthorizedClientProvider clientCredentialsAccessTokenProvider = new
ClientCredentialsOAuth2AuthorizedClientProvider();
OAuth2AccessToken token =
clientCredentialsAccessTokenProvider.authorize(xsuaaContext).getAccessToken();
// set access token as Proxy-Authorization header in the URL connection
urlConnection.setRequestProperty("Proxy-Authorization",
token.getTokenType().getValue() + " " + token.getTokenValue());
Note
xsuaaCredentials.getString("token_service_url") replaces the deprecated property
xsuaaCredentials.getString("url"), which will be removed soon.
Back to Tasks [page 164]
Authentication against the On-Premise System
Depending on the required authentication type for the desired on-premise resource, you may have to set an
additional header in your request. This header provides the required information for the authentication process
against the on-premise resource. See Authentication to the On-Premise System [page 173].
Back to Tasks [page 164]
Specify a Cloud Connector Location ID
Note
This is an advanced option when using more than one Cloud Connector for a subaccount. For more
information how to set the location ID in the Cloud Connector, see Managing Subaccounts [page 328],
step 4 in section Subaccount Dashboard.
SAP BTP Connectivity
Connectivity PUBLIC 171](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-171-320.jpg)
![As of Cloud Connector 2.9.0, you can connect multiple Cloud Connectors to a subaccount if their location
ID is different. Using the header SAP-Connectivity-SCC-Location_ID you can specify the Cloud
Connector over which the connection should be opened. If this header is not specified, the connection is
opened to the Cloud Connector that is connected without any location ID. This also applies for all Cloud
Connector versions prior to 2.9.0. For example:
Sample Code
// Optionally, if configured, add the SCC location ID.
urlConnection.setRequestProperty("SAP-Connectivity-SCC-Location_ID",
"orlando");
Back to Tasks [page 164]
Multitenancy in the Connectivity Service
To consume the Connectivity service from an SaaS application in a multitenant way, the only requirement is
that the SaaS application returns the Connectivity service as a dependent service in its dependencies list.
For more information about the subscription flow, see Develop the Multitenant Business Application.
Back to Tasks [page 164]
Related Information
Cloud Connector [page 267]
Set Up an Application as a Sample Backend System
Create and Bind a Connectivity Service Instance [page 159]
Authentication to the On-Premise System [page 173]
Consuming the Destination Service [page 189]
What Is the SAP Authorization and Trust Management Service?
Multitarget Applications in the Cloud Foundry Environment
Security
Invoking ABAP Function Modules via RFC [page 208]
Using the TCP Protocol for Cloud Applications [page 180]
172 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-172-320.jpg)
![1.1.4.1.1 Authentication to the On-Premise System
Provide authentication information for the authentication type you use.
You can use the Connectivity service in different authentication scenarios:
● No authentication to the on-premise system
● Principal propagation (user propagation) to the on-premise system
● Basic authentication to the on-premise system
Procedure
For each authentication type, you must provide specific information in the request to the virtual host:
● The SAP-Connectivity-Authentication Header [page 173]
● Authentication Types [page 174]
The SAP-Connectivity-Authentication Header
Note
For the principal propagation scenario, the SAP-Connectivity-Authentication header is only required if you
do not use the user exchange token flow, see Configure Principal Propagation via User Exchange Token
[page 174].
Applications must propagate the user JWT token (userToken) using the SAP-Connectivity-Authentication
header. This is required for the Connectivity service to open a tunnel to the subaccount for which a
configuration is made in the Cloud Connector. The following example shows you how to do this using the
Spring framework:
Sample Code
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
if (auth == null) {
throw new UserInfoException("User not authenticated");
}
OAuth2AuthenticationDetails details = (OAuth2AuthenticationDetails)
auth.getDetails();
String userToken = details.getTokenValue();
urlConnection.setRequestProperty("SAP-Connectivity-Authentication", "Bearer "
+ userToken);
Back to Procedure [page 173]
SAP BTP Connectivity
Connectivity PUBLIC 173](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-173-320.jpg)
![Authentication Types
The required setup for each of the authentication type is as follows:
No Authentication
If the on-premise system does not need to identify the user, you should use this authentication type. It requires
no additional information to be passed with the request.
Principal Propagation
When you open the application router to access your cloud application, you are prompted to log in. Doing so
means that the cloud application now knows your identity. Principal propagation forwards this identity via the
Cloud Connector to the on-premise system. This information is then used to grant access without additional
input from the user. To achieve this, you do not need to send any additional information from your application,
but you must set up the Cloud Connector for principal propagation. See Configuring Principal Propagation
[page 340].
Basic Authentication
If the on-premise system requires username and password to grant access, the cloud application must provide
these data using the Authorization header. The following example shows how to do this:
Sample Code
// Basic authentication to backend system
String credentials = MessageFormat.format("{0}:{1}", backendUser,
backendPassword);
byte[] encodedBytes = Base64.encodeBase64(credentials.getBytes());
urlConnection.setRequestProperty("Authorization", "Basic " + new
String(encodedBytes));
Back to Procedure [page 173]
Related Information
Configure Principal Propagation via User Exchange Token [page 174]
Configure Principal Propagation via OIDC Token [page 178]
1.1.4.1.1.1 Configure Principal Propagation via User Exchange
Token
Configure a user exchange token for principal propagation (user propagation) from your Cloud Foundry
application to an on-premise system.
174 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-174-320.jpg)
![Tasks
Task Type Task
Operator and/or Developer
Scenario [page 175]
Developer
Solutions [page 175]
Generate the Authentication Token [page 176]
Scenario
For a Cloud Foundry application that uses the Connectivity service, you want the currently logged-in user to be
propagated to an on-premise system. For more information, see Principal Propagation [page 121].
Back to Tasks [page 175]
Solutions
You have two options to implement user propagation:
1. Recommended: The application sends one header containing the user exchange token to the Connectivity
proxy:
Header: "Proxy-Authorization" : "Bearer <userExchangeAcessToken>"
This option is described in detail in Generate the Authentication Token [page 176] below.
2. The application sends two headers to the Connectivity proxy:
Header: "SAP-Connectivity-Authentication" : "Bearer <userToken>"
Header: "Proxy-Authorization" : "Bearer <accessToken>"
For more information about this solution, see also Consuming the Connectivity Service [page 164].
SAP BTP Connectivity
Connectivity PUBLIC 175](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-175-320.jpg)
![ Note
This solution is supported to guarantee backward compatibility.
Back to Tasks [page 175]
Generate the Authentication Token
To propagate a user to an on-premise system, you must call the Connectivity proxy using a special JWT (JSON
Web token). This token is obtained by exchanging a valid user token following the OAuth2 JWT Bearer grant
type .
● Example: Obtaining a User Token Following the JWT Bearer Grant Type [page 176]
● Example: Calling the Connectivity Proxy with the Exchanged User Token [page 178]
Example: Obtaining a User Token Following the JWT Bearer Grant Type
Request:
Sample Code
POST https://<host: the value of 'url' from Connectivity service credentials
in VCAP_SERVICES>/oauth/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded
client_id=<connectivity_service_client_id>
client_secret=<connectivity_service_client_secret>
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
token_format=jwt
response_type=token
assertion=<logged-in-user-JWT>
Response:
Sample Code
{
"access_token" : "<new-user-JWT>",
"token_type" : "bearer",
"expires_in" : 43199,
"scope" : "<token-scopes>",
"jti" : "7cc917b8bf6347a2aa18d7ac8f38a1c2"
}
176 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-176-320.jpg)
![See also: XSUAA Token Client and Token Flow API .
After obtaining the userExchangeAcessToken, you can use it to consume the Connectivity service.
Back to Generate the Authentication Token [page 176]
Example: Calling the Connectivity Proxy with the Exchanged User Token
As a prerequisite to this step, you must configure the Connectivity proxy to be used by your client, see Set up
the HTTP Proxy for On-Premise Connectivity [page 169].
Once the application has retrieved the user exchange token, it must pass the token to the Connectivity proxy
via the Proxy-Authorization header. In this example, we use urlConnection as a client.
Sample Code
// set user exchange token as Proxy-Authorization header in the URL connection
urlConnection.setRequestProperty("Proxy-Authorization", "Bearer " +
userExchangeAcessToken);
Note
Alternatively, you can use the basic authentication scheme:
Sample Code
// Basic authentication to Connectivity Proxy
String credentials = MessageFormat.format("{0}:{1}", userExchangeAcessToken,
"");
byte[] encodedBytes = Base64.encodeBase64(credentials.getBytes());
urlConnection.setRequestProperty("Proxy-Authorization", "Basic " + new
String(encodedBytes));
Back to Generate the Authentication Token [page 176]
Back to Tasks [page 175]
1.1.4.1.1.2 Configure Principal Propagation via OIDC Token
Configure an OpenID-Connect (OIDC) token for principal propagation (user propagation) from your Cloud
Foundry application to an on-premise system.
178 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-178-320.jpg)
![Tasks
Task Type Task
Operator and/or Developer
Scenario [page 179]
Developer
Solution [page 179]
Scenario
For a Cloud Foundry application that uses the Connectivity service, you want the currently logged-in user to be
propagated via the Cloud Connector to an on-premise system. This user is represented in the cloud application
by an OIDC token. For more information, see Principal Propagation [page 121] and the OIDC specification .
Back to Tasks [page 179]
Solution
As of version 2.13.0, the Cloud Connector supports principal propagation for OIDC tokens. If on the cloud
application side the user is represented by an OIDC token, the application can send the user principal to the
Connectivity service (thus reaching the Cloud Connector), using the SAP-Connectivity-Authentication
HTTP header.
The Cloud Connector validates the token, extracts the available user data, and enables further processing
through a configured subject pattern for the resulting short-lived X.509 client certificate.
By default, the user principal is identified by one of the following JWT (JSON web token) attributes:
● user_name
SAP BTP Connectivity
Connectivity PUBLIC 179](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-179-320.jpg)
![● email
● mail
● user_uuid
● sub
This list specifies the priority (in descending order from top to bottom) for the default value of ${name} in the
subject pattern of the X.509 client certificate. If a token has more than one of the above claims, the value of $
{name} is extracted from the claim with the highest priority by default.
For the example token below, the default value of ${name} is test@user.com:
Sample Code
{
"aud": "111111111111-2222-3333-444444444444",
"iss": "https://issuer.com",
"exp": 2091269073,
"iat": 1601901108,
"jti": "111222333444555666777888999000",
"sub": "test",
"email": "test@users.com"
}
The Cloud Connector administrator can control the exact value to be used as user principal for the subject CN
of the X.509 client certificate by configuring a subject pattern. For more information, see Configure a Subject
Pattern for Principal Propagation [page 359].
Back to Tasks [page 179]
1.1.4.1.2 Using the TCP Protocol for Cloud Applications
Access on-premise systems from a Cloud Foundry application via TCP-based protocols, using a SOCKS5 Proxy.
Content
Concept [page 181]
Restrictions [page 182]
Example [page 182]
Troubleshooting [page 188]
180 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-180-320.jpg)
![Concept
SAP BTP Connectivity provides a SOCKS5 proxy that you can use to access on-premise systems via TCP-based
protocols. SOCKS5 is the industry standard for proxying TCP-based traffic (for more information, see IETF RFC
1928 ).
The SOCKS5 proxy host and port are accessible through the environment variables, which are generated after
binding an application to a Connectivity service instance. For more information, see Consuming the
Connectivity Service [page 164].
You can access the host under onpremise_proxy_host, and the port through
onpremise_socks5_proxy_port, obtained from the Connectivity service instance.
Authentication to the SOCKS5 proxy is mandatory. It involves the usage of a JWT (JSON Web token) access
token (for more information, see IETF RFC 7519 ). The JWT can be retrieved through the client_id and
client_secret, obtained from the Connectivity service instance. For more information, see Set up the HTTP
Proxy for On-Premise Connectivity [page 169], section Authorization.
The value of the SOCKS5 protocol authentication method is defined as 0x80 (defined as X'80' in IETF, refer to
the official specification SOCKS Protocol Version 5 ). This value should be sent as part of the authentication
method's negotiation request (known as Initial Request in SOCKS5). The server then confirms with a response
containing its decimal representation (either 128 or -128, depending on the client implementation).
After a successful SOCKS5 Initial Request, the authentication procedure follows the standard SOCKS5
authentication sub-procedure, that is SOCKS5 Authentication Request. The request bytes, in sequence, should
look like this:
Bytes Description
1 byte Authentication method version - currently 1
4 bytes Length of the JWT
X bytes X - The actual value of the JWT in its encoded form
1 byte Length of the Cloud Connector location ID (0 if no Cloud
Connector location ID is used)
Y bytes Optional. Y - The value of the Cloud Connector location ID in
base64-encoded form (if the the value of the location ID is
not 0)
The Cloud Connector location ID identifies Cloud Connector instances that are deployed in various locations of
a customer's premises and connected to the same subaccount. Since the location ID is an optional property,
you should include it in the request only if it has already been configured in the Cloud Connector. For more
information, see Set up Connection Parameters and HTTPS Proxy [page 315] (Step 4).
If not set in the Cloud Connector, the byte representing the length of the location ID in the Authentication
Request should have the value 0, without including any value for the Cloud Connector location ID
(sccLocationId).
Back to Content [page 180]
SAP BTP Connectivity
Connectivity PUBLIC 181](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-181-320.jpg)
![Restrictions
● You cannot use the provided SOCKS5 proxy as general-purpose proxy.
● Proxying UDP traffic is not supported.
Back to Content [page 180]
Example
The following code snippet demonstrates an example based on the Apache Http Client library and Java
code, which represents a way to replace the standard socket used in the Apache HTTP client with one that is
responsible for authenticating with the Connectivity SOCKS5 proxy:
Sample Code
@Override
public void connect(SocketAddress endpoint, int timeout) throws IOException {
super.connect(getProxyAddress(), timeout);
OutputStream outputStream = getOutputStream();
executeSOCKS5InitialRequest(outputStream); // 1. Negotiate authentication
method, i.e. 0x80 (128)
executeSOCKS5AuthenticationRequest(outputStream); // 2. Negotiate
authentication sub-version and send the JWT (and optionally the Cloud
Connector Location ID)
executeSOCKS5ConnectRequest(outputStream, (InetSocketAddress)
endpoint); // 3. Initiate connection to target on-premise backend system
}
Sample Code
private byte[] createInitialSOCKS5Request() throws IOException {
ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream();
try {
byteArraysStream.write(SOCKS5_VERSION);
byteArraysStream.write(SOCKS5_AUTHENTICATION_METHODS_COUNT);
byteArraysStream.write(SOCKS5_JWT_AUTHENTICATION_METHOD);
return byteArraysStream.toByteArray();
} finally {
byteArraysStream.close();
}
}
private void executeSOCKS5InitialRequest(OutputStream outputStream) throws
IOException {
byte[] initialRequest = createInitialSOCKS5Request();
outputStream.write(initialRequest);
assertServerInitialResponse();
}
182 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-182-320.jpg)
![ Sample Code
private byte[] createJWTAuthenticationRequest() throws IOException {
ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream();
try {
byteArraysStream.write(SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION);
byteArraysStream.write(ByteBuffer.allocate(4).putInt(jwtToken.getBytes().lengt
h).array());
byteArraysStream.write(jwtToken.getBytes());
byteArraysStream.write(ByteBuffer.allocate(1).put((byte)
sccLocationId.getBytes().length).array());
byteArraysStream.write(sccLocationId.getBytes());
return byteArraysStream.toByteArray();
} finally {
byteArraysStream.close();
}
}
private void executeSOCKS5AuthenticationRequest(OutputStream outputStream)
throws IOException {
byte[] authenticationRequest = createJWTAuthenticationRequest();
outputStream.write(authenticationRequest);
assertAuthenticationResponse();
}
In version 4.2.6 of the Apache HTTP client, the class responsible for connecting the socket is
DefaultClientConnectionOperator. By extending the class and replacing the standard socket with the
complete example code below, which implements a Java Socket, you can handle the SOCKS5 authentication
with ID 0x80. It is based on a JWT and supports the Cloud Connector location ID.
Sample Code
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.InetAddress;
import java.net.InetSocketAddress;
import java.net.Socket;
import java.net.SocketAddress;
import java.net.SocketException;
import java.nio.ByteBuffer;
import java.util.Base64; // or any other library for base64 encoding
import org.json.JSONArray; // or any other library for JSON objects
import org.json.JSONObject; // or any other library for JSON objects
import org.json.JSONException; // or any other library for JSON objects
public class ConnectivitySocks5ProxySocket extends Socket {
private static final byte SOCKS5_VERSION = 0x05;
private static final byte SOCKS5_JWT_AUTHENTICATION_METHOD = (byte) 0x80;
private static final byte SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION = 0x01;
private static final byte SOCKS5_COMMAND_CONNECT_BYTE = 0x01;
private static final byte SOCKS5_COMMAND_REQUEST_RESERVED_BYTE = 0x00;
private static final byte SOCKS5_COMMAND_ADDRESS_TYPE_IPv4_BYTE = 0x01;
private static final byte SOCKS5_COMMAND_ADDRESS_TYPE_DOMAIN_BYTE = 0x03;
private static final byte SOCKS5_AUTHENTICATION_METHODS_COUNT = 0x01;
SAP BTP Connectivity
Connectivity PUBLIC 183](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-183-320.jpg)
![private static final int SOCKS5_JWT_AUTHENTICATION_METHOD_UNSIGNED_VALUE
= 0x80 & 0xFF;
private static final byte SOCKS5_AUTHENTICATION_SUCCESS_BYTE = 0x00;
private static final String SOCKS5_PROXY_HOST_PROPERTY =
"onpremise_proxy_host";
private static final String SOCKS5_PROXY_PORT_PROPERTY =
"onpremise_socks5_proxy_port";
private final String jwtToken;
private final String sccLocationId;
public ConnectivitySocks5ProxySocket(String jwtToken, String
sccLocationId) {
this.jwtToken = jwtToken;
this.sccLocationId = sccLocationId != null ?
Base64.getEncoder().encodeToString(sccLocationId.getBytes()) : "";
}
protected InetSocketAddress getProxyAddress() {
try {
JSONObject credentials = extractEnvironmentCredentials();
String proxyHost =
credentials.getString(SOCKS5_PROXY_HOST_PROPERTY);
int proxyPort =
Integer.parseInt(credentials.getString(SOCKS5_PROXY_PORT_PROPERTY));
return new InetSocketAddress(proxyHost, proxyPort);
} catch (JSONException ex) {
throw new IllegalStateException("Unable to extract the SOCKS5
proxy host and port", ex);
}
}
private JSONObject extractEnvironmentCredentials() throws JSONException {
JSONObject jsonObj = new JSONObject(System.getenv("VCAP_SERVICES"));
JSONArray jsonArr = jsonObj.getJSONArray("connectivity");
return jsonArr.getJSONObject(0).getJSONObject("credentials");
}
@Override
public void connect(SocketAddress endpoint, int timeout) throws
IOException {
super.connect(getProxyAddress(), timeout);
OutputStream outputStream = getOutputStream();
executeSOCKS5InitialRequest(outputStream);
executeSOCKS5AuthenticationRequest(outputStream);
executeSOCKS5ConnectRequest(outputStream, (InetSocketAddress)
endpoint);
}
private void executeSOCKS5InitialRequest(OutputStream outputStream)
throws IOException {
byte[] initialRequest = createInitialSOCKS5Request();
outputStream.write(initialRequest);
assertServerInitialResponse();
}
private byte[] createInitialSOCKS5Request() throws IOException {
ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream();
try {
byteArraysStream.write(SOCKS5_VERSION);
byteArraysStream.write(SOCKS5_AUTHENTICATION_METHODS_COUNT);
byteArraysStream.write(SOCKS5_JWT_AUTHENTICATION_METHOD);
184 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-184-320.jpg)
![return byteArraysStream.toByteArray();
} finally {
byteArraysStream.close();
}
}
private void assertServerInitialResponse() throws IOException {
InputStream inputStream = getInputStream();
int versionByte = inputStream.read();
if (SOCKS5_VERSION != versionByte) {
throw new SocketException(String.format("Unsupported SOCKS
version - expected %s, but received %s", SOCKS5_VERSION, versionByte));
}
int authenticationMethodValue = inputStream.read();
if (SOCKS5_JWT_AUTHENTICATION_METHOD_UNSIGNED_VALUE !=
authenticationMethodValue) {
throw new SocketException(String.format("Unsupported
authentication method value - expected %s, but received %s",
SOCKS5_JWT_AUTHENTICATION_METHOD_UNSIGNED_VALUE,
authenticationMethodValue));
}
}
private void executeSOCKS5AuthenticationRequest(OutputStream
outputStream) throws IOException {
byte[] authenticationRequest = createJWTAuthenticationRequest();
outputStream.write(authenticationRequest);
assertAuthenticationResponse();
}
private byte[] createJWTAuthenticationRequest() throws IOException {
ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream();
try {
byteArraysStream.write(SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION);
byteArraysStream.write(ByteBuffer.allocate(4).putInt(jwtToken.getBytes().lengt
h).array());
byteArraysStream.write(jwtToken.getBytes());
byteArraysStream.write(ByteBuffer.allocate(1).put((byte)
sccLocationId.getBytes().length).array());
byteArraysStream.write(sccLocationId.getBytes());
return byteArraysStream.toByteArray();
} finally {
byteArraysStream.close();
}
}
private void assertAuthenticationResponse() throws IOException {
InputStream inputStream = getInputStream();
int authenticationMethodVersion = inputStream.read();
if (SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION !=
authenticationMethodVersion) {
throw new SocketException(String.format("Unsupported
authentication method version - expected %s, but received %s",
SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION,
authenticationMethodVersion));
}
int authenticationStatus = inputStream.read();
if (SOCKS5_AUTHENTICATION_SUCCESS_BYTE != authenticationStatus) {
throw new SocketException("Authentication failed!");
}
}
SAP BTP Connectivity
Connectivity PUBLIC 185](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-185-320.jpg)
![private void executeSOCKS5ConnectRequest(OutputStream outputStream,
InetSocketAddress endpoint) throws IOException {
byte[] commandRequest = createConnectCommandRequest(endpoint);
outputStream.write(commandRequest);
assertConnectCommandResponse();
}
private byte[] createConnectCommandRequest(InetSocketAddress endpoint)
throws IOException {
String host = endpoint.getHostName();
int port = endpoint.getPort();
ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream();
try {
byteArraysStream.write(SOCKS5_VERSION);
byteArraysStream.write(SOCKS5_COMMAND_CONNECT_BYTE);
byteArraysStream.write(SOCKS5_COMMAND_REQUEST_RESERVED_BYTE);
byte[] hostToIPv4 = parseHostToIPv4(host);
if (hostToIPv4 != null) {
byteArraysStream.write(SOCKS5_COMMAND_ADDRESS_TYPE_IPv4_BYTE);
byteArraysStream.write(hostToIPv4);
} else {
byteArraysStream.write(SOCKS5_COMMAND_ADDRESS_TYPE_DOMAIN_BYTE);
byteArraysStream.write(ByteBuffer.allocate(1).put((byte)
host.getBytes().length).array());
byteArraysStream.write(host.getBytes());
}
byteArraysStream.write(ByteBuffer.allocate(2).putShort((short)
port).array());
return byteArraysStream.toByteArray();
} finally {
byteArraysStream.close();
}
}
private void assertConnectCommandResponse() throws IOException {
InputStream inputStream = getInputStream();
int versionByte = inputStream.read();
if (SOCKS5_VERSION != versionByte) {
throw new SocketException(String.format("Unsupported SOCKS
version - expected %s, but received %s", SOCKS5_VERSION, versionByte));
}
int connectStatusByte = inputStream.read();
assertConnectStatus(connectStatusByte);
readRemainingCommandResponseBytes(inputStream);
}
private void assertConnectStatus(int commandConnectStatus) throws
IOException {
if (commandConnectStatus == 0) {
return;
}
String commandConnectStatusTranslation;
switch (commandConnectStatus) {
case 1:
commandConnectStatusTranslation = "FAILURE";
break;
case 2:
commandConnectStatusTranslation = "FORBIDDEN";
break;
case 3:
commandConnectStatusTranslation = "NETWORK_UNREACHABLE";
break;
186 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-186-320.jpg)
![case 4:
commandConnectStatusTranslation = "HOST_UNREACHABLE";
break;
case 5:
commandConnectStatusTranslation = "CONNECTION_REFUSED";
break;
case 6:
commandConnectStatusTranslation = "TTL_EXPIRED";
break;
case 7:
commandConnectStatusTranslation = "COMMAND_UNSUPPORTED";
break;
case 8:
commandConnectStatusTranslation = "ADDRESS_UNSUPPORTED";
break;
default:
commandConnectStatusTranslation = "UNKNOWN";
break;
}
throw new SocketException("SOCKS5 command failed with status: " +
commandConnectStatusTranslation);
}
private byte[] parseHostToIPv4(String hostName) {
byte[] parsedHostName = null;
String[] virtualHostOctets = hostName.split(".", -1);
int octetsCount = virtualHostOctets.length;
if (octetsCount == 4) {
try {
byte[] ipOctets = new byte[octetsCount];
for (int i = 0; i < octetsCount; i++) {
int currentOctet = Integer.parseInt(virtualHostOctets[i]);
if ((currentOctet < 0) || (currentOctet > 255)) {
throw new
IllegalArgumentException(String.format("Provided octet %s is not in the range
of [0-255]", currentOctet));
}
ipOctets[i] = (byte) currentOctet;
}
parsedHostName = ipOctets;
} catch (IllegalArgumentException ex) {
return null;
}
}
return parsedHostName;
}
private void readRemainingCommandResponseBytes(InputStream inputStream)
throws IOException {
inputStream.read(); // skipping over SOCKS5 reserved byte
int addressTypeByte = inputStream.read();
if (SOCKS5_COMMAND_ADDRESS_TYPE_IPv4_BYTE == addressTypeByte) {
for (int i = 0; i < 6; i++) {
inputStream.read();
}
} else if (SOCKS5_COMMAND_ADDRESS_TYPE_DOMAIN_BYTE ==
addressTypeByte) {
int domainNameLength = inputStream.read();
int portBytes = 2;
inputStream.read(new byte[domainNameLength + portBytes], 0,
domainNameLength + portBytes);
}
}
}
SAP BTP Connectivity
Connectivity PUBLIC 187](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-187-320.jpg)
![Back to Example [page 182]
Back to Content [page 180]
Troubleshooting
If the handshake with the SOCKS5 proxy server fails, a SOCKS5 protocol error is returned, see IETF RFC 1928
. The table below shows the most common errors and their root cause in the scenario you use:
SOCSK5 Error Code Technical Description
Client-Side Error Descrip
tion Scenario Error
0x00 SUCCESS Success
0x01 FAILURE Connection closed by back
end or general scenario fail
ure.
0x02 FORBIDDEN Connection not
allowed by ruleset
No matching host mapping
found in Cloud Connector ac
cess control settings, see
Configure Access Control
(TCP) [page 386].
0x03 NETWORK_UNREACHABLE The Cloud Connector is not
connected to the subaccount
and the Cloud Connector
Location ID that is used
by the cloud application can't
be identified. See Connect
and Disconnect a Cloud Sub
account [page 514] and
Managing Subaccounts
[page 328], section Proce
dure.
0x04 HOST_UNREACHABLE Cannot open connection to
the backend, that is, the host
is unreachable.
0x05 CONNECTION_REFUSED Authentication failure
0x06 TTL_EXPIRED Not used
0x07 COMMAND_UNSUPPORTED Only the SOCKS5 CONNECT
command is supported.
0x08 ADDRESS_UNSUPPORTED Only the SOCKS5 DOMAIN
and IPv4 commands are
supported.
Back to Content [page 180]
188 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-188-320.jpg)
![1.1.4.2 Consuming the Destination Service
Retrieve and store externalized technical information about the destination to consume a target remote service
from your Cloud Foundry application.
Tasks
Task Type Task
Operator and/or Developer
Overview [page 189]
Prerequisites [page 190]
Developer
Steps [page 191]
1. Read Credentials from the Environment Variables [page
191]
2. Generate a JSON Web Token (JWT) [page 192]
3. Call the Destination Service [page 193]
Operator and/or Developer
Destination Configuration Attributes [page 196]
Overview
The Destination service lets you find the destination information that is required to access a remote service or
system from your Cloud Foundry application.
● For the connection to an on-premise system, you can optionally use this service, together with (i.e. in
addition to) the Connectivity service, see Consuming the Connectivity Service [page 164].
● For the connection to any other Web application (remote service), you can use the Destination service
without the Connectivity service.
Consuming the Destination Service includes user authorization via a JSON Web Token (JWT) that is provided
by the xsuaa service.
SAP BTP Connectivity
Connectivity PUBLIC 189](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-189-320.jpg)
![Back to Tasks [page 189]
Prerequisites
● To manage destinations and certificates on service instance level (all CRUD operations), you must be
assigned to one of the following roles: OrgManager, SpaceManager or SpaceDeveloper.
Note
The role SpaceAuditor has only Read permission for destinations and certificates.
● To consume the Destination service from an application, you must create a service instance and bind it to
the application. See Create and Bind a Destination Service Instance [page 161].
● To generate the required JSON Web Token (JWT), you must bind the application to an instance of the xsuaa
service using the service plan 'application'. The xsuaa service instance acts as an OAuth 2.0 client and
190 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-190-320.jpg)
![grants user access to the bound application. Make sure that you set the xsappname property when
creating the instance. Find a detailed guide for this procedure in section 3. Creation of the Authorization &
Trust Management Instance (aka XSUAA) of the SCN blog How to use SAP BTP Connectivity and Cloud
Connector in the Cloud Foundry environment .
● You need at least one configured destination, otherwise there will be nothing to retrieve via the service.
To access the Destinations editor in the cockpit, follow the steps in Access the Destinations Editor [page
40].
To manage destinations via REST API, see Destination Service REST API [page 59].
Back to Tasks [page 189]
Steps
To consume the Destination service from your application, perform the following basic steps:
1. Read Credentials from the Environment Variables [page 191]
2. Generate a JSON Web Token (JWT) [page 192]
3. Call the Destination Service [page 193]
Back to Tasks [page 189]
Read Credentials from the Environment Variables
The Destination service stores its credentials in the environment variables. To consume the service, you require
the following information:
● The value of clientid, clientsecret and uri from the Destination service credentials.
SAP BTP Connectivity
Connectivity PUBLIC 191](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-191-320.jpg)
![● The values of url from the xsuaa credentials.
You can access this information as follows:
● From the CLI, the following command lists the environment variables of <app-name>:
cf env <app-name>
● From within the application, the service credential can be accessed as described in Consuming the
Connectivity Service [page 164].
Note
Below, we refer to the JSONObjects, containing the instance credentials as destinationCredentials
(for the Destination service) and xsuaaCredentials (for xsuaa).
Back to Tasks [page 189]
Generate a JSON Web Token (JWT)
Your application must create an OAuth client using the attributes clientid and clientsecret, which are
provided by the Destination service instance. Then, you must retrieve a new JWT from UAA and pass it in the
Authorization HTTP header.
Two examples how to achieve this (Java and cURL):
Java:
For a Java application, you can use a library that implements the client credentials OAuth flow. Here is an
example of how the clientCredentialsTokenFlow can be obtained using the XSUAA Token Client and
Token Flow API :
Caution
Make sure you get the latest API version.
A sample Maven dependency declaration:
<dependency>
<groupId>com.sap.cloud.security.xsuaa</groupId>
<artifactId>token-client</artifactId>
<version><latest version (e.g.: 2.7.7)></version>
</dependency>
192 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-192-320.jpg)
![ Remember
The XSUAA Token Client library works with multiple HTTP client libraries. Make sure you have one as Maven
dependency.
The following sample uses the Apache REST client:
Sample Code
// get value of "clientid" and "clientsecret" from the environment variables
String clientid = destinationCredentials.getString("clientid");
String clientsecret = destinationCredentials.getString("clientsecret");
// get the URL to xsuaa from the environment variables
URI xsuaaUri = new URI(xsuaaCredentials.getString("url"));
// use the XSUAA client library to ease the implementation of the user token
exchange flow
XsuaaTokenFlows tokenFlows = new XsuaaTokenFlows(new
DefaultOAuth2TokenService(), new XsuaaDefaultEndpoints(xsUaaUri.toString()),
new ClientCredentials(clientid, clientsecret));
String jwtToken =
tokenFlows.clientCredentialsTokenFlow().execute().getAccessToken();
For more information about caching, see also XSUAA Token Client and Token Flow API - Cache .
cURL:
Sample Code
curl -X POST
<xsuaa-url>/oauth/token
-H 'authorization: Basic <<clientid>:<clientsecret> encoded with Base64>'
-H 'content-type: application/x-www-form-urlencoded'
-d 'client_id=<clientid>&grant_type=client_credentials'
Back to Tasks [page 189]
Call the Destination Service
When calling the Destination service, use the uri attribute, provided in VCAP_SERVICES, to build the request
URLs.
Read a Destination by only Specifying its Name ("Find Destination") [page 194]
SAP BTP Connectivity
Connectivity PUBLIC 193](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-193-320.jpg)
![Read a Destination Associated with a Subaccount [page 194]
Get All Destinations Associated with a Subaccount [page 195]
Response Codes [page 196]
Read a Destination by only Specifying its Name ("Find Destination")
This lets you provide simply a name of the destination while the service will search for it. First, the service
searches the destinations that are associated with the service instance. If none of the destinations match the
requested name, the service searches the destinations that are associated with the subaccount.
● Path: /destination-configuration/v1/destinations/<destination-name>
● Example of a call (cURL):
Sample Code
curl "<uri>/destination-configuration/v1/destinations/<destination-name>"
-X GET
-H "Authorization: Bearer <jwtToken>"
● Example of a response (this is a destination found when going through the subaccount destinations):
Sample Code
{
"owner":
{
"SubaccountId":<id>,
"InstanceId":null
},
"destinationConfiguration":
{
"Name": "demo-internet-destination",
"URL": "http://www.google.com",
"ProxyType": "Internet",
"Type": "HTTP",
"Authentication": "NoAuthentication"
}
}
Note
The response from this type of call contains not only the configuration of the requested destination, but
also some additional data. See "Find Destination" Response Structure [page 196].
Back to Call the Destination Service [page 193]
Read a Destination Associated with a Subaccount
This lets you retrieve the configurations of a destination that is defined within a subaccount, by providing the
name of the destination.
● Path: /destination-configuration/v1/subaccountDestinations/<destination-name>
194 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-194-320.jpg)
![● Example of a call (cURL):
Sample Code
curl "<uri>/destination-configuration/v1/subaccountDestinations/
<destination name>"
-X GET
-H "Authorization: Bearer <jwtToken>"
● Example of a response:
Sample Code
{
"Name": "demo-internet-destination",
"URL": "http://www.google.com",
"ProxyType": "Internet",
"Type": "HTTP",
"Authentication": "NoAuthentication"
}
Back to Call the Destination Service [page 193]
Get All Destinations Associated with a Subaccount
This lets you retrieve the configurations of all destinations that are defined within a subaccount.
● Path: /destination-configuration/v1/subaccountDestinations
● Example of a call (cURL):
Sample Code
curl "<uri>/destination-configuration/v1/subaccountDestinations"
-X GET
-H "Authorization: Bearer <jwtToken>"
● Example of a response:
Sample Code
[
{
"Name": "demo-onpremise-destination1",
"URL": "http:/virtualhost:1234",
"ProxyType": "OnPremise",
"Type": "HTTP",
"Authentication": "NoAuthentication"
},
{
"Name": "demo-onpremise-destination2",
"URL": "http:/virtualhost:4321",
"ProxyType": "OnPremise",
"Type": "HTTP",
"Authentication": "BasicAuthentication",
"User": "myname123",
"Password": "123456"
}
]
SAP BTP Connectivity
Connectivity PUBLIC 195](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-195-320.jpg)
![Back to Call the Destination Service [page 193]
Response Codes
When calling the Destination service, you may get the following response codes:
● 200: OK (Json of Destination)
● 401: Unauthorized (Authentication Failed)
● 403: Forbidden (Authorization Failed)
● 404: The requested destination could not be found (not applicable to 'get all destinations associated with a
subaccount')
● 500: Internal Server Error
Back to Call the Destination Service [page 193]
Back to Tasks [page 189]
Destination Configuration Attributes
The JSON object that serves as the response of a successful request (value of the
destinationConfiguration property for "Find destination") can have different attributes, depending on the
authentication type and proxy type of the corresponding destination. See HTTP Destinations [page 64].
Back to Tasks [page 189]
Related Information
User Propagation via SAML 2.0 Bearer Assertion Flow [page 200]
Destination Service REST API [page 59]
Exchanging User JWTs via OAuth2UserTokenExchange Destinations [page 204]
Use Cases [page 211]
Multitenancy in the Destination Service [page 206]
1.1.4.2.1 "Find Destination" Response Structure
Overview of data that are returned by the Destination service for the call type "find destination".
196 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-196-320.jpg)
![Response Structure
When you use the "find destination" call (read a destination by only specifying its name), the structure of the
response includes four parts:
● The owner of the destination [page 197].
● The actual destination configuration [page 197].
● (Optional) Authentication tokens [page 198] that are relevant to the destination.
● (Optional) Certificates [page 199] that are relevant to the destination.
Each of these parts is represented in the JSON object as a key-value pair and their values are JSON objects, see
Example [page 199].
See also Call the Destination Service [page 193].
Destination Owner
● Key: owner
The JSON object that represents the value of this property contains two properties itself: SubaccountId
and InstanceId. Depending on where the destination was found (as a service instance destination or a
subaccount destination) one of these properties has the value null, and the other one shows the ID of the
subaccount/service instance, to which the destination belongs.
● Example:
Sample Code
"owner": {
"SubaccountId": "9acf4877-5a3d-43d2-b67d-7516efe15b11",
"InstanceId": null
}
Back to Response Structure [page 197]
Destination Configuration
● Key: destinationConfiguration
The JSON object that represents the value of this property contains the actual properties of the
destination. To learn more about the available properties, see HTTP Destinations [page 64].
● Example:
Sample Code
"destinationConfiguration": {
SAP BTP Connectivity
Connectivity PUBLIC 197](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-197-320.jpg)
!["Name": "TestBasic",
"Type": "HTTP",
"URL": "http://sap.com",
"Authentication": "BasicAuthentication",
"ProxyType": "OnPremise",
"User": "test",
"Password": "pass12345"
}
Back to Response Structure [page 197]
Authentication Tokens
Note
This property is only applicable to destinations that use the following authentication types:
BasicAuthentication, OAuth2SAMLBearerAssertion, OAuth2ClientCredentials, OAuthUserTokenExchange,
OAuth2JWTBearer, OAuth2Password, and SAPAssertionSSO.
● Key: authTokens
The JSON array that represents the value of this property contains tokens that are required for
authentication. These tokens are represented by JSON objects with these properties (expect more new
properties to be added in the future):
○ type: the type of the token.
○ value: the actual token.
○ http_header: JSON object containing the prepared token in the correct format. The <key> field
contains the key of the HTTP header. The <value> field contains the value of the header.
○ expires_in (only in OAuth2 destinations): The lifetime in seconds of the access token. For example,
the value "3600" denotes that the access token will expire in one hour from the time the response was
generated.
○ error (optional): if the retrieval of the token fails, the value of both type and value is an empty string
and this property shows an error message, explaining the problem.
○ scope (optional) (only in OAuth2 destinations): The scopes issued with the token. The value of the
scope parameter is expressed as a list of space-delimited strings. For example, read write
execute.
● Example:
Sample Code
"authTokens": [
{
"type": "Basic",
"value": "dGVzdDpwYXNzMTIzNDU=",
"http_header": {
"key":"Authorization",
"value":"Basic dGVzdDpwYXNzMTIzNDU="
}
}
198 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-198-320.jpg)
![]
Back to Response Structure [page 197]
Certificates
Note
This property is only applicable to destinations that use the following authentication types:
ClientCertificateAuthentication, OAuth2SAMLBearerAssertion (when default JDK trust store is not used).
● Key: certificates
The JSON array that represents the value of this property contains the certificates, specified in the
destination configuration. These certificates are represented by JSON objects with these properties
(expect more new properties to be added in the future):
○ type
○ content: the encoded content of the certificate.
○ name: the name of the certificate, as specified in the destination configuration.
● Example:
Sample Code
"certificates": [
{
"Name": "keystore.jks",
"Content": "<value>"
"Type": "CERTIFICATE"
},
{
"Name": "truststore.jks",
"Content": "<value>"
"Type": "CERTIFICATE"
}
]
Back to Response Structure [page 197]
Example
Example of a full response for a destination using basic authentication:
Sample Code
{
SAP BTP Connectivity
Connectivity PUBLIC 199](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-199-320.jpg)
!["owner": {
"SubaccountId": "9acf4877-5a3d-43d2-b67d-7516efe15b11",
"InstanceId": null
},
"destinationConfiguration": {
"Name": "TestBasic",
"Type": "HTTP",
"URL": "http://sap.com",
"Authentication": "BasicAuthentication",
"ProxyType": "OnPremise",
"User": "test",
"Password": "pass12345"
},
"authTokens": [
{
"type": "Basic",
"value": "dGVzdDpwYXNzMTIzNDU="
"http_header": {
"key":"Authorization",
"value":"Basic dGVzdDpwYXNzMTIzNDU="
}
}
]
}
Back to Response Structure [page 197]
1.1.4.2.2 User Propagation via SAML 2.0 Bearer Assertion
Flow
Learn about the process for automatic token retrieval, using the OAuth2SAMLBearerAssertion
authentication type for HTTP destinations.
Tasks
Task Type Task
Operator and/or Developer
Prerequisites [page 201]
Developer
Automated Access Token Retrieval [page 201]
● Determine the Propagated User ID [page 201]
● Propagate User Attributes [page 203]
● Scenarios [page 203]
200 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-200-320.jpg)
![Prerequisites
● You have configured an OAuth2SAMLBearerAssertion destination. See OAuth SAML Bearer Assertion
Authentication [page 70].
● Unless using the destination property SystemUser, the user’s identity should be represented by a JSON
Web token (JWT).
Note
Though actually not being a strict requirement, it is likely that you need a user JWT to get the relevant
information. See SAP Authorization and Trust Management Service in the Cloud Foundry Environment.
● If you are using custom user attributes to determine the user, the JWT representing the user (that is
passed to the Destination service) must have the user_attributes scope.
Back to Tasks [page 200]
Automated Access Token Retrieval
For an OAuth2SAMLBearerAssertion destination, you can use the automated token retrieval functionality
that is available via the "find destination" endpoint. See Destination Service REST API [page 59].
Determine the Propagated User ID
There are currently three sources that can provide the propagated user ID. They are prioritized, meaning that
the lookup always starts from the top-priority source and goes down the list. If the propagated user ID is not
found at a given level, the next level is checked. If not found on any level, the operation would fail.
Find the available sources in the table below, in order of their priority.
Propagated User ID: Sources
Source Procedure
System User The system user is a special user ID that is hardcoded in
your destination as value of the SystemUser property. If
you set this property, its value is used as the propagated
user ID.
SAP BTP Connectivity
Connectivity PUBLIC 201](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-201-320.jpg)
![Source Procedure
Field in the JWT In this case, the Destination service looks for the user ID as a
field in the provided JWT. When you make the HTTP call to
the Destination service, you must provide the
Authorization header. The value must be a JWT in its
encoded form (see RFC 7519 ). The procedure is as fol
lows:
● If the userIdSource property is configured in the
destination, its value is the key of the JWT field that will
be the user ID (if there is no such key in the JWT, the
flow proceeds to the next level). There are 2 options:
○ plain string: the exact match is searched on the
root-level element keys of the JWT.
○ JsonPath expression: lets you use non-root-
level elements of the JWT.
● If the userIdSource property is missing, the flow
falls back to the destination property nameIdFormat.
It must have one of the following two values (or not be
set at all), otherwise an exception is thrown:
○ urn:oasis:names:tc:SAML:1.1:nameid-for
mat:emailAddress: the email element of the JWT
is the user ID. If there is no such element in the
JWT, an exception is thrown.
○ urn:oasis:names:tc:SAML:1.1:nameid-format:un
specified (or not set): the user_name element of
the JWT is the user ID. If there is no such element
in the JWT, an exception is thrown.
Custom User Attribute Like Field in the JWT, this source must use the
Authorization header. In this case, its value is used to
retrieve the custom user attributes from the Identity Pro
vider (XSUAA). One of those attributes can be used as the
propagated user ID. The access token from the header must
be a user JWT with the user_attributes scope. Other
wise the custom attributes cannot be retrieved, and the op
eration results in an error.
● If the userIdSource property is configured in the
destination, the same logic applies as for Field in the
JWT, but this time on the JSON containing the custom
user attributes.
● If userIdSource is missing or the desired key is not
found in the custom attributes, the operation fails
(user ID could not be determined).
Back to Tasks [page 200]
202 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-202-320.jpg)
![Propagate User Attributes
You can read additional user attributes from the identity provider (XSUAA), and propagate them as SAML
attributes in the generated SAML bearer assertion.
These attributes are similar to the ones returned by the Cloud Foundry UAA user info endpoint. However, they
may differ depending on the XSUAA behavior, and are specific to the identity provider you use.
For more details about these attributes and possible values, see https:/
/docs.cloudfoundry.org/api/uaa/
version/74.15.0/index.html#user-info .
Note
When adding the attributes, the following rules apply:
● All root elements, except for user_attributes, are added "as is", that is, the attribute name and
value are displayed as seen in the source (user info response structure).
● Elements under the user_attribute key are parsed and added as attributes prefixed with
'user_attributes.'. For example, having {"user_attributes": { "my_param":
"my_value" }} will result in an attribute called 'user_attributes.my_param' with value
'my_value' in the SAML assertion.
In addition to identity provider (XSUAA) user info attributes, there are some more attributes which are read
from the passed JWT. They are located via predefined JsonPath expressions and cannot be controlled by the
end user:
● $.['xs.system.attributes']['xs.saml.groups']
● $.['user_attributes']['xs.saml.groups']
Note
The 'xs.saml.groups' attribute, read from the passed JWT, is renamed to 'Groups' in the resulting
SAML assertion. See also Federation Attribute Settings of Any Identity Provider.
Back to Tasks [page 200]
Scenarios
Refer to the table below to find the JWT requirements for a specific scenario:
Scenario Authorization Header
Propagate a technical user principal, using the
SystemUser property of an
OAuth2SAMLBearerAssertion destination main
tained in the subscriber subaccount, and used by the pro
vider application.
Access token, retrieved
● via the client credentials of the Destination service in
stance (bound to the application).
● using the subscriber's tenant-specific Token
Service URL.
SAP BTP Connectivity
Connectivity PUBLIC 203](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-203-320.jpg)
![Scenario Authorization Header
Propagate a technical user principal, using the
SystemUser property of an
OAuth2SAMLBearerAssertion destination main
tained in the same subaccount where the application is de
ployed.
Access token, retrieved
● via the client credentials of the Destination service in
stance (bound to the application).
● using the provider's tenant-specific Token Service
URL.
Propagate a business user principal, using an
OAuth2SAMLBearerAssertion destination main
tained in the subscriber subaccount where the application
is deployed.
The business user is represented by a JWT that was issued
by the subscriber.
The JWT, previously retrieved from the application
● by exchanging the JWT (that represents the user) to an
other user access token via the client credentials of the
Destination service instance (bound to the application).
● using the subscriber's tenant-specific Token
Service URL.
Propagate a business user principal, using an
OAuth2SAMLBearerAssertion destination main
tained in the same subaccount where the application is de
ployed.
The business user is represented by a JWT that was issued
by the provider.
The JWT, previously retrieved by the application
● by exchanging the JWT (that represents the user) to an
other user access token via the client credentials of the
Destination service instance (bound to the application).
● using the provider's tenant-specific Token Service
URL.
Back to Tasks [page 200]
1.1.4.2.3 Destination Service REST API
Destination service REST API specification for the SAP Cloud Foundry environment.
The Destination service provides a REST API that you can use to read and manage destinations and certificates
on all available levels. This API is documented in the SAP API Business Hub .
It shows all available endpoints, the supported operations, parameters, possible error cases and related status
codes, etc. You can also execute requests using the credentials (for example, the service key) of your
Destination service instance, see Create and Bind a Destination Service Instance [page 161].
1.1.4.2.4 Exchanging User JWTs via
OAuth2UserTokenExchange Destinations
Automatic token retrieval using the OAuth2UserTokenExchange authentication type for HTTP destinations.
204 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-204-320.jpg)
![Content
Prerequisites [page 205]
Automated Access Token Retrieval [page 205]
Scenarios [page 205]
Prerequisites
You have configured an OAuth2UserTokenExchange destination. See OAuth User Token Exchange
Authentication [page 86].
The token to be exchanged must have the uaa.user scope to enable the token exchange. See SAP
Authorization and Trust Management Service in the Cloud Foundry Environment for more details.
Back to Content [page 205]
Automated Access Token Retrieval
For destinations of authentication type OAuth2UserTokenExchange, you can use the automated token
retrieval functionality via the "find destination" endpoint, see Call the Destination Service [page 193].
If you provide the user token exchange header with the request to the Destination service and its value is not
empty, it is used instead of the Authorization header to specify the user and the tenant subdomain. It will be
the token for which token exchange is performed.
● The header value must be a user JWT (JSON Web token) in encoded form, see RFC 7519 .
● If the user token exchange header is not provided with the request to the Destination Service or it is
provided, but its value is empty, the token from the Authorization header is used instead. In this case,
the JWT in the Authorization header must be a user JWT in encoded form, otherwise the token
exchange does not work.
For information about the response structure of this request, see "Find Destination" Response Structure [page
196].
Back to Content [page 205]
Scenarios
SAP BTP Connectivity
Connectivity PUBLIC 205](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-205-320.jpg)
![To achieve specific token exchange goals, you can use the following headers and values when calling the
Destination service:
Goal User Token Exchange Header Authorization Header
Exchange a user token:
● Issued on behalf of the application
provider tenant
● Using a destination in the applica
tion provider tenant
Not used The user token to be
exchanged
Previously retrieved by the application
via exchanging the initial user token,
passed to the application (to another
user access token) via the client cre
dentials of the Destination service in
stance (bound to the application), using
the provider tenant-specific token serv
ice URL.
Exchange a user token:
● Issued on behalf of a tenant, sub
scribed to your application
● Using a destination in the applica
tion provider tenant
<User token to be
exchanged>
Access token
Retrieved via the client credentials of
the Destination service instance (bound
to the application), using the provider
tenant-specific token service URL.
Exchange a user token:
● Issued on behalf of a tenant, sub
scribed to your application
● Using a destination in the sub
scriber tenant
<User token to be
exchanged>
Access token
Retrieved via the client credentials of
the Destination service instance (bound
to the application), using the subscriber
tenant-specific token service URL.
Back to Content [page 205]
1.1.4.2.5 Multitenancy in the Destination Service
Establilsh multitenancy in the Destination service using subscription-level destinations.
Concept
When developing a provider application (SaaS application) that consumes the Destination service, you can
choose between the following destination levels:
206 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-206-320.jpg)
![Level Who has Access and How?
Subaccount Any application using any destination service instance in the
subaccount context. This is the common level for all applica
tions and service instances in the subaccount.
Service Instance Any application using the concrete destination service in
stance in the context of the provider subaccount (the subac
count in which the instance is provisioned). Each service in
stance has its own level.
Subscription Any application using the concrete destination service in
stance in the context of the subscribed subaccount. Each
combination of service instance and subscriber subaccount
is a unique level.
Note
The term level is used here to represent an area or visibility scope. The higher the level, the broader is the
visibility scope.
If you, as an application provider, want to create a destination that is used at runtime only by the subscriber and
that should be visible and accessible only to the subscriber, you can create a subscription-level destination for
each subscriber subaccount (tenant):
Create a Subscription-Level Destination [page 207]
Consume a Subscription-Level Destination [page 208]
Create a Subscription-Level Destination
SAP BTP Connectivity
Connectivity PUBLIC 207](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-207-320.jpg)
![1. Retrieve an OAuth token from the subscriber token service URL using the OAuth client credentials from the
destination service instance, for example:
POST https://{subscriber subdomain}.authentication.{region host}/oauth/token
2. Use the retrieved token from step 1 to create (POST) a subscription-level destination in the Destination
service, see Destinations on service instance (subscription) level in the REST API specification .
Back to Concept [page 206]
Consume a Subscription-Level Destination
1. Retrieve an OAuth token from the subscriber token service URL using the OAuth client credentials from the
destination service instance, for example:
POST https://{subscriber subdomain}.authentication.{region host}/oauth/token
2. Use the token from step 1 to retrieve (GET) the destination stored on subscription level from the
Destination service via:
○ Find a destination in the REST API specification
○ Destinations on service instance (subscription) level in the REST API specification
Back to Concept [page 206]
Related Information
Multitenancy in the Connectivity Service [page 156]
1.1.4.3 Invoking ABAP Function Modules via RFC
Call a remote-enabled function module in an on-premise or cloud ABAP server from your Cloud Foundry
application, using the RFC protocol.
Find the tasks and prerequisites that are required to consume an ABAP function module via RFC, using the
Java Connector (JCo) API as a built-in feature of SAP BTP.
Tasks
208 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-208-320.jpg)
![Task Type Task
Operator
Prerequisites [page 209]
Operator and/or Developer
About JCo [page 209]
Installation Prerequisites for JCo Applications [page 210]
Consume Connectivity via RFC [page 210]
Restrictions [page 211]
Prerequisites
Before you can use RFC communication for an SAP BTP application, you must configure:
● A destination on SAP BTP to use RFC.
For more information, see RFC Destinations [page 110].
● (Only for on-premise backend systems) RFC connectivity between a backend system and the application.
To do this, you must install the Cloud Connector [page 267] in your internal network and configure it to
expose a remote-enabled function module in an ABAP system.
For more information, see Initial Configuration (RFC) [page 321] and Configure Access Control (RFC)
[page 377].
Back to Tasks [page 208]
About JCo
To learn in detail about the SAP JCo API, see the JCo 3.0 documentation on SAP Support Portal .
Note
Some sections of this documentation are not applicable to SAP BTP:
● Architecture: CPIC is only used in the last mile from your Cloud Connector to an on-premise ABAP
backend. From SAP BTP to the Cloud Connector, TLS-protected communication is used.
SAP BTP Connectivity
Connectivity PUBLIC 209](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-209-320.jpg)
![● Installation: SAP BTP runtimes already include all required artifacts.
● Customizing and Integration: On SAP BTP, the integration is already done by the runtime. You can
concentrate on your business application logic.
● Server Programming: The programming model of JCo on SAP BTP does not include server-side RFC
communication.
● IDoc Support for External Java Applications: Currently, there is no IDocLibrary for JCo available on
SAP BTP
Back to Tasks [page 208]
Installation Prerequisites for JCo Applications
● For connections to an on-premise ABAP backend, you have downloaded the Cloud Connector installation
archive from SAP Development Tools for Eclipse and connected the Cloud Connector to your subaccount.
● You have downloaded and set up your Eclipse IDE and the Eclipse Tools for Cloud Foundry .
● You have downloaded the Cloud Foundry CLI, see Tools.
Back to Tasks [page 208]
Consuming Connectivity via RFC
You can call a service from a fenced customer network using an application that consumes a remote-enabled
function module.
Invoking function modules via RFC is enabled by a JCo API that is comparable to the one available in SAP
NetWeaver Application Server Java (version 7.10+), and in JCo standalone 3.0. If you are an experienced JCo
developer, you can easily develop a Web application using JCo: you simply consume the APIs like you do in
other Java environments. Restrictions that apply in the cloud environment are mentioned in the Restrictions
section below.
Find a sample Web application in Scenario: Invoke ABAP Function Modules in On-Premise ABAP Systems [page
212].
Back to Tasks [page 208]
210 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-210-320.jpg)
![Restrictions
● The supported runtime environment is SAP Java Buildpack as of version 1.8.0.
Note
You must use the Tomcat or TomEE runtime offered by the build pack to make JCo work correctly. You
cannot bring a container of your own.
● JCoServer functionality cannot be used within SAP BTP.
● Environment embedding, such as offered by JCo standalone 3.0, is not possible. This is, however, similar
to SAP NetWeaver AS Java.
● Logon authentication only supports user/password credentials (basic authentication) and principal
propagation. See Authentication to the On-Premise System [page 173].
● The supported set of configuration properties is restricted. For details, see RFC Destinations [page 110].
Back to Tasks [page 208]
Related Information
Use Cases [page 211]
1.1.4.3.1 Use Cases
Find instructions for typical RFC end-to-end scenarios that use the Connectivity service and/or the Destination
service (Cloud Foundry environment).
Scenario: Invoke ABAP Function Modules in On-Premise
ABAP Systems [page 212]
Call a function module in an on-premise ABAP system via
RFC, using a sample Web application (Cloud Foundry envi
ronment).
Scenario: Invoke ABAP Function Modules in Cloud ABAP
Systems [page 236]
Call a function module in a cloud ABAP system via RFC, us
ing a sample Web application (Cloud Foundry environment).
Scenario: Multitenancy for JCo Applications (Advanced)
[page 254]
Learn about the required steps to make your Cloud Foundry
JCo application tenant-aware.
SAP BTP Connectivity
Connectivity PUBLIC 211](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-211-320.jpg)
![1.1.4.3.1.1 Scenario: Invoke ABAP Function Modules in On-
Premise ABAP Systems
Call a function module in an on-premise ABAP system via RFC, using a sample Web application (Cloud Foundry
environment).
This scenario performs a remote function call to invoke an ABAP function module, by using the Connectivity
service and the Destination service in the Cloud Foundry environment, as well as a Cloud Foundry application
router.
Tasks
Task Type Task
Operator and/or Developer
Scenario Overview [page 213]
Connectivity User Roles [page 214]
Installation Prerequisites [page 215]
Used Values [page 214]
Developer
Develop a Sample Web Application [page 216]
Operator and/or Developer
Create and Bind Service Instances [page 220]
Developer
Deploy the Application [page 223]
Operator
Configure Roles and Trust [page 225]
Operator and/or Developer
Set Up an Application Router [page 226]
212 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-212-320.jpg)
![Task Type Task
Operator
Configure the RFC Destination [page 230]
Configure the Cloud Connector [page 231]
Operator and/or Developer
Monitoring Your Web Application [page 235] (Optional)
Scenario Overview
Control Flow for Using the Java Connector (JCo) with Basic Authentication
Process Steps:
1. Call through AppRouter (entry point for business applications).
Note
AppRouter is only required you want to use multitenancy or perform user-specific service calls. In all
other cases, JCo uses cloud-security-xsuaa-integration with ClientCredentialFlow.
2. Redirect to XSUAA for login. JSON Web Token (JWT1) is sent to AppRouter and cached there.
SAP BTP Connectivity
Connectivity PUBLIC 213](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-213-320.jpg)
![3. AppRouter calls Web app and sends JWT1 with credentials.
4. Buildpack/XSUAA interaction:
1. Buildpack requests JWT2 to access the Destination service instance (JCo call).
2. Buildpack requests JWT3 to access the Connectivity service instance.
5. Buildpack requests destination configuration (JWT2).
6. Buildpack sends request to the Connectivity service instance (with JWT3 and Authorization Header).
7. Connectivity service forwards request to the Cloud Connector.
8. Cloud Connector sends request to on-premise system.
Since token exchanges are handled by the buildpack, you must only create and bind the service instances, see
Create and Bind Service Instances [page 220].
Back to Tasks [page 212]
Used Values
This scenario uses:
● A subaccount in region Europe (Frankfurt), for which the API endpoint is
api.cf.eu10.hana.ondemand.com.
● The application name jco-demo-<subaccount name>, where <subaccount name> is the subdomain
name of the subaccount. For this example, we use p1234.
Back to Tasks [page 212]
Connectivity User Roles
Different user roles are involved in the cloud to on-premise connectivity end-to-end scenario. The particular
steps for the relevant roles are described below:
IT Administrator
Sets up and configures the Cloud Connector. Scenario steps:
1. Downloads the Cloud Connector from https:/
/tools.hana.ondemand.com/#cloud
2. Installs the Cloud Connector.
3. Establishes an SSL tunnel from the connector to an SAP BTP subaccount.
4. Configures the exposed back-end systems and resources.
Application Developer
Develops Web applications using destinations. Scenario steps:
1. Installs Eclipse IDE, the Cloud Foundry Plugin for Eclipse and the Cloud Foundry CLI.
214 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-214-320.jpg)
![2. Develops a Java EE application using the JCo APIs.
3. Configures connectivity destinations via the SAP BTP cockpit.
4. Deploys and tests the Java EE application on SAP BTP.
Account Operator
Deploys Web applications, creates application routers, creates and binds service instances, conducts tests.
Scenario steps:
1. Obtains a ready Java EE application WAR file.
2. Deploys an application router with respective routes to the application.
3. Creates an XSUAA service instance and binds it to the router.
4. Deploys the Java EE application to an SAP BTP subaccount.
5. Creates a Connectivity service and Destination service instance, and binds them to the application.
6. Creates and manages roles and role collections.
Back to Tasks [page 212]
Installation Prerequisites
● You have downloaded the Cloud Connector installation archive from SAP Development Tools for Eclipse
and connected the Cloud Connector to your subaccount.
● You have downloaded and set up your Eclipse IDE and the Eclipse Tools for Cloud Foundry .
● You have downloaded the Cloud Foundry CLI, see Tools.
Back to Tasks [page 212]
Next Steps
● Develop a Sample Web Application [page 216]
● Create and Bind Service Instances [page 220]
● Deploy the Application [page 223]
● Configure Roles and Trust [page 225]
● Set Up an Application Router [page 226]
● Configure the RFC Destination [page 230]
● Configure the Cloud Connector [page 231]
● Monitoring Your Web Application [page 235] (Optional)
Related Information
Scenario: Multitenancy for JCo Applications (Advanced) [page 254]
SAP BTP Connectivity
Connectivity PUBLIC 215](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-215-320.jpg)
![1.1.4.3.1.1.1 Develop a Sample Web Application
Create a Web application to call an ABAP function module via RFC.
Steps
1. Create a Dynamic Web Project [page 216]
2. Include JCo Dependencies [page 217]
3. Create a Sample Servlet [page 218]
Create a Dynamic Web Project
1. Open the Java EE perspective of the Eclipse IDE.
2. On the Project Explorer view, choose New Dynamic Web Project in the context menu.
3. Enter jco_demo as the project name.
4. In the Target Runtime pane, select Cloud Foundry . If it is not yet in the list of available runtimes, choose
New Runtime and select it from there.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish.
216 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-216-320.jpg)
![Back to Steps [page 216]
Include JCo Dependencies
SAP BTP Connectivity
Connectivity PUBLIC 217](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-217-320.jpg)
![To use JCo functionality seamlessly at compile time in Eclipse, you must include the JCo dependencies into
your web project. Therefore, you must convert it into a maven project.
1. In the Project Explorer view, right-click on the project jco-demo and choose Configure Convert to
Maven Project .
2. In the dialog window, leave the default settings unchanged and choose Finish.
3. Open the pom.xml file and include the following dependency:
<dependencies>
<dependency>
<groupId>com.sap.cloud</groupId>
<artifactId>neo-java-web-api</artifactId>
<version>[3.71.8,4.0.0)</version>
<scope>provided</scope>
</dependency>
</dependencies>
Back to Steps [page 216]
Create a Sample Servlet
1. From the jco_demo project node, choose New Servlet in the context menu.
2. Enter com.sap.demo.jco as the <> and ConnectivityRFCExampleJava as the <Class name>.
Choose Next.
3. Choose Finish to create the servlet and open it in the Java editor.
4. Replace the entire servlet class to make use of the JCo API. The JCo API is visible by default for cloud
applications. You do not need to add it explicitly to the application class path.
Sample Code
package com.sap.demo.jco;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.sap.conn.jco.AbapException;
import com.sap.conn.jco.JCoDestination;
import com.sap.conn.jco.JCoDestinationManager;
import com.sap.conn.jco.JCoException;
import com.sap.conn.jco.JCoFunction;
import com.sap.conn.jco.JCoParameterList;
import com.sap.conn.jco.JCoRepository;
/**
* Sample application that uses the Connectivity
service. In particular, it is
* making use of the capability to invoke a function module in an ABAP
system
218 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-218-320.jpg)
![* via RFC
*
* Note: The JCo APIs are available under <code>com.sap.conn.jco</code>.
*/
@WebServlet("/ConnectivityRFCExample/*")
public class ConnectivityRFCExample extends HttpServlet {
private static final long serialVersionUID = 1L;
protected void doGet(HttpServletRequest request, HttpServletResponse
response)
throws ServletException, IOException {
PrintWriter responseWriter = response.getWriter();
try {
// access the RFC Destination "JCoDemoSystem"
JCoDestination destination =
JCoDestinationManager.getDestination("JCoDemoSystem");
// make an invocation of STFC_CONNECTION in the backend;
JCoRepository repo = destination.getRepository();
JCoFunction stfcConnection =
repo.getFunction("STFC_CONNECTION");
JCoParameterList imports =
stfcConnection.getImportParameterList();
imports.setValue("REQUTEXT", "SAP BTP Connectivity runs with
JCo");
stfcConnection.execute(destination);
JCoParameterList exports =
stfcConnection.getExportParameterList();
String echotext = exports.getString("ECHOTEXT");
String resptext = exports.getString("RESPTEXT");
response.addHeader("Content-type", "text/html");
responseWriter.println("<html><body>");
responseWriter.println("<h1>Executed STFC_CONNECTION in system
JCoDemoSystem</h1>");
responseWriter.println("<p>Export parameter ECHOTEXT of
STFC_CONNECTION:<br>");
responseWriter.println(echotext);
responseWriter.println("<p>Export parameter RESPTEXT of
STFC_CONNECTION:<br>");
responseWriter.println(resptext);
responseWriter.println("</body></html>");
} catch (AbapException ae) {
// just for completeness: As this function module does not
have an exception
// in its signature, this exception cannot occur. But you
should always
// take care of AbapExceptions
} catch (JCoException e) {
response.addHeader("Content-type", "text/html");
responseWriter.println("<html><body>");
responseWriter
.println("<h1>Exception occurred while executing
STFC_CONNECTION in system JCoDemoSystem</h1>");
responseWriter.println("<pre>");
e.printStackTrace(responseWriter);
responseWriter.println("</pre>");
responseWriter.println("</body></html>");
}
}
}
5. Save the Java editor and make sure that the project compiles without errors.
Back to Steps [page 216]
SAP BTP Connectivity
Connectivity PUBLIC 219](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-219-320.jpg)
![Next Steps
● Create and Bind Service Instances [page 220]
● Deploy the Application [page 223]
● Configure Roles and Trust [page 225]
● Set Up an Application Router [page 226]
● Configure the RFC Destination [page 230]
● Configure the Cloud Connector [page 231]
● Monitoring Your Web Application [page 235] (Optional)
1.1.4.3.1.1.2 Create and Bind Service Instances
You must create and bind several service instances, before you can use your application.
Procedure
1. Logon to the cloud cockpit and choose your subaccount.
2. Choose the space where you want to deploy your demo application.
3. Choose Service Marketplace and find these 3 services:
○ Connectivity
○ Destination
○ Authorization & Trust Management (XSUAA)
4. Create and bind a service instance for each of these services.
○ Connectivity service [page 221]
○ Destination service [page 221]
○ Authorization & Trust Management (XSUAA service) [page 222]
220 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-220-320.jpg)
![Connectivity Service
1. Choose Connectivity Create Instance .
2. Insert an instance name (for example, connectivity_jco) and choose Create Instance .
Back to Procedure [page 220]
Destination Service
1. Choose Destination Create Instance .
SAP BTP Connectivity
Connectivity PUBLIC 221](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-221-320.jpg)
![2. Insert an instance name (for example, destination_jco) and choose Create Instance .
Back to Procedure [page 220]
Authorization & Trust Management (XSUAA Service)
1. Choose Authorization & Trust Management Create Instance
2. Select <Service Plan> application.
3. Enter an <Instance Name> and choose Next.
Note
The instance name must match the one defined in the manifest file.
4. In the next tab Parameters, insert the following as a JSON file:
Sample Code
{
"xsappname" : "jco-demo-p1234",
"tenant-mode": "dedicated",
"scopes": [
{
"name": "$XSAPPNAME.all",
"description": "all"
}
],
"role-templates": [
{
"name": "all",
"description": "all",
"scope-references": [
"$XSAPPNAME.all"
]
}
]
}
5. Go to tab Review and choose Create Instance.
Back to Procedure [page 220]
Next Steps
● Deploy the Application [page 223]
● Configure Roles and Trust [page 225]
● Set Up an Application Router [page 226]
● Configure the RFC Destination [page 230]
222 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-222-320.jpg)
![● Configure the Cloud Connector [page 231]
● Monitoring Your Web Application [page 235] (Optional)
1.1.4.3.1.1.3 Deploy the Application
Deploy your Cloud Foundry application to call an ABAP function module via RFC.
Prerequisites
You have created and bound the required service instances, see Create and Bind Service Instances [page 220].
Procedure
1. To deploy your Web application, you can use the following two alternative procedures:
○ Deploying from the Eclipse IDE
○ Deploying from the CLI, see Developing Java in the Cloud Foundry Environment
2. In the following, we publish it with the CLI.
3. To do this, create a manifest.yml file. The key parameter is USE_JCO: true, which must be set to
include JCo into the buildpack during deployment.
manifest.yml
Sample Code
---
applications:
- name: jco-demo-p1234
buildpacks:
- sap_java_buildpack
env:
USE_JCO: true
# This is necessary only if more than one instance is bound
xsuaa_connectivity_instance_name: "xsuaa_jco"
connectivity_instance_name: "connectivity_jco"
destination_instance_name: "destination_jco"
services:
- xsuaa_jco
- connectivity_jco
- destination_jco
SAP BTP Connectivity
Connectivity PUBLIC 223](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-223-320.jpg)
![ Caution
The client libraries (java-security, spring-xsuaa, and container security api for node.js as of version
3.0.6) have been updated. When using these libraries, setting the parameter SAP_JWT_TRUST_ACL has
become obsolete. This update comes with a change regarding scopes:
○ For a business application A calling an application B, it is now mandatory that application B grants
at least one scope to the calling business application A.
○ Business application A must accept these granted scopes or authorities as part of the application
security descriptor.
You can grant scopes using the xs-security.json file.
For more information, see Application Security Descriptor Configuration Syntax, specifically the
sections Referencing the Application and Authorities.
Note
If you have more than one instance of those three services bound to your application, you must specify
which one JCo should use with the respective env parameters:
○ xsuaa_connectivity_instance_name
○ connectivity_instance_name
○ destination_instance_name.
4. In Eclipse, right-click on the project and navigate to Export WAR file .
5. Choose a destination by pressing the Browse... button next to the manifest.yml you created before, for
example as jcodemo.war.
6. Leave the other default settings unchanged and choose Finish to export the WAR file.
7. Perform a CLI login via cf login -a api.cf.eu10.hana.ondemand.com -u
<your_email_address> (password, org and space are prompted after a successful login).
8. Push the application with cf push -f manifest.yml -p jcodemo.war.
9. Now, the application should be deployed successfully.
Next Steps
● Configure Roles and Trust [page 225]
● Set Up an Application Router [page 226]
● Configure the RFC Destination [page 230]
● Configure the Cloud Connector [page 231]
● Monitoring Your Web Application [page 235] (Optional)
224 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-224-320.jpg)
![1.1.4.3.1.1.4 Configure Roles and Trust
Configure a role that enables your user to access your Web application.
To add and assign roles, navigate to the subaccount view of the cloud cockpit and choose Security Role
Collections .
1. Create a new role collection with the name all.
2. From the subaccount menu, choose Trust Configuration.
3. If you don't have a trust configuration, follow the steps in Manually Establish Trust and Federation Between
UAA and Identity Authentication.
4. Click on the IdP name of your choice.
5. Type in your e-mail address and choose Show Assignments.
6. If your user has not yet been added to the SAP ID service, you see following popup. In this case, add your
user now.
7. You should now be able to click Assign Role Collection. Choose role collection all and assign it.
Next Steps
● Set Up an Application Router [page 226]
● Configure the RFC Destination [page 230]
● Configure the Cloud Connector [page 231]
● Monitoring Your Web Application [page 235] (Optional)
SAP BTP Connectivity
Connectivity PUBLIC 225](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-225-320.jpg)
![Related Information
Working with Role Collections
1.1.4.3.1.1.5 Set Up an Application Router
For authentication purposes, configure and deploy an application router for your test application.
Note
AppRouter is only required if you want to use multitenancy or perform user-specific service calls. In all
other cases, JCo uses cloud-security-xsuaa-integration with ClientCredentialFlow.
1. To set up an application router, follow the steps in Application Router or use the demo file approuter.zip
(download).
2. For deployment, you need a manifest file, similar to this one:
Sample Code
---
applications:
- name: approuter-jco-demo-p1234
path: ./
buildpacks:
- nodejs_buildpack
memory: 120M
routes:
- route: approuter-jco-demo-p1234.cfapps.eu10.hana.ondemand.com
env:
NODE_TLS_REJECT_UNAUTHORIZED: 0
destinations: >
[
{"name":"dest-to-example", "url" :"https://jco-demo-
p1234.cfapps.eu10.hana.ondemand.com/ConnectivityRFCExample",
"forwardAuthToken": true }
]
services:
- xsuaa_jco
Note
○ The routes and destination URLs need to fit your test application.
○ In this example, we already bound our XSUAA instance to the application router. Alternatively, you
could also do this via the cloud cockpit.
3. Push the approuter with cf push -f manifest.yml -p approuter.zip.
4. To navigate to the approuter application in the cloud cockpit, choose <your_space> Applications
<your application> Overview .
226 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-226-320.jpg)
![</dependency>
Note
Make sure you don't include this dependency with scope compile transitively with any other jar, for
example, with
<dependency>
<groupId>com.sap.cloud.security</groupId>
<artifactId>java-security</artifactId>
</dependency>
In this case, you must exclude java-api from this dependency and add it again as described above, with
scope provided.
Adjust your code from the step Develop a Sample Web Application [page 216] in the following way:
Sample Code
package com.sap.demo.jco;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.sap.cloud.security.token.SecurityContext;
import com.sap.cloud.security.token.Token;
import com.sap.conn.jco.AbapException;
import com.sap.conn.jco.JCoDestination;
import com.sap.conn.jco.JCoDestinationManager;
import com.sap.conn.jco.JCoException;
import com.sap.conn.jco.JCoFunction;
import com.sap.conn.jco.JCoParameterList;
import com.sap.conn.jco.JCoRepository;
/**
*
* Sample application that uses the connectivity service. In particular, it is
* making use of the capability to invoke a function module in an ABAP system
* via RFC
*
* Note: The JCo APIs are available under <code>com.sap.conn.jco</code>.
*/
@WebServlet("/ConnectivityRFCExample/*")
public class ConnectivityRFCExample extends HttpServlet {
private static final long serialVersionUID = 1L;
protected void doGet(HttpServletRequest request, HttpServletResponse
response)
throws ServletException, IOException {
PrintWriter responseWriter = response.getWriter();
// access the token from the thread which is executing the servlet
Token token = SecurityContext.getToken();
Thread runThread = new Thread(() -> {
// set the information in the newly created thread
SecurityContext.setToken(token);
try {
// access the RFC Destination "JCoDemoSystem"
JCoDestination destination =
JCoDestinationManager.getDestination("JCoDemoSystem_Normal");
// make an invocation of STFC_CONNECTION in the backend
228 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-228-320.jpg)
![Next Steps
● Configure the RFC Destination [page 230]
● Configure the Cloud Connector [page 231]
● Monitoring Your Web Application [page 235] (Optional)
1.1.4.3.1.1.6 Configure the RFC Destination
Configure an RFC destination on SAP BTP that you can use in your Web application to call the on-premise
ABAP system.
To configure the destination, you must use a virtual application server host name (abapserver.hana.cloud)
and a virtual system number (42) that you will expose later in the Cloud Connector. Alternatively, you could use
a load balancing configuration with a message server host and a system ID.
1. Create a .properties file with the following settings:
Name=JCoDemoSystem
Type=RFC
jco.client.ashost=abapserver.hana.cloud
jco.client.sysnr=42
jco.destination.proxy_type=OnPremise
jco.client.user=<DEMOUSER>
jco.client.passwd=<Password>
jco.client.client=000
jco.client.lang=EN
jco.destination.pool_capacity=5
2. Go to your subaccount in the cloud cockpit.
1. From the subaccount menu, choose Connectivity Destinations Import Destination and upload
this file.
2. Alternatively, you can create a destination for the service instance destination_jco to make it
visible only for this instance. To do this, go to <your space> Services Service Instances <your
destination_instance> and choose Destinations.
3. Call again the URL that references the cloud application in the Web browser. The Web application should
now return a different exception:
Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem
com.sap.conn.jco.JCoException: (102) JCO_ERROR_COMMUNICATION: Opening
connection to backend failed: Opening connection to
abapserver.hana.cloud:sapgw42 denied. Expose the system in your Cloud
Connector in case it was a valid request.
at
com.sap.conn.jco.rt.MiddlewareJavaRfc.generateJCoException(MiddlewareJavaRfc.j
ava:487)
at com.sap.conn.jco.rt.MiddlewareJavaRfc
$JavaRfcClient.connect(MiddlewareJavaRfc.java:1216)
at com.sap.conn.jco.rt.ClientConnection.connect(ClientConnection.java:700)
at
com.sap.conn.jco.rt.RepositoryConnection.connect(RepositoryConnection.java:72)
at com.sap.conn.jco.rt.PoolingFactory.init(PoolingFactory.java:113)
at
com.sap.conn.jco.rt.ConnectionManager.createFactory(ConnectionManager.java:
426)
230 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-230-320.jpg)
![at
com.sap.conn.jco.rt.DefaultConnectionManager.createFactory(DefaultConnectionMa
nager.java:46)
at
com.sap.conn.jco.rt.ConnectionManager.getFactory(ConnectionManager.java:376)
at com.sap.conn.jco.rt.RfcDestination.getSystemID(RfcDestination.java:
1101)
..... (cut rest of the call stack)
4. This means that the Cloud Connector denied opening a connection to this system. As a next step, you
must configure the system in your installed Cloud Connector.
Next Steps
● Configure the Cloud Connector [page 231]
● Monitoring Your Web Application [page 235] (Optional)
Related Information
Target System Configuration [page 115]
1.1.4.3.1.1.7 Configure the Cloud Connector
Configure the system mapping and the function module in the Cloud Connector.
Steps
1. Configure Host Mapping [page 231]
2. Configure the Function Module [page 234]
Configure Host Mapping
The Cloud Connector only allows access to trusted backend systems. To configure this, follow the steps below:
1. Optional: In the Cloud Connector administration UI, you can check under Audits whether access has been
denied:
SAP BTP Connectivity
Connectivity PUBLIC 231](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-231-320.jpg)
![Denying access for user DEMOUSER to system abapserver.hana.cloud:sapgw42
[connectionId=-1547299395]
2. In the Cloud Connector administration UI, choose Cloud To On-Premise from your Subaccount menu, tab
Access Control.
3. In section Mapping Virtual To Internal System choose Add to define a new system.
1. For Backend Type, select ABAP System and choose Next.
2. For Protocol, select RFC and choose Next.
3. Choose option Without load balancing.
4. Enter application server and instance number. The Application Server entry must be the physical host
name of the machine on which the ABAP application server is running. Choose Next.
Example:
232 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-232-320.jpg)
![at
com.sap.conn.jco.rt.MiddlewareJavaRfc.generateJCoException(MiddlewareJavaRfc.j
ava:632)
at com.sap.conn.jco.rt.MiddlewareJavaRfc
$JavaRfcClient.execute(MiddlewareJavaRfc.java:1764)
at com.sap.conn.jco.rt.ClientConnection.execute(ClientConnection.java:
1110)
at com.sap.conn.jco.rt.ClientConnection.execute(ClientConnection.java:943)
at com.sap.conn.jco.rt.RfcDestination.execute(RfcDestination.java:1307)
at com.sap.conn.jco.rt.RfcDestination.execute(RfcDestination.java:1278)
at com.sap.conn.jco.rt.AbapFunction.execute(AbapFunction.java:295)
at
com.sap.demo.jco.ConnectivityRFCExample.doGet(ConnectivityRFCExample.java:55)
..... (cut rest of the call stack)
5. This means that the Cloud Connector denied invoking STFC_CONNECTION in this system. As a final step,
you must provide access to this function module.
Back to Steps [page 231]
Configure the Function Module
The Cloud Connector only allows access to explicitly allowed resources (which, in an RFC scenario, are defined
on the basis of function module names). To configure the function module, follow the steps below:
1. Optional: In the Cloud Connector administration UI, you can check under Monitor Audit whether
access has been denied:
Denying access for user DEMOUSER to resource STFC_CONNECTION on system
abapserver.hana.cloud:sapgw42 [connectionId=609399452]
2. In the Cloud Connector administration UI, choose again Cloud To On-Premise from your Subaccount menu,
and go to tab Access Control.
3. For the specified internal system referring to abapserver.hana.cloud, add a new resource. To do this, select
the system in the table.
4. Add a new function name under the list of exposed resources. In section Resources Accessible On
abapserver.hana.cloud:sapgw42, choose the Add button and specify STFC_CONNECTION as accessible
resource, as shown in the screenshot below. Make sure that you have selected the Exact Name option to
only expose this specific function module.
234 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-234-320.jpg)
![5. Call again the URL that references the cloud application in the Web browser. The application should now
return a message showing the export parameters of the function module.
See also Configure Access Control (RFC) [page 377].
Back to Steps [page 231]
Next Step (Optional)
● Monitoring Your Web Application [page 235]
1.1.4.3.1.1.8 Monitoring Your Web Application
Monitor the state and logs of your Web application deployed on SAP BTP, using the Application Logging
service.
For this purpose, create an instance of the Application Logging service (as you did for the Destination and
Connectivity service) and bind it to your application, see Create and Bind Service Instances [page 220].
To activate JCo logging, set the following property in the env section of your manifest file:
SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: INFO}'
Now you can see and open the logs in the cloud cockpit or in the Kibana Dashboard in the tab Logs, if you are
within your application.
SAP BTP Connectivity
Connectivity PUBLIC 235](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-235-320.jpg)
![For detailed information, you can activate the internal JCo logs:
SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: DEBUG, com.sap.conn.jco:
DEBUG}'
Including other relevant components for logging:
SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: DEBUG, com.sap.conn.jco:
DEBUG, com.sap.xs.security: DEBUG, com.sap.cloud.security: DEBUG,
com.sap.xs.env: DEBUG}'
1.1.4.3.1.2 Scenario: Invoke ABAP Function Modules in Cloud
ABAP Systems
Call a function module in a cloud ABAP system via RFC, using a sample Web application (Cloud Foundry
environment).
This scenario performs a remote function call to invoke an ABAP function module, by using the Destination
service in the Cloud Foundry environment, as well as a Cloud Foundry application router.
Tasks
Task Type Task
Operator and/or Developer
Scenario Overview [page 237]
Used Values [page 238]
Connectivity User Roles [page 238]
Installation Prerequisites [page 239]
Developer
Develop a Sample Web Application [page 239]
Operator and/or Developer
Create and Bind Service Instances [page 244]
236 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-236-320.jpg)
![Task Type Task
Developer
Deploy the Application [page 246]
Operator
Configure Roles and Trust [page 248]
Operator and/or Developer
Set Up an Application Router [page 249]
Operator
Configure the RFC Destination [page 253]
Operator and/or Developer
Monitoring Your Web Application [page 254] (Optional)
Scenario Overview
Control Flow for Using the Java Connector (JCo) with Basic Authentication
SAP BTP Connectivity
Connectivity PUBLIC 237](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-237-320.jpg)
![Process Steps:
1. Call through AppRouter (entry point for business applications).
Note
AppRouter is only required you want to use multitenancy or perform user-specific service calls. In all
other cases, JCo uses cloud-security-xsuaa-integration with ClientCredentialFlow.
2. Redirect to XSUAA for login. JSON Web Token (JWT1) is sent to AppRouter and cached there.
3. AppRouter calls Web app and sends JWT1 with credentials.
4. Buildpack/XSUAA interaction: Buildpack requests JWT2 to access the Destination service instance (JCo
call).
5. Buildpack requests destination configuration (JWT2).
6. Buildpack sends request to the cloud ABAP system (with JWT2 and Authorization Header).
Since token exchanges are handled by the buildpack, you must only create and bind the service instances, see
Create and Bind Service Instances [page 220].
Back to Tasks [page 236]
Used Values
This scenario uses:
● A subaccount in region Europe (Frankfurt), for which the API endpoint is
api.cf.eu10.hana.ondemand.com.
● The application name jco-demo-<subaccount name>, where <subaccount name> is the subdomain
name of the subaccount. For this example, we use p1234.
Back to Tasks [page 236]
Connectivity User Roles
Different user roles are involved in the cloud-to-cloud connectivity scenario. The particular steps for the
relevant roles are described below:
Application Developer
Develops Web applications using destinations. Scenario steps:
1. Installs Eclipse IDE, the Cloud Foundry Plugin for Eclipse and the Cloud Foundry CLI.
2. Develops a Java EE application using the JCo APIs.
3. Configures connectivity destinations via the SAP BTP cockpit.
4. Deploys and tests the Java EE application on SAP BTP.
238 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-238-320.jpg)
![Account Operator
Deploys Web applications, creates application routers, creates and binds service instances, conducts tests.
Scenario steps:
1. Obtains a ready Java EE application WAR file.
2. Deploys an application router with respective routes to the application.
3. Creates an XSUAA service instance and binds it to the router.
4. Deploys the Java EE application to an SAP BTP subaccount.
5. Creates a Destination service instance, and binds it to the application.
6. Creates and manages roles and role collections.
Back to Tasks [page 236]
Installation Prerequisites
● You have downloaded and set up your Eclipse IDE and the Eclipse Tools for Cloud Foundry .
● You have downloaded the Cloud Foundry CLI, see Tools.
Back to Tasks [page 236]
Next Steps
● Develop a Sample Web Application [page 239]
● Create and Bind Service Instances [page 244]
● Deploy the Application [page 246]
● Configure Roles and Trust [page 248]
● Set Up an Application Router [page 249]
● Configure the RFC Destination [page 253]
● Monitoring Your Web Application [page 254] (Optional)
Related Information
Scenario: Multitenancy for JCo Applications (Advanced) [page 254]
1.1.4.3.1.2.1 Develop a Sample Web Application
Create a Web application to call an ABAP function module via RFC.
SAP BTP Connectivity
Connectivity PUBLIC 239](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-239-320.jpg)
![Steps
1. Create a Dynamic Web Project [page 216]
2. Include JCo Dependencies [page 217]
3. Create a Sample Servlet [page 218]
Create a Dynamic Web Project
1. Open the Java EE perspective of the Eclipse IDE.
2. On the Project Explorer view, choose New Dynamic Web Project in the context menu.
3. Enter jco_demo as the project name.
4. In the Target Runtime pane, select Cloud Foundry . If it is not yet in the list of available runtimes, choose
New Runtime and select it from there.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish.
240 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-240-320.jpg)
![Back to Steps [page 216]
Include JCo Dependencies
SAP BTP Connectivity
Connectivity PUBLIC 241](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-241-320.jpg)
![To use JCo functionality seamlessly at compile time in Eclipse, you must include the JCo dependencies into
your web project. Therefore, you must convert it into a maven project.
1. In the Project Explorer view, right-click on the project jco-demo and choose Configure Convert to
Maven Project .
2. In the dialog window, leave the default settings unchanged and choose Finish.
3. Open the pom.xml file and include the following dependency:
<dependencies>
<dependency>
<groupId>com.sap.cloud</groupId>
<artifactId>neo-java-web-api</artifactId>
<version>[3.71.8,4.0.0)</version>
<scope>provided</scope>
</dependency>
</dependencies>
Back to Steps [page 216]
Create a Sample Servlet
1. From the jco_demo project node, choose New Servlet in the context menu.
2. Enter com.sap.demo.jco as the <package> and ConnectivityRFCExampleJava as the <Class
name>. Choose Next.
3. Choose Finish to create the servlet and open it in the Java editor.
4. Replace the entire servlet class to make use of the JCo API. The JCo API is visible by default for cloud
applications. You do not need to add it explicitly to the application class path.
Sample Code
package com.sap.demo.jco;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.sap.conn.jco.AbapException;
import com.sap.conn.jco.JCoDestination;
import com.sap.conn.jco.JCoDestinationManager;
import com.sap.conn.jco.JCoException;
import com.sap.conn.jco.JCoFunction;
import com.sap.conn.jco.JCoParameterList;
import com.sap.conn.jco.JCoRepository;
/**
* Sample application that makes use of the capability to invoke a
function module in an ABAP system
* via RFC
*
242 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-242-320.jpg)
![* Note: The JCo APIs are available under <code>com.sap.conn.jco</code>.
*/
@WebServlet("/ConnectivityRFCExample/*")
public class ConnectivityRFCExample extends HttpServlet {
private static final long serialVersionUID = 1L;
protected void doGet(HttpServletRequest request, HttpServletResponse
response)
throws ServletException, IOException {
PrintWriter responseWriter = response.getWriter();
try {
// access the RFC Destination "JCoDemoSystem"
JCoDestination destination =
JCoDestinationManager.getDestination("JCoDemoSystem");
// make an invocation of STFC_CONNECTION in the backend;
JCoRepository repo = destination.getRepository();
JCoFunction stfcConnection =
repo.getFunction("STFC_CONNECTION");
JCoParameterList imports =
stfcConnection.getImportParameterList();
imports.setValue("REQUTEXT", "SAP BTP Connectivity runs with
JCo");
stfcConnection.execute(destination);
JCoParameterList exports =
stfcConnection.getExportParameterList();
String echotext = exports.getString("ECHOTEXT");
String resptext = exports.getString("RESPTEXT");
response.addHeader("Content-type", "text/html");
responseWriter.println("<html><body>");
responseWriter.println("<h1>Executed STFC_CONNECTION in system
JCoDemoSystem</h1>");
responseWriter.println("<p>Export parameter ECHOTEXT of
STFC_CONNECTION:<br>");
responseWriter.println(echotext);
responseWriter.println("<p>Export parameter RESPTEXT of
STFC_CONNECTION:<br>");
responseWriter.println(resptext);
responseWriter.println("</body></html>");
} catch (AbapException ae) {
// just for completeness: As this function module does not
have an exception
// in its signature, this exception cannot occur. But you
should always
// take care of AbapExceptions
} catch (JCoException e) {
response.addHeader("Content-type", "text/html");
responseWriter.println("<html><body>");
responseWriter
.println("<h1>Exception occurred while executing
STFC_CONNECTION in system JCoDemoSystem</h1>");
responseWriter.println("<pre>");
e.printStackTrace(responseWriter);
responseWriter.println("</pre>");
responseWriter.println("</body></html>");
}
}
}
5. Save the Java editor and make sure that the project compiles without errors.
Back to Steps [page 216]
SAP BTP Connectivity
Connectivity PUBLIC 243](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-243-320.jpg)
![Next Steps
● Create and Bind Service Instances [page 244]
● Deploy the Application [page 246]
● Configure Roles and Trust [page 248]
● Set Up an Application Router [page 249]
● Configure the RFC Destination [page 253]
● Monitoring Your Web Application [page 254] (Optional)
1.1.4.3.1.2.2 Create and Bind Service Instances
You must create and bind several service instances, before you can use your application.
Procedure
1. Logon to the cloud cockpit and choose your subaccount.
2. Choose the space where you want to deploy your demo application.
3. Choose Service Marketplace and find these 2 services:
○ Destination
○ Authorization & Trust Management (XSUAA)
4. Create and bind a service instance for each of these services.
○ Destination service [page 221]
○ Authorization & Trust Management (XSUAA service) [page 222]
244 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-244-320.jpg)
![Destination Service
1. Choose Destination Create Instance .
2. Insert an instance name (for example, destination_jco) and choose Create Instance.
Back to Procedure [page 220]
Authorization & Trust Management (XSUAA Service)
1. Choose Authorization & Trust Management Create Instance
2. Select <Service Plan> application.
3. Enter an <Instance Name> and choose Next.
Note
The instance name must match the one defined in the manifest file.
4. In the next tab Parameters , insert the following as a JSON file:
Sample Code
{
"xsappname" : "jco-demo-p1234",
"tenant-mode": "dedicated",
"scopes": [
{
"name": "$XSAPPNAME.all",
"description": "all"
}
],
"role-templates": [
{
"name": "all",
"description": "all",
"scope-references": [
"$XSAPPNAME.all"
]
}
]
}
5. Go to tab Review and choose Create Instance.
Back to Procedure [page 220]
SAP BTP Connectivity
Connectivity PUBLIC 245](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-245-320.jpg)
![Next Steps
● Deploy the Application [page 246]
● Configure Roles and Trust [page 248]
● Set Up an Application Router [page 249]
● Configure the RFC Destination [page 253]
● Monitoring Your Web Application [page 254] (Optional)
1.1.4.3.1.2.3 Deploy the Application
Deploy your Cloud Foundry application to call an ABAP function module via RFC.
Prerequisites
You have created and bound the required service instances, see Create and Bind Service Instances [page 220].
Procedure
1. To deploy your Web application, you can use the following two alternative procedures:
○ Deploying from the Eclipse IDE
○ Deploying from the CLI, see Developing Java in the Cloud Foundry Environment
2. In the following, we publish it with the CLI.
3. To do this, create a manifest.yml file. The key parameter is USE_JCO: true, which must be set to
include JCo into the buildpack during deployment.
manifest.yml
Sample Code
---
applications:
- name: jco-demo-p1234
buildpacks:
- sap_java_buildpack
env:
USE_JCO: true
# This is necessary only if more than one instance is bound
xsuaa_connectivity_instance_name: "xsuaa_jco"
connectivity_instance_name: "connectivity_jco"
destination_instance_name: "destination_jco"
services:
- xsuaa_jco
- connectivity_jco
246 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-246-320.jpg)
![- destination_jco
Caution
The client libraries (java-security, spring-xsuaa, and container security api for node.js as of version
3.0.6) have been updated. When using these libraries, setting the parameter SAP_JWT_TRUST_ACL has
become obsolete. This update comes with a change regarding scopes:
○ For a business application A calling an application B, it is now mandatory that application B grants
at least one scope to the calling business application A.
○ Business application A must accept these granted scopes or authorities as part of the application
security descriptor.
You can grant scopes using the xs-security.json file.
For more information, see Application Security Descriptor Configuration Syntax, specifically the
sections Referencing the Application and Authorities.
Note
If you have more than one instance of those three services bound to your application, you must specify
which one JCo should use with the respective env parameters:
○ xsuaa_connectivity_instance_name
○ connectivity_instance_name
○ destination_instance_name.
4. In Eclipse, right-click on the project and navigate to Export WAR file .
5. Choose a destination by pressing the Browse... button next to the manifest.yml you created before, for
example as jcodemo.war.
6. Leave the other default settings unchanged and choose Finish to export the WAR file.
7. Perform a CLI login via cf login -a api.cf.eu10.hana.ondemand.com -u
<your_email_address> (password, org and space are prompted after a successful login).
8. Push the application with cf push -f manifest.yml -p jcodemo.war.
9. Now, the application should be deployed successfully.
Next Steps
● Configure Roles and Trust [page 248]
● Set Up an Application Router [page 249]
● Configure the RFC Destination [page 253]
● Monitoring Your Web Application [page 254] (Optional)
SAP BTP Connectivity
Connectivity PUBLIC 247](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-247-320.jpg)
![1.1.4.3.1.2.4 Configure Roles and Trust
Configure a role that enables your user to access your Web application.
To add and assign roles, navigate to the subaccount view of the cloud cockpit and choose Security Role
Collections .
1. Create a new role collection with the name all.
2. From the subaccount menu, choose Trust Configuration.
3. If you don't have a trust configuration, follow the steps in Manually Establish Trust and Federation Between
UAA and Identity Authentication.
4. Click on the IdP name of your choice.
5. Type in your e-mail address and choose Show Assignments.
6. If your user has not yet been added to the SAP ID service, you see following popup. In this case, add your
user now.
7. You should now be able to click Assign Role Collection. Choose role collection all and assign it.
Next Steps
● Set Up an Application Router [page 249]
● Configure the RFC Destination [page 253]
● Monitoring Your Web Application [page 254] (Optional)
Related Information
Working with Role Collections
248 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-248-320.jpg)
![1.1.4.3.1.2.5 Set Up an Application Router
For authentication purposes, configure and deploy an application router for your test application.
Note
AppRouter is only required if you want to use multitenancy or perform user-specific service calls. In all
other cases, JCo uses cloud-security-xsuaa-integration with ClientCredentialFlow.
1. To set up an application router, follow the steps in Application Router or use the demo file approuter.zip
(download).
2. For deployment, you need a manifest file, similar to this one:
Sample Code
---
applications:
- name: approuter-jco-demo-p1234
path: ./
buildpacks:
- nodejs_buildpack
memory: 120M
routes:
- route: approuter-jco-demo-p1234.cfapps.eu10.hana.ondemand.com
env:
NODE_TLS_REJECT_UNAUTHORIZED: 0
destinations: >
[
{"name":"dest-to-example", "url" :"https://jco-demo-
p1234.cfapps.eu10.hana.ondemand.com/ConnectivityRFCExample",
"forwardAuthToken": true }
]
services:
- xsuaa_jco
Note
○ The routes and destination URLs need to fit your test application.
○ In this example, we already bound our XSUAA instance to the application router. Alternatively, you
could also do this via the cloud cockpit.
3. Push the approuter with cf push -f manifest.yml -p approuter.zip.
4. To navigate to the approuter application in the cloud cockpit, choose <your_space> Applications
<your application> Overview .
SAP BTP Connectivity
Connectivity PUBLIC 249](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-249-320.jpg)
![</dependency>
Note
Make sure you don't include this dependency with scope compile transitively with any other jar, for
example, with
<dependency>
<groupId>com.sap.cloud.security</groupId>
<artifactId>java-security</artifactId>
</dependency>
In this case, you must exclude java-api from this dependency and add it again as described above, with
scope provided.
Adjust your code from the step Develop a Sample Web Application [page 239] in the following way:
Sample Code
package com.sap.demo.jco;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.sap.cloud.security.token.SecurityContext;
import com.sap.cloud.security.token.Token;
import com.sap.conn.jco.AbapException;
import com.sap.conn.jco.JCoDestination;
import com.sap.conn.jco.JCoDestinationManager;
import com.sap.conn.jco.JCoException;
import com.sap.conn.jco.JCoFunction;
import com.sap.conn.jco.JCoParameterList;
import com.sap.conn.jco.JCoRepository;
/**
*
* Sample application that uses the connectivity service. In particular, it is
* making use of the capability to invoke a function module in an ABAP system
* via RFC
*
* Note: The JCo APIs are available under <code>com.sap.conn.jco</code>.
*/
@WebServlet("/ConnectivityRFCExample/*")
public class ConnectivityRFCExample extends HttpServlet {
private static final long serialVersionUID = 1L;
protected void doGet(HttpServletRequest request, HttpServletResponse
response)
throws ServletException, IOException {
PrintWriter responseWriter = response.getWriter();
// access the token from the thread which is executing the servlet
Token token = SecurityContext.getToken();
Thread runThread = new Thread(() -> {
// set the information in the newly created thread
SecurityContext.setToken(token);
try {
// access the RFC Destination "JCoDemoSystem"
JCoDestination destination =
JCoDestinationManager.getDestination("JCoDemoSystem_Normal");
// make an invocation of STFC_CONNECTION in the backend
SAP BTP Connectivity
Connectivity PUBLIC 251](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-251-320.jpg)
![Next Steps
● Configure the RFC Destination [page 253]
● Monitoring Your Web Application [page 254] (Optional)
1.1.4.3.1.2.6 Configure the RFC Destination
Configure an RFC destination on SAP BTP that you can use in your Web application to call the cloud ABAP
system.
To configure the destination, you must use a WebSocket application server host name
(<id>.abap.eu10.hana.ondemand.com) and a WebSocket port (443).
1. Create a .properties file with the following settings:
Name=JCoDemoSystem
Type=RFC
jco.client.wshost= <id>.abap.eu10.hana.ondemand.com
jco.client.wsport=443
jco.client.alias_user=<DEMOUSER>
jco.client.passwd=<Password>
jco.client.client=100
jco.client.lang=EN
jco.destination.pool_capacity=5
jco.destination.proxy_type=Internet
2. Go to your subaccount in the cloud cockpit.
1. From the subaccount menu, choose Connectivity Destinations Import Destination and upload
this file.
2. Alternatively, you can create a destination for the service instance destination_jco to make it
visible only for this instance. To do this, go to <your space> Services Service Instances <your
destination_instance> and choose Destinations.
3. Specify a trust/key store or security information, see WebSocket Connection [page 118].
Next Steps
● Monitoring Your Web Application [page 254] (Optional)
Related Information
Target System Configuration [page 115]
SAP BTP Connectivity
Connectivity PUBLIC 253](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-253-320.jpg)
![1.1.4.3.1.2.7 Monitoring Your Web Application
Monitor the state and logs of your Web application deployed on SAP BTP, using the Application Logging
service.
For this purpose, create an instance of the Application Logging service (as you did for the Destination service)
and bind it to your application, see Create and Bind Service Instances [page 220].
To activate JCo logging, set the following property in the env section of your manifest file:
SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: INFO}'
Now you can see and open the logs in the cloud cockpit or in the Kibana Dashboard in the tab Logs, if you are
within your application.
For detailed information, you can activate the internal JCo logs:
SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: DEBUG, com.sap.conn.jco:
DEBUG}'
Including other relevant components for logging:
SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: DEBUG, com.sap.conn.jco:
DEBUG, com.sap.xs.security: DEBUG, com.sap.cloud.security: DEBUG,
com.sap.xs.env: DEBUG}'
1.1.4.3.1.3 Scenario: Multitenancy for JCo Applications
(Advanced)
Learn about the required steps to make your Cloud Foundry JCo application tenant-aware.
Using this procedure, you can enable the sample JCo application created in Scenario: Invoke ABAP Function
Modules in On-Premise ABAP Systems [page 212] or Scenario: Invoke ABAP Function Modules in Cloud ABAP
Systems [page 236], for multitenancy.
Steps
1. Prerequisites [page 255]
2. Adjust the Application Router [page 255]
3. Adjust the XSUAA Service Instance and Roles [page 256]
4. Make the Application Subscribable [page 257]
254 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-254-320.jpg)
![5. Create the SAAS Provisioning Service [page 262]
6. Subscribe to the Application [page 263]
7. Create a New Route [page 265]
Prerequisites
● Your runtime environment uses SAP Java Buildpack version 1.9.0 or higher.
● You have successfully completed one of these precedures:
Scenario: Invoke ABAP Function Modules in On-Premise ABAP Systems [page 212]
Scenario: Invoke ABAP Function Modules in Cloud ABAP Systems [page 236]
● You have created a second subaccount (in the same global account), that is used to subscribe to your
application.
Back to Steps [page 254]
Adjust the Application Router
The application router needs to be tenant-aware with a TENANT_HOST_PATTERN to recognize different tenants
from the URL, see Multitenancy. TENANT_HOST_PATTERN should have the following format:
"^(.*).<application domain>". The application router extracts the token captured by "(.*)" to use it as
the subscriber tenant. The manifest file might look like this:
Sample Code
manifest.yml
---
applications:
- name: approuter-jco-demo-p42424242
path: ./
buildpacks:
- nodejs_buildpack
memory: 120M
routes:
- route: approuter-jco-demo-p42424242.cfapps.eu10.hana.ondemand.com
env:
TENANT_HOST_PATTERN: "^(.*).approuter-jco-demo-
p42424242.cfapps.eu10.hana.ondemand.com"
NODE_TLS_REJECT_UNAUTHORIZED: 0
destinations: >
[
{"name":"dest-to-example", "url" :"https://jco-demo-
p42424242.cfapps.eu10.hana.ondemand.com/ConnectivityRFCExample",
"forwardAuthToken": true }
]
services:
- xsuaa_jco
SAP BTP Connectivity
Connectivity PUBLIC 255](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-255-320.jpg)
![Back to Steps [page 254]
Adjust the XSUAA Service Instance and Roles
To call the XSUAA in a tenant-aware way, you must adjust the configuration JSON file. The tenant mode must
now have the value "shared". Also, you must allow calling the previously defined REST APIs (callbacks).
Sample Code
{
"xsappname" : "jco-demo-p42424242",
"tenant-mode": "shared",
"scopes": [
{
"name":"$XSAPPNAME.Callback",
"description":"With this scope set, the callbacks for tenant
onboarding, offboarding and getDependencies can be called.",
"grant-as-authority-to-apps":[
"$XSAPPNAME(application,sap-provisioning,tenant-onboarding)"
]
},
{
"name": "$XSAPPNAME.access",
"description": "app access"
},
{
"name": "uaa.user",
"description": "uaa.user"
}
],
"role-templates": [
{
"name":"MultitenancyCallbackRoleTemplate",
"description":"Call callback-services of applications",
"scope-references":[
"$XSAPPNAME.Callback"
]
},
{
"name": "UAAaccess",
"description": "UAA user access",
"scope-references": [
"uaa.user",
"$XSAPPNAME.access"
]
}
]
}
Add Roles
1. In the cloud cockpit, navigate to the subaccount view and go the tab Role Collections under Security (see
step Configure Roles and Trust [page 225] from the previous procedure).
2. Click on the role collection name.
3. Choose Add Role.
256 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-256-320.jpg)
![4. In the popup window, select the demo application as <Application Identifier>.
5. For <Role Template> and <Role>, use MultitenancyCallbackRoleTemplate and choose Save.
6. Choose Add Role again.
7. Select the demo application as <Application Identifier>.
8. For Role Template and Role use UAAaccess and choose Save.
Back to Steps [page 254]
Make the Application Subscribable
Firstly, in order to make the application subscribable, it must provide at least the following REST APIs:
● GET dependent services of an application [page 257]
● PUT tenant subscription to an application [page 260]
In our sample application, we implement new servlets for each of these APIs.
The following servlets need additional maven dependencies:
Sample Code
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>com.unboundid.components</groupId>
<artifactId>json</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>javax.ws.rs</groupId>
<artifactId>javax.ws.rs-api</artifactId>
<version>2.1.1</version>
</dependency>
GET Dependencies
The current JCo dependencies are the Connectivity and Destination service. Thus, the GET API must return
information about these two services:
Sample Code
import java.io.IOException;
import java.util.Arrays;
import java.util.List;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
SAP BTP Connectivity
Connectivity PUBLIC 257](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-257-320.jpg)
![public static JSONObject getServiceCredentials(String serviceName, String
serviceInstanceName) throws JSONException
{
JSONArray jsonarr=new
JSONObject(VCAP_SERVICES).getJSONArray(serviceName);
for (int i=0; i<jsonarr.length(); i++)
{
JSONObject serviceInstanceObject=jsonarr.getJSONObject(i);
String
instanceName=serviceInstanceObject.getString(VCAP_SERVICES_NAME);
if (instanceName.equals(serviceInstanceName))
{
return
serviceInstanceObject.getJSONObject(VCAP_SERVICES_CREDENTIALS);
}
}
throw new RuntimeException(MessageFormat.format("Service instance {0} of
service {1} not bound to application", serviceInstanceName, serviceName));
}
/**
* Returns service credentials attribute for a given service from
VCAP_SERVICES
*
* @see <a href= "https://docs.run.pivotal.io/devguide/deploy-apps/
environment-variable.html#VCAP-SERVICES">VCAP_SERVICES</a>
*/
public static String getServiceCredentialsAttribute(String serviceName,
String attributeName) throws JSONException
{
return getServiceCredentials(serviceName).getString(attributeName);
}
/**
* Returns the name of the xsuaa service for connectivity service.
*/
public static String getXsuaaConnectivityInstanceName()
{
String
xsuaaConnectivityInstanceName=System.getenv(PROP_XSUAA_CONNECTIVITY_INSTANCE_NAME
);
return xsuaaConnectivityInstanceName!=null?
xsuaaConnectivityInstanceName:DEFAULT_XSUAA_CONNECTIVITY_INSTANCE_NAME;
}
}
Back to Make the Application Subscribable [page 257]
PUT Tenant Subscription
This API is called whenever a tenant is subscribing. In our example, we just read the received JSON, and return
the tenant-aware URL of the application router which points to our application. Also, if a tenant wants to
unsubscribe, DELETE does currently nothing.
Sample Code
SubscribeServlet
import java.io.IOException;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
260 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-260-320.jpg)
![import com.google.gson.Gson;
@WebServlet("/callback/v1.0/tenants/*")
public class SubscribeServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
protected void doPut(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
PayloadDataDto payload = new Gson().fromJson(request.getReader(),
PayloadDataDto.class);
response.getWriter().println("https://" +
payload.getSubscribedSubdomain() + ".approuter-jco-
demo.cfapps.eu10.hana.ondemand.com");
}
@Override
protected void doDelete(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
super.doDelete(req, resp);
}
}
Here is the helper class:
PayloadDataDto.java
import java.util.Map;
public class PayloadDataDto {
private String subscriptionAppName;
private String subscriptionAppId;
private String subscribedTenantId;
private String subscribedSubdomain;
private String subscriptionAppPlan;
private long subscriptionAppAmount;
private String[] dependantServiceInstanceAppIds = null;
private Map<String, String> additionalInformation;
public PayloadDataDto() {}
public PayloadDataDto(String subscriptionAppName, String subscriptionAppId,
String subscribedTenantId, String subscribedSubdomain, String
subscriptionAppPlan,
Map<String, String> additionalInformation) {
this.subscriptionAppName = subscriptionAppName;
this.subscriptionAppId = subscriptionAppId;
this.subscribedTenantId = subscribedTenantId;
this.subscribedSubdomain = subscribedSubdomain;
this.subscriptionAppPlan = subscriptionAppPlan;
this.additionalInformation = additionalInformation;
}
public String getSubscriptionAppName() {
return subscriptionAppName;
}
public void setSubscriptionAppName(String subscriptionAppName) {
this.subscriptionAppName = subscriptionAppName;
}
public String getSubscriptionAppId() {
return subscriptionAppId;
}
public void setSubscriptionAppId(String subscriptionAppId) {
this.subscriptionAppId = subscriptionAppId;
}
public String getSubscribedTenantId() {
return subscribedTenantId;
}
SAP BTP Connectivity
Connectivity PUBLIC 261](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-261-320.jpg)
![public void setSubscribedTenantId(String subscribedTenantId) {
this.subscribedTenantId = subscribedTenantId;
}
public String getSubscribedSubdomain() {
return subscribedSubdomain;
}
public void setSubscribedSubdomain(String subscribedSubdomain) {
this.subscribedSubdomain = subscribedSubdomain;
}
public String getSubscriptionAppPlan() {
return subscriptionAppPlan;
}
public void setSubscriptionAppPlan(String subscriptionAppPlan) {
this.subscriptionAppPlan = subscriptionAppPlan;
}
public Map<String, String> getAdditionalInformation() {
return additionalInformation;
}
public void setAdditionalInformation(Map<String, String>
additionalInformation) {
this.additionalInformation = additionalInformation;
}
public long getSubscriptionAppAmount() {
return subscriptionAppAmount;
}
public void setSubscriptionAppAmount(long subscriptionAppAmount) {
this.subscriptionAppAmount = subscriptionAppAmount;
}
public String[] getDependantServiceInstanceAppIds() {
return dependantServiceInstanceAppIds;
}
public void setDependantServiceInstanceAppIds(
String[] dependantServiceInstanceAppIds) {
this.dependantServiceInstanceAppIds = dependantServiceInstanceAppIds;
}
public String toString() {
return String.format("Payload data: subscriptionAppName=%s,
subscriptionAppId=%s, subscribedTenantId=%s,"
+ "subscribedSubdomain=%s subscriptionAppPlan=%s
subscriptionAppAmount=%s dependantServiceInstanceAppIds=%s",
this.subscriptionAppName, this.subscriptionAppId,
this.subscribedTenantId, this.subscribedSubdomain,
this.subscriptionAppPlan, this.getSubscriptionAppAmount(),
dependantServiceInstanceAppIds);
}
}
Back to Make the Application Subscribable [page 257]
Back to Steps [page 254]
Create the SAAS Provisioning Service
For the subscription of other tenants, your application must have a bound SAAS provisioning service instance.
You can do this using the cockpit:
1. Go to the Service Marketplace in the cloud cockpit:
262 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-262-320.jpg)
![2. Choose Saas Provisioning Instances New Instance .
3. Select application as <Service Plan> and choose Next.
4. In the step Specify Parameters (Optional), insert the following as a JSON file:
Sample Code
{
"xsappname" : "jco-demo-p42424242",
"appName" : "JCo-Demo",
"appUrls": {
"getDependencies": "https://jco-demo-
p42424242.cfapps.eu10.hana.ondemand.com/callback/v1.0/dependencies",
"onSubscription" : "https://jco-demo-
p42424242.cfapps.eu10.hana.ondemand.com/callback/v1.0/tenants/{tenantId}"
}
}
5. Choose Next, and select the sample application jco-demo-p42424242 in the drop-down menu to assign
the SAAS service to it.
6. Choose Next, insert an instance name, for example, saas_jco, and confirm the creation by pressing
Finish.
Back to Steps [page 254]
Subscribe to the Application
1. To subscribe the new application from a different subaccount, go to Subscriptions in the cockpit:
SAP BTP Connectivity
Connectivity PUBLIC 263](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-263-320.jpg)
![Back to Steps [page 254]
Create a New Route
1. To call the application with a new tenant, you must create a new route (URL). In the cockpit, choose
Routes New Route :
2. For <Domain>, select the landscape your application is deployed in (e.g.
cfapps.eu10.hana.ondemand.com).
3. For <Host Name>, choose the tenant-specific link. In our example it would be <tenant-subdomain-
name>.approuter-jco-demo-p42424242.
4. Choose Save.
5. Choose Map Route of the newly created route where the field <Mapped Applications> is empty (value
none):
6. Select the approuter application and choose Save.
7. Congratulations, you are done, now you are able to call the sample application with this newly created
route from the other subaccount!
Back to Steps [page 254]
SAP BTP Connectivity
Connectivity PUBLIC 265](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-265-320.jpg)
![1.1.5 Security
Find an overview of recommended security measures for SAP BTP Connectivity.
Topic More Information
Enable single sign-on by forwarding the identity of cloud
users to a remote system or service.
Principal Propagation [page 121]
Set up and run the Cloud Connector according to the highest
security standards.
Security Guidelines [page 563]
1.1.6 Monitoring and Troubleshooting
Find information on monitoring and troubleshooting for SAP BTP Connectivity.
Getting Support
If you encounter an issue with this service, we recommend to follow the procedure below:
Check Platform Status
Check the availability of the platform at SAP BTP Status Page .
For more information about selected platform incidents, see Root Cause Analyses.
Check Guided Answers
In the SAP Support Portal, check the Guided Answers section for SAP BTP. You can find solutions for
general SAP BTP issues as well as for specific services there.
Contact SAP Support
You can report an incident or error through the SAP Support Portal .
To find the relevant component for your for SAP BTP Connectivity incident, see Connectivity Support [page
581] (section SAP Support Information).
When submitting the incident, we recommend including the following information:
● Region information (for example: Canary, EU10, US10)
● Subaccount technical name
● The URL of the page where the incident or error occurs
266 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-266-320.jpg)
![● The steps or clicks used to replicate the error
● Screenshots, videos, or the code entered
More Information
Topic More Information
Monitor the Cloud Connector from the SAP BTP cockpit and
from the Cloud Connector administration UI.
Monitoring [page 516]
Troubleshoot connection problems and view different types
of logs and traces in the Cloud Connector.
Troubleshooting [page 548]
Detailed support information for SAP Connectivity service
and the Cloud Connector.
Connectivity Support [page 581]
1.2 Cloud Connector
Learn more about the Cloud Connector: features, scenarios and setup.
Note
This documentation refers to SAP BTP, Cloud Foundry environment. If you are looking for information
about the Neo environment, see Connectivity for the Neo Environment.
Content
In this Topic
Hover over the elements for a description. Click an element for more information.
SAP BTP Connectivity
Connectivity PUBLIC 267](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-267-320.jpg)
![● Context [page 268]
● Basic Scenarios [page 269]
● Basic Tasks [page 272]
● Advantages [page 269]
● Extended Scenarios [page 271]
● What's New? [page 272]
In this Guide
Hover over the elements for a description. Click an element for more information.
● Configuration [page 311]
● Installation [page 273]
● Operations [page 502]
● Frequently Asked Questions [page 571]
● Upgrade [page 567]
● Security [page 556]
● Update the Java VM [page 569]
● Uninstallation [page 570]
● Connectivity Support [page 581]
● Security Guidelines [page 563]
Context
The Cloud Connector:
● Serves as a link between SAP BTP applications and on-premise systems.
○ Combines an easy setup with a clear configuration of the systems that are exposed to the SAP BTP.
○ Lets you use existing on-premise assets without exposing the entire internal landscape.
268 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-268-320.jpg)
![● Runs as on-premise agent in a secured network.
○ Acts as a reverse invoke proxy between the on-premise network and SAP BTP.
● Provides fine-grained control over:
○ On-premise systems and resources that can be accessed by cloud applications.
○ Cloud applications using the Cloud Connector.
● Lets you use the features that are required for business-critical enterprise scenarios.
○ Recovers broken connections automatically.
○ Provides audit logging of inbound traffic and configuration changes.
○ Can be run in a high-availability setup.
Caution
The Cloud Connector must not be used to connect to products other than SAP BTP or S/4HANA Cloud.
Back to Content [page 267]
Advantages
Compared to the approach of opening ports in the firewall and using reverse proxies in the DMZ to establish
access to on-premise systems, the Cloud Connector offers the following benefits:
● You don't need to configure the on-premise firewall to allow external access from SAP BTP to internal
systems. For allowed outbound connections, no modifications are required.
● The Cloud Connector supports HTTP as well as additional protocols. For example, the RFC protocol
supports native access to ABAP systems by invoking function modules.
● You can use the Cloud Connector to connect on-premise databases or BI tools to SAP HANA databases in
the cloud.
● The Cloud Connector lets you propagate the identity of cloud users to on-premise systems in a secure way.
● Easy installation and configuration, which means that the Cloud Connector comes with a low TCO and is
tailored to fit your cloud scenarios.
● SAP provides standard support for the Cloud Connector.
Back to Content [page 267]
Basic Scenarios
Connecting Cloud Applications to On-Premise Systems [page 270]
Connecting On-Premise Database Tools to SAP HANA Databases [page 270]
SAP BTP Connectivity
Connectivity PUBLIC 269](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-269-320.jpg)
![ Note
This section refers to the Cloud Connector installation in a standard on-premise network. Find setup
options for other system environments in Extended Scenarios [page 271].
Connecting Cloud Applications to On-Premise Systems
1. Install the Cloud Connector: Installation [page 273]
2. Set up the connection between Cloud Connector, back-end system and your SAP BTP subaccount : Initial
Configuration [page 312], Managing Subaccounts [page 328]
3. Allow your cloud application to access a back-end system on the intranet: Configure Access Control [page
369]
4. Connect your cloud application to an on-premise system:
Consuming the Connectivity Service [page 164] (Cloud Foundry environment)
Back to Basic Scenarios [page 269]
Back to Content [page 267]
Connecting On-Premise Database Tools to SAP HANA Databases
270 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-270-320.jpg)
![1. Install and configure the Cloud Connector: Installation [page 273], Initial Configuration [page 312],
Managing Subaccounts [page 328]
2. Access HANA databases on SAP BTP: Configure a Service Channel for an SAP HANA Database [page 483]
3. Connect on-premise database or BI tools to a HANA database on SAP BTP: Connect DB Tools to SAP
HANA via Service Channels [page 486]
Note
You can use service channels also for other purposes:
● Connect to a virtual machine on SAP BTP.
● Configure an RFC connection from your on-premise system to S/4HANA Cloud.
See Using Service Channels [page 482].
Back to Basic Scenarios [page 269]
Back to Content [page 267]
Extended Scenarios
Besides the standard setup: SAP BTP - Cloud Connector - on-premise system/network, you can also use the
Cloud Connector to connect SAP BTP applications to other cloud-based environments, as long as they are
operated in a way that is comparable to an on-premise network from a functional perspective. This is
particularly true for infrastructure (IaaS) hosting solutions.
SAP BTP Connectivity
Connectivity PUBLIC 271](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-271-320.jpg)
![Here's an overview of all environments in which you can or cannot set up the Cloud Connector:
Cloud Connector Environment Examples
Can be set up in:
Note
Within extended scenarios that al
low a Cloud Connector setup, spe
cial procedures may apply for con
figuration. If so, they are mentioned
in the corresponding configuration
steps.
Customer on-premise network (see Ba
sic Scenarios [page 269])
SAP ERP, SAP S/4HANA
SAP Hosting SAP HANA Enterprise Cloud (HEC)
Third-party IaaS providers (hosting) Amazon Web Services (AWS), Microsoft
Azure, Google Cloud Platform (GCP)
Cannot be set up in: SAP SaaS solutions SAP SuccessFactors, SAP Concur, SAP
Ariba
SAP cloud-based enterprise solutions SAP S/4HANA Cloud, SAP C/4HANA
Third-party PaaS providers AWS, Azure, GCP
Third-party SaaS providers
Back to Content [page 267]
Basic Tasks
The following steps are required to connect the Cloud Connector to your SAP BTP subaccount:
● Install the Cloud Connector: Installation [page 273]
● Perform the initial configuration for the Cloud Connector: Initial Configuration [page 312]
● Register the Cloud Connector for your SAP BTP subaccount: Managing Subaccounts [page 328]
Back to Content [page 267]
What's New?
Follow the SAP BTP Release Notes to stay informed about Cloud Connector and Connectivity updates.
Back to Content [page 267]
Related Information
272 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-272-320.jpg)
![Installation [page 273]
Configuration [page 311]
Operations [page 502]
Security [page 556]
Upgrade [page 567]
Update the Java VM [page 569]
Uninstallation [page 570]
Frequently Asked Questions [page 571]
1.2.1 Installation
Choose a procedure to install the Cloud Connector on your operating system.
Portable Version vs. Installer Version
On Microsoft Windows and Linux, two installation modes are available: a portable version and an
installer version. On Mac OS X, only the portable version is available.
● Portable version: can be installed easily, by extracting a compressed archive into an empty directory. It
does not require administrator or root privileges for the installation, and you can run multiple instances on
the same host.
Restrictions:
○ You cannot run it in the background as a Windows Service or Linux daemon (with automatic start
capabilities at boot time).
○ The portable version does not support an automatic upgrade procedure. To update a portable
installation, you must delete the current one, extract the new version, and then re-do the configuration.
○ Portable versions are meant for non-productive scenarios only.
○ The environment variable JAVA_HOME is relevant when starting the instance, and therefore must be set
properly.
● Installer version: requires administrator or root permissions for the installation and can be set up to run
as a Windows service or Linux daemon in the background. You can upgrade it easily, retaining all the
configuration and customizing.
Note
We strongly recommend that you use this variant for a productive setup.
SAP BTP Connectivity
Connectivity PUBLIC 273](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-273-320.jpg)
![Prerequisites
● There are some general prerequisites you must fulfill to successfully install the Cloud Connector, see
Prerequisites [page 274].
● For OS-specific requirements and procedures, see section Tasks below.
Tasks
● Installation on Microsoft Windows OS [page 292]
● Installation on Linux OS [page 295]
● Installation on Mac OS X [page 298]
Related Information
Sizing Recommendations [page 286]
Recommendations for Secure Setup [page 299]
[Deprecated] Replace the Default SSL Certificate [page 306]
Uninstallation [page 570]
1.2.1.1 Prerequisites
Prerequisites for successful installation of the Cloud Connector.
Content
Section Description
Connectivity Restrictions [page 275] General information about SAP BTP and connectivity restric
tions.
Hardware [page 275] Hardware prerequisites for a physical or virtual machine.
Software [page 275] Required software download and installation.
JDKs [page 276] Java Development Kit (JDK) versions that you can use.
Product Availability Matrix [page 276] Availability of operating systems/versions for specific Cloud
Connector versions.
274 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-274-320.jpg)
![Section Description
Network [page 277] Required Internet connection to SAP BTP hosts per region.
Note
For additional system requirements, see also System Requirements [page 284].
Connectivity Restrictions
For general information about SAP BTP restrictions, see Prerequisites and Restrictions.
For specific information about all Connectivity restrictions, see Connectivity: Restrictions [page 5].
Back to Content [page 274]
Hardware
Hardware prerequisites, physical or virtual machine:
Minimum Recommended
CPU Single core 3 GHz, x86-64 architecture
compatible
Dual core 2 GHz, x86-64 architecture
compatible
Memory (RAM) 2 GB 4 GB
Free disk space 3 GB 20 GB
Back to Content [page 274]
Software
● You have downloaded the Cloud Connector installation archive from SAP Development Tools for Eclipse.
● A JDK 8 must be installed. You can download an up-to-date SAP JVM from SAP Development Tools for
Eclipse as well.
Caution
Do not use Apache Portable Runtime (APR) on the system on which you use the Cloud Connector. If you
cannot avoid this restriction and want to use APR at your own risk, you must manually adopt the
server.xml configuration file in directory <scc_installation_folder>/conf. To do so, follow the
steps in HTTPS port configuration for APR.
SAP BTP Connectivity
Connectivity PUBLIC 275](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-275-320.jpg)
![Back to Content [page 274]
JDKs
JDK Version Cloud Connector Version
SAP JVM 64-bit (recommended) 7 2.x up to 2.12.2
8 2.7.2 and higher
Oracle JDK 64-bit 7 2.x up to 2.12.2
8 2.7.2 and higher
Note
The support for using Cloud Connector with Java runtime version 7 ended on December 31, 2019. Any
Cloud Connector version released after that date may contain Java byte code requiring at least a JVM 8.
We therefore strongly recommend that you perform fresh installations only with Java 8, and update
existing installations running with Java 7, to Java 8.
See SAP Cloud Connector – Java 7 support will phase out and Update the Java VM [page 569].
Back to Content [page 274]
Product Availability Matrix
Operating System Version Architecture Cloud Connector Version
Windows 7, Windows Server 2008 R2 x86_64 2.x
SUSE Linux Enterprise Server 11, Red
hat Enterprise Linux 6
x86_64 2.x
Mac OS X 10.7 (Lion), Mac OS X 10.8
(Mountain Lion)
x86_64 2.x
Windows 8.1, Windows Server 2012,
Windows Server 2012 R2
x86_64 2.5.1 and higher
SUSE Linux Enterprise Server 12, Red
hat Enterprise Linux 7
x86_64 2.5.1 and higher
Mac OS X 10.9 (Mavericks), Mac OS X
10.10 (Yosemite)
x86_64 2.5.1 and higher
Windows 10 x86_64 2.7.2 and higher
Mac OS X 10.11 (El Capitan) x86_64 2.8.1 and higher
276 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-276-320.jpg)
![Operating System Version Architecture Cloud Connector Version
Windows Server 2016 x86_64 2.9.1 and higher
Windows Server 2019, Mac OS X 10.12
(Sierra), Mac OS X 10.13 (High Sierra),
Mac OS X 10.14 (Mojave)
x86_64 2.11.3 and higher
SUSE Linux Enterprise Server 15 x86_64 2.12.0 and higher
Redhat Enterprise Linux 8 x86_64 2.12.2 and higher
SUSE Linux Enterprise Server 12, SUSE
Linux Enterprise Server 15, Redhat En
terprise Linux 7, Redhat Enterprise Li
nux 8
ppc64le 2.13.0 and higher
Back to Content [page 274]
Network
You must have Internet connection at least to the following Connectivity service hosts (depending on the
region), to which you can connect your Cloud Connector. All connections to the hosts are TLS-based and
connect to port 443.
Note
For general information on IP ranges per region, see Regions (Cloud Foundry and ABAP environment) or
Regions and Hosts Available for the Neo Environment. Find detailed information about the region status
and planned network updates on http:/
/sapcp.statuspage.io/ .
Cloud Foundry Environment [page 277]
ABAP Environment [page 280]
Neo Environment [page 280]
Trial [page 282]
Region (Region Host) Hosts IP Address
Cloud Foundry Environment
Note
In the Cloud Foundry environment, IPs are controlled by the respective IaaS provider - Amazon Web Services (AWS),
Microsoft Azure (Azure), or Google Cloud Platform (GCP). IPs may change due to network updates on the provider
side. Any planned changes will be announced at least 4 weeks before they take effect. See also Regions.
SAP BTP Connectivity
Connectivity PUBLIC 277](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-277-320.jpg)
![Region (Region Host) Hosts IP Address
China (Shanghai) - Alibaba
Cloud
(cf.cn40.platform.sa
pcloud.cn)
connectivitynotification.cf.cn40.platform.sapcloud.cn 139.224.7.71
connectivitycertsigning.cf.cn40.platform.sapcloud.cn 139.224.7.71
connectivitytunnel.cf.cn40.platform.sapcloud.cn 139.224.7.71
Back to Network [page 277]
Back to Content [page 274]
Region (Region Host) Hosts IP Address
ABAP Environment
Note
For scenarios using the ABAP environment, include the IPs of the corresponding region below in your firewall rules, in
addition to the IPs listed for the same region above (Cloud Foundry environment), if you use IP-based firewall rules.
Europe (Frankfurt) - AWS *.abap.eu10.hana.ondemand.com 18.185.129.45,
52.29.97.247
US East (VA) - AWS *.abap.us10.hana.ondemand.com 52.4.22.116,
52.1.251.254
Japan (Tokyo) - AWS *.abap.jp10.hana.ondemand.com 18.177.215.21,
3.115.146.41
Back to Network [page 277]
Back to Content [page 274]
Region (Region Host) Hosts IP Address
Neo Environment
Europe (Rot)
(hana.ondemand.com)
connectivitynotification.hana.ondemand.com 155.56.210.83
connectivitycertsigning.hana.ondemand.com 155.56.210.43
connectivitytunnel.hana.ondemand.com 155.56.210.84
Europe (Frankfurt)
(eu2.hana.ondemand.c
om)
connectivitynotification.eu2.hana.ondemand.com 157.133.206.143
connectivitycertsigning.eu2.hana.ondemand.com 157.133.205.174
connectivitytunnel.eu2.hana.ondemand.com 157.133.205.233
Europe (Amsterdam)
(eu3.hana.ondemand.c
om)
connectivitynotification.eu3.hana.ondemand.com 157.133.141.140
connectivitycertsigning.eu3.hana.ondemand.com 157.133.141.132
connectivitytunnel.eu3.hana.ondemand.com 157.133.141.141
United States East (Ashburn) connectivitynotification.us1.hana.ondemand.com Old: 65.221.12.40
New: 157.133.18.120
280 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-280-320.jpg)
![Region (Region Host) Hosts IP Address
(cn1.platform.sapclo
ud.cn)
connectivitytunnel.cn1.platform.sapcloud.cn 157.133.194.82
Japan (Tokyo)
(jp1.hana.ondemand.c
om)
connectivitynotification.jp1.hana.ondemand.com 157.133.150.140
connectivitycertsigning.jp1.hana.ondemand.com 157.133.150.132
connectivitytunnel.jp1.hana.ondemand.com 157.133.150.141
Canada (Toronto)
(ca1.hana.ondemand.c
om)
connectivitynotification.ca1.hana.ondemand.com 157.133.54.140
connectivitycertsigning.ca1.hana.ondemand.com 157.133.54.132
connectivitytunnel.ca1.hana.ondemand.com 157.133.54.141
Russia (Moscow)
(ru1.hana.ondemand.c
om)
connectivitynotification.ru1.hana.ondemand.com 157.133.2.140
connectivitycertsigning.ru1.hana.ondemand.com 157.133.2.132
connectivitytunnel.ru1.hana.ondemand.com 157.133.2.141
Brazil (São Paulo)
(br1.hana.ondemand.c
om)
connectivitynotification.br1.hana.ondemand.com 157.133.246.140
connectivitycertsigning.br1.hana.ondemand.com 157.133.246.132
connectivitytunnel.br1.hana.ondemand.com 157.133.246.141
UAE (Dubai)
(ae1.hana.ondemand.c
om)
connectivitynotification.ae1.hana.ondemand.com 157.133.85.140
connectivitycertsigning.ae1.hana.ondemand.com 157.133.85.132
connectivitytunnel.ae1.hana.ondemand.com 157.133.85.141
KSA (Riyadh)
(sa1.hana.ondemand.c
om)
connectivitynotification.sa1.hana.ondemand.com 157.133.93.140
connectivitycertsigning.sa1.hana.ondemand.com 157.133.93.132
connectivitytunnel.sa1.hana.ondemand.com 157.133.93.141
Back to Network [page 277]
Back to Content [page 274]
Region (Region Host) Hosts IP Address
Trial (Cloud Foundry Environment)
Note
In the Cloud Foundry environment, IPs are controlled by the respective IaaS provider (AWS, Azure, or GCP). IPs may
change due to network updates on the provider side. Any planned changes will be announced several weeks before
they take effect. See also Regions.
Europe (Frankfurt) - AWS
(cf.eu10.hana.ondema
nd.com)
connectivitynotification.cf.eu10.hana.ondemand.com 3.124.222.77,
3.122.209.241,
3.124.208.223
connectivitycertsigning.cf.eu10.hana.ondemand.com 3.124.222.77,
3.122.209.241,
3.124.208.223
282 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-282-320.jpg)
![Region (Region Host) Hosts IP Address
connectivitytunnel.cf.eu10.hana.ondemand.com 3.124.222.77,
3.122.209.241,
3.124.208.223
Europe (Netherleands) -
Azure
(cf.eu20.hana.ondema
nd.com)
connectivitynotification.cf.eu20.hana.ondemand.com 40.119.153.88
connectivitycertsigning.cf.eu20.hana.ondemand.com 40.119.153.88
connectivitytunnel.cf.eu20.hana.ondemand.com 40.119.153.88
United States East (VA) -
AWS
(cf.us10.hana.ondema
nd.com)
connectivitynotification.cf.us10.hana.ondemand.com 52.23.189.23,
52.4.101.240,
52.23.1.211
connectivitycertsigning.cf.us10.hana.ondemand.com 52.23.189.23,
52.4.101.240,
52.23.1.211
connectivitytunnel.cf.us10.hana.ondemand.com 52.23.189.23,
52.4.101.240,
52.23.1.211
US Central (IA) - GCP
(cf.us30.hana.ondema
nd.com)
connectivitynotification.cf.us30.hana.ondemand.com 35.184.169.79
connectivitycertsigning.cf.us30.hana.ondemand.com 35.184.169.79
connectivitytunnel.cf.us30.hana.ondemand.com 35.184.169.79
Trial (Neo Environment)
Trial (Europe only)
(hanatrial.ondemand.
com)
connectivitynotification.hanatrial.ondemand.com 155.56.219.26
connectivitycertsigning.hanatrial.ondemand.com 155.56.219.22
connectivitytunnel.hanatrial.ondemand.com 155.56.219.27
Back to Network [page 277]
Back to Content [page 274]
Note
If you install the Cloud Connector in a network segment that is isolated from the backend systems, make
sure the exposed hosts and ports are still reachable and open them in the firewall that protects them:
● for HTTP, the ports you chose for the HTTP/S server.
● for LDAP, the port of the LDAP server.
● for RFC, it depends on whether you use an SAProuter or not and whether load balancing is used:
○ if you use an SAProuter, it is typically configured as visible in the network of the Cloud Connector
and the corresponding routtab is exposing all the systems that should be used.
○ without SAProuter, you must open the application server hosts and the corresponding gateway
ports (33##, 48##). When using load balancing for the connection, you must also open the
message server host and port.
See also Network Zones [page 285].
SAP BTP Connectivity
Connectivity PUBLIC 283](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-283-320.jpg)
![For more information about the used ABAP server ports, see: Ports of SAP NetWeaver Application Server
ABAP.
Back to Network [page 277]
Back to Content [page 274]
Related Information
Installation on Microsoft Windows OS [page 292]
Installation on Linux OS [page 295]
Installation on Mac OS X [page 298]
Recommendations for Secure Setup [page 299]
Sizing Recommendations [page 286]
1.2.1.1.1 System Requirements
Additional system requirements for installing and running the Cloud Connector.
Supported Browsers
The browsers you can use for the Cloud Connector Administration UI are the same as those currently
supported by SAPUI5. See: Browser and Platform Support.
Minimum Disk Space for Download and Installation
The minimum free disk space required to download and install a new Cloud Connector server is as follows:
● Size of downloaded Cloud Connector installation file (ZIP, TAR, MSI files): 50 MB
● Newly installed Cloud Connector server: 70 MB
● Total: 120 MB as a minimum
Additional Disk Space for Log and Configuration Files
The Cloud Connector writes configuration files, audit log files and trace files at runtime. We recommend that
you reserve between 1 and 20 GB of disk space for those files.
284 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-284-320.jpg)
![Trace and log files are written to <scc_dir>/log/ within the Cloud Connector root directory. The
ljs_trace.log file contains traces in general, communication payload traces are stored in
traffic_trace_*.trc. These files may be used by SAP Support to analyze potential issues. The default
trace level is Information, where the amount of written data is generally only a few KB per day. You can turn
off these traces to save disk space. However, we recommend that you don't turn off this trace completely, but
that you leave it at the default settings, to allow root cause analysis if an issue occurs. If you set the trace level
to All, the amount of data can easily reach the range of several GB per day. Use trace level All only to analyze
a specific issue. Payload trace, however, should normally be turned off, and used only for analysis by SAP
Support.
Note
Regularly back up or delete written trace files to clean up the used disk space.
Audit log files are written to /log/audit/<subaccount-name>/audit-log_<subaccount-
name>_<date>.csv within the Cloud Connector root directory. By default, only security-related events are
written in the audit log. You can change the audit log level using the administration UI, as described in Manage
Audit Logs [page 545].
To be compliant with the regulatory requirements of your organization and the regional laws, the audit log files
must be persisted for a certain period of time for traceability purposes. Therefore, we recommend that you
back up the audit log files regularly from the Cloud Connector file system and keep the backup for the length of
time required.
Related Information
Prerequisites [page 274]
1.2.1.1.2 Network Zones
Choose a network zone for your Cloud Connector installation.
A customer network is usually divided into multiple network zones or subnetworks according to the security
level of the contained components. For example, the DMZ that contains and exposes the external-facing
services of an organization to an untrusted network, usually the Internet, and there are one or more other
network zones which contain the components and services provided in the company’s intranet.
You can generally choose the network zone in which to set up the Cloud Connector:
● Internet access to the SAP BTP region host, either directly or via HTTPS proxy.
● Direct access to the internal systems it provides access to, which means that there is transparent
connectivity between the Cloud Connector and the internal system.
The Cloud Connector can be set up either in the DMZ and operated centrally by the IT department, or set up in
the intranet and operated by the appropriate line of business.
SAP BTP Connectivity
Connectivity PUBLIC 285](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-285-320.jpg)
![ Note
The internal network must allow access to the required ports; the specific configuration depends on the
firewall software used.
The default ports are 80 for HTTP and 443 for HTTPS. For RFC communication, you need to open a
gateway port (default: 33+<instance number> and an arbitrary message server port. For a connection to
a HANA Database (on SAP BTP) via JDBC, you need to open an arbitrary outbound port in your network.
Mail (SMTP) communication is not supported.
1.2.1.2 Sizing Recommendations
When installing a Cloud Connector, the first thing you need to decide is the sizing of the installation.
This section gives some basic guidance what to consider for this decision. The provided information includes
the shadow instance, which should always be added in productive setups. See also Install a Failover Instance
for High Availability [page 508].
Note
The following recommendations are based on current experiences. However, they are only a rule of thumb
since the actual performance strongly depends on the specific environment. The overall performance of a
Cloud Connector is impacted by many factors (number of hosted subaccounts, bandwidth, latency to the
attached regions, network routers in the corporate network, used JVM, and others).
Restrictions
The sizing data refer to a single Cloud Connector installation.
Note
Up until now, you cannot perform horizontal scaling directly. However, you can distribute the load statically
by operating multiple Cloud Connector installations with different location IDs for all involved subaccounts.
In this scenario, you can use multiple destinations with virtually the same configuration, except for the
location ID. See also Managing Subaccounts [page 328], step 4. Alternatively, each of the Cloud Connector
instances can host its own list of subaccounts without any overlap in the respective lists. Thus, you can
handle more load, if a single installation risks to be overloaded.
Related Information
Hardware Setup [page 287]
Configuration Setup [page 290]
286 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-286-320.jpg)
![1.2.1.2.1 Hardware Setup
How to choose the right sizing for your Cloud Connector installation.
Regarding the hardware, we recommend that you use different setups for master and shadow. One dedicated
machine should be used for the master, another one for the shadow. Usually, a shadow instance takes over the
master role only temporarily. During most of its lifetime, in the shadow state, it needs less resources compared
to the master.
If the master instance is available again after a downtime, we recommend that you switch back to the actual
master.
Note
The sizing recommendations refer to the overall load across all subaccounts that are connected via the
Cloud Connector. This means that you need to accumulate the expected load of all subaccounts and
should not only calculate separately per subaccount (taking the one with the highest load as basis).
Related Information
Sizing for the Master Instance [page 287]
Sizing for the Shadow Instance [page 289]
1.2.1.2.1.1 Sizing for the Master Instance
Learn more about the basic criteria for the sizing of your Cloud Connector master instance.
For the master setup, keep in mind the expected load for communication between the SAP BTP and on-
premise systems. The setups listed below differ in a mostly qualitative manner, without hard limits for each of
them.
Note
The mentioned sizes are considered as minimal configuration, larger ones are always ok. In general, the
more applications, application instances, and subaccounts are connected, the more competition will exist
for the limited resources on the machine.
SAP BTP Connectivity
Connectivity PUBLIC 287](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-287-320.jpg)
![Installation Size (S, M, L) CPU (x86_64)
Machine Memory / Heap /
Direct Memory Disk Space
L:
The expected load is large
(more than 10 million re
quests per day, request con
currency and size is in aver
age medium or high) and
multiple subaccounts with
multiple applications are
connected.
In addition, many service
channels are used, and a
large data amount is repli
cated to cloud systems con
currently.
We recommend that you do
the setup in a virtual or phys
ical machine. A virtual ma
chine should be on a host
without overcommitted re
sources.
8 cores 3.0 Ghz 32GB RAM / 8GB / 16GB 40GB
Particularly the heap size is critical. If you size it too low for the load passing the Cloud Connector, at some
point the Java Virtual Machine will execute full GCs (garbage collections) more frequently, blocking the
processing of the Cloud Connector completely for multiple seconds, which massively slows down overall
performance. If you experience such situations regularly, you should increase the heap size in the Cloud
Connector UI (choose Configuration Advanced JVM ). See also Configure the Java VM [page 497].
Note
You should use the same value for both <initial heap size> and <maximum heap size>.
1.2.1.2.1.2 Sizing for the Shadow Instance
Learn more about the basic criteria for the sizing of your Cloud Connector shadow instance (high availability
mode).
The shadow installation is typically not used in standard situations and hence does not need the same sizing,
assuming that the time span in which it takes over the master role is limited.
Note
The shadow only acts as master, for example, during an upgrade or when an abnormal situation occurs on
the master machine, and either the Cloud Connector or the full machine on OS level needs to be restarted.
SAP BTP Connectivity
Connectivity PUBLIC 289](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-289-320.jpg)
![While being in the shadow state, the resource consumption is very low, especially in productive environments,
where typically only few configuration changes are required. Therefore, the machine sizing can usually be
smaller than the one for the master. However, if you want to mitigate the risk of a longer outage of the master
machine, you should increase the sizing of the shadow up to the master size:
Master Shadow
S S installation as virtual machine
M S installation (with double memory) as virtual or physical
machine
M installation as virtual or physical machine for risk mitiga
tion
L M installation as virtual or physical machine
L installation as virtual or physical machine for risk mitiga
tion
1.2.1.2.2 Configuration Setup
Choose the right connection configuration options to improve the performance of the Cloud Connector.
This section provides detailed information how you can adjust the configuration to improve overall
performance. This is typically relevant for an M or L installation (see Hardware Setup [page 287]). For S
installations, the default configuration will probably be sufficient to handle the traffic.
To change the connection parameters, proceed as follows:
● As of Cloud Connector 2.11, you can configure the number of physical connections through the Cloud
Connector UI. See also Configure Tunnel Connections [page 496].
● In versions prior to 2.11, you have to modify the configuration files with an editor and restart the Cloud
Connector to activate the changes.
In general, the Cloud Connector tunnel is multiplexing multiple virtual connections over a single physical
connection. Thus, a single connection can handle a considerable amount of traffic. However, increasing the
maximum number of physical connections allows you to make use of the full available bandwidth and to
minimize latency effects.
If the bandwidth limit of your network is reached, adding additional connections doesn't increase the
througput, but will only consume more resources.
Note
Different network access parameters may impact and limit your configuration options: if the access to an
external network is a 1 MB line with an added latency of 50 ms, you will not be able to achieve the same
data volumes like with a 10 GB line with an added latency of < 1 ms. However, even if the line is good, for
example 10 GB, but with an added latency of 100 ms, the performance might still be bad.
290 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-290-320.jpg)
![Optimal configuration strongly depends on your actual scenarios. A good approach is to try out different
settings, if the current performance does not meet your expectations.
Related Information
On-Demand To On-Premise Connections [page 291]
On-Premise To On-Demand Connections (Service Channels) [page 292]
1.2.1.2.2.1 On-Demand To On-Premise Connections
Configure the physical connections for on-demand to on-premise calls in the Cloud Connector.
Adjusting the number of physical connections for this direction is possible both globally in the Cloud Connector
UI ( Configuration Advanced ), and for individual communication partners on cloud side ( On-Demand
To On-Premise Applications ).
Connections are established for each defined and connected subaccount. The current number of opened
connections is visible in the Cloud Connector UI via <Subaccount> Cloud Connections .
The global default is 1 physical connection per connected subaccount. This value is used across all
subaccounts hosted by the Cloud Connector instance and applies for all communication partners.
In general, the default should be sufficient for applications with low traffic. If you expect medium traffic for most
applications, it may be useful to set the default value to 2.
Note
An exact traffic forecast is difficult to achieve. It requires a deep understanding of the use case and of the
possible future load generated by different applications. For this reason, we recommend that you focus on
subsequent configuration adjustments, using the Cloud Connector monitoring tools to recognize
bottlenecks in time, and adjust Cloud Connector configuration accordingly.
Tunnel Worker Threads
In addition to the number of connections, you can configure the number of <Tunnel Worker Threads>. This
value should be at least equal to the maximum of all individual application tunnel connections in all
subaccounts, to have at least 1 thread available for each connection that can process incoming requests and
outgoing responses.
SAP BTP Connectivity
Connectivity PUBLIC 291](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-291-320.jpg)
![Protocol Processor Worker Threads
The value for <Protocol Processor Worker Threads> is mainly relevant if RFC is used as protocol. Since
its communication model towards the ABAP system is a blocking one, each thread can handle only one call at a
time and cannot be shared. Hence, you should provide 1 thread per 5 concurrent RFC requests.
Note
The longer the RFC execution time in the backend, the more threads you should provide. Threads can be
reused only after the response of a call was returned to SAP BTP.
1.2.1.2.2.2 On-Premise To On-Demand Connections (Service
Channels)
Configure the number of physical connections for a Cloud Connector service channel.
Service channels let you configure the number of physical connections to the communication partner on cloud
side, see Using Service Channels [page 482]. The default is 1. This value is used as well in versions prior to
Cloud Connector 2.11, which did not offer a configuration option for each service channel. You should define the
number of connections depending on the expected number of clients and, with lower priority, depending on the
size of the exchanged messages.
If there is only a single RFC client for an S/4HANA Cloud channel or only a single HANA client for a HANA DB on
SAP BTP side, increasing the number doesn't help, as each virtual connection is assigned to one physical
connection. The following simple rule lets you to define the required number of connections per service
channel:
● Per 10 concurrent clients, use one physical connection.
● If the transferred net data size is larger than 500k per request, make sure to add an additional connection
per 2 of such clients.
Example
For a HANA system in the SAP BTP, data is replicated using 18 concurrent clients in the on-premise network. In
average, about 5 of those clients are regularly sending 600k. For the number of clients, you should use 2
physical connections, for the 5 clients sending larger amounts add an additional 3, which sums up to 5
connections.
1.2.1.3 Installation on Microsoft Windows OS
Installing the Cloud Connector on a Microsoft Windows operating system.
292 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-292-320.jpg)
![Starting the Cloud Connector
After installation, the Cloud Connector is registered as a Windows service that is configured to be started
automatically after a system reboot. You can start and stop the service via shortcuts on the desktop ("Start
Cloud Connector" and "Stop Cloud Connector"), or by using the Windows Services manager and look for the
service SAP Cloud Connector.
Access the Cloud Connector administration UI at https:/
/localhost:<port>, where the default port is 8443 (but
this port might have been modified during the installation).
Next Steps
1. Open a browser and enter: https://<hostname>:8443. <hostname> is the host name of the machine
on which you have installed the Cloud Connector. If you access the Cloud Connector locally from the same
machine, you can simply enter localhost.
2. Continue with the initial configuration of the Cloud Connector, see Initial Configuration [page 312].
Related Information
(Optional) Install SAP JVM
Recommendations for Secure Setup [page 299]
[Deprecated] Replace the Default SSL Certificate [page 306]
1.2.1.4 Installation on Linux OS
Installing the Cloud Connector on a Linux operating system.
Context
You can choose between a simple portable variant of the Cloud Connector and the RPM-based installer.
The installer is the generally recommended version that you can use for both the developer and the
productive scenario. It registers, for example, the Cloud Connector as a daemon service and this way
automatically starts it after machine reboot.
Tip
If you are a developer, you might want to use the portable variant as you can run the Cloud Connector
after a simple "tar -xzof" execution. You also might want to use it if you cannot perform a full installation
SAP BTP Connectivity
Connectivity PUBLIC 295](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-295-320.jpg)
![Starting the Cloud Connector
After installation via RPM manager, the Cloud Connector process is started automatically and registered as a
daemon process, which ensures the automatic restart of the Cloud Connector after a system reboot.
To start, stop, or restart the process explicitly, open a command shell and use the following commands, which
require root permissions:
System V init distributions: service scc_daemon start|stop|restart
systemd distributions: systemctl start|stop|restart scc_daemon
Next Steps
1. Open a browser and enter: https://<hostname>:8443. <hostname> is the host name of the machine
on which you installed the Cloud Connector.
If you access the Cloud Connector locally from the same machine, you can simply enter localhost.
2. Continue with the initial configuration of the Cloud Connector, see Initial Configuration [page 312].
Related Information
Recommendations for Secure Setup [page 299]
[Deprecated] Replace the Default SSL Certificate [page 306]
1.2.1.5 Installation on Mac OS X
Installing the Cloud Connector on a Mac OS X operating system.
Prerequisites
Note
Mac OS X is not supported for productive scenarios. The developer version described below must not be
used as productive version.
● You have either of the following 64-bit operating systems: Mac OS X 10.7 (Lion), Mac OS X 10.8 (Mountain
Lion), Mac OS X 10.9 (Mavericks), Mac OS X 10.10 (Yosemite), or Mac OS X 10.11 (El Capitan), Mac OS X
10.12 (Sierra), Mac OS X 10.13 (High Sierra), or Mac OS X 10.14 (Mojave).
● You have downloaded the tar.gz archive for the developer use case on Mac OS X from SAP Development
Tools for Eclipse.
298 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-298-320.jpg)
![● Java 8 must be installed. If you want to use SAP JVM, you can download it from SAP Development Tools for
Eclipse as well.
● Environment variable <JAVA_HOME> must be set to the Java installation directory so that the bin
subdirectory can be found. Alternatively, you can add the Java installation's bin subdirectory to the
<PATH> variable.
Procedure
1. Extract the tar.gz file to an arbitrary directory on your local file system using the following command:
tar -xzof sapcc-<version>-macosx-x64.tar.gz
2. Go to this directory and start Cloud Connector using the go.sh script.
3. Continue with the Next Steps section.
Note
The Cloud connector is not started as a daemon, and therefore will not automatically start after a
reboot of your system. Also, the Mac OS X version of Cloud Connector does not support the automatic
upgrade procedure.
Next Steps
1. Open a browser and enter: https://<hostname>:8443. <hostname> is the host name of the machine
on which you installed the Cloud Connector.
If you access the Cloud Connector locally from the same machine, you can simply enter localhost.
2. Continue with the initial configuration of the Cloud Connector, see Initial Configuration [page 312].
Related Information
Recommendations for Secure Setup [page 299]
[Deprecated] Replace the Default SSL Certificate [page 306]
1.2.1.6 Recommendations for Secure Setup
For the Connectivity service and the Cloud Connector, you should apply the following guidelines to guarantee
the highest level of security for these components.
SAP BTP Connectivity
Connectivity PUBLIC 299](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-299-320.jpg)
![Security Status
From the Connector menu, choose Security Status to access an overview showing potential security risks and
the recommended actions.
The General Security Status addresses security topics that are subaccount-independent.
● Choose any of the Actions icons in the corresponding line to navigate to the UI area that deals with that
particular topic and view or edit details.
Note
Navigation is not possible for the last item in the list (Service User).
● The service user is specific to the Windows operating system (see Installation on Microsoft Windows OS
[page 292] for details) and is only visible when running the Cloud Connector on Windows. It cannot be
accessed or edited through the UI. If the service user was set up properly, choose Edit and check the
corresponding checkbox.
The Subaccount-Specific Security Status lists security-related information for each and every subaccount.
Note
The security status only serves as a reminder to address security issues and shows if your installation
complies with all recommended security settings.
300 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-300-320.jpg)
![Password Policy
Upon installation, the Cloud Connector provides an initial user name and password for the administration UI,
and forces the user (Administrator) to change the password. You must change the password immediately
after installation.
The connector itself does not check the strength of the password. You should select a strong password that
cannot be guessed easily.
Note
To enforce your company's password policy, we recommend that you configure the Administration UI to
use an LDAP server for authorizing access to the UI.
UI Access
The Cloud Connector administration UI can be accessed remotely via HTTPS. The connector uses a standard
X.509 self-signed certificate as SSL server certificate. You can exchange this certificate with a specific
certificate that is trusted by your company. See [Deprecated] Replace the Default SSL Certificate [page 306].
Note
Since browsers usually do not resolve localhost to the host name whereas the certificate usually is created
under the host name, you might get a certificate warning. In this case, simply skip the warning message.
OS-Level Access
The Cloud Connector is a security-critical component that handles the external access to systems of an
isolated network, comparable to a reverse proxy. We therefore recommend that you restrict the access to the
operating system on which the Cloud Connector is installed to the minimal set of users who would administrate
the Cloud Connector. This minimizes the risk of unauthorized users getting access to credentials, such as
certificates stored in the secure storage of the Cloud Connector.
We also recommend that you use the machine to operate only the Cloud Connector and no other systems.
Administrator Privileges
To log on to the Cloud Connector administration UI, the Administrator user of the connector must not have
an operating system (OS) user for the machine on which the connector is running. This allows the OS
administrator to be distinguished from the Cloud Connector administrator. To make an initial connection
between the connector and a particular SAP BTP subaccount, you need an SAP BTP user with the required
permissions for the related subaccount. We recommend that you separate these roles/duties (that means, you
have separate users for Cloud Connector administrator and SAP BTP).
SAP BTP Connectivity
Connectivity PUBLIC 301](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-301-320.jpg)
![ Note
We recommend that only a small number of users are granted access to the machine as root users.
Hard Drive Encryption
Hard drive encryption for machines with a Cloud Connector installation ensures that the Cloud Connector
configuration data cannot be read by unauthorized users, even if they obtain access to the hard drive.
Supported Protocols
Currently, the protocols HTTP and RFC are supported for connections between the SAP BTP and on-premise
systems when the Cloud Connector and the Connectivity service are used. The whole route from the
application virtual machine in the cloud to the Cloud Connector is always SSL-encrypted.
The route from the connector to the back-end system can be SSL-encrypted or SNC-encrypted. See Configure
Access Control (HTTP) [page 370] and Configure Access Control (RFC) [page 377].
Audit Log on OS Level
We recommend that you turn on the audit log on operating system level to monitor the file operations.
Audit Log on Cloud Connector Level
The Cloud Connector audit log must remain switched on during the time it is used with productive systems.
The default audit level is SECURITY. Set it to ALL if required by your company policy. The administrators who
are responsible for a running Cloud Connector must ensure that the audit log files are properly archived, to
conform to the local regulations. You should switch on audit logging also in the connected back-end systems.
Encryption Ciphers
By default, all available encryption ciphers are supported for HTTPS connections to the administration UI.
However, some of them may not conform to your security standards and therefore should be excluded:
1. From the main menu, choose Configuration and select the tab User Interface, section Cipher Suites. By
default, all available ciphers are marked as selected.
2. Choose the Remove icon to unselect the ciphers that do not meet your security requirements.
302 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-302-320.jpg)
![ Note
We recommend that you revert the selection to the default (all ciphers selected) whenever you plan to
switch to another JVM. As the set of supported ciphers may differ, the selected ciphers may not be
supported by the new JVM. In that case the Cloud Connector does not start anymore. You need to fix
the issue manually by adapting the file default-server.xml (cp. attribute ciphers, see section
Accessing the Cloud Connector Administrator UI above). After switching the JVM, you can adjust the list
of eligible ciphers.
3. Choose Save.
Related Information
Connectivity via Reverse Proxy [page 579]
Security [page 556]
1.2.1.7 Recommended: Exchange UI Certificates in the
Administration UI
By default, the Cloud Connector includes a self-signed UI certificate. It is used to encrypt the communication
between the browser-based user interface and the Cloud Connector itself. For security reasons, however, you
SAP BTP Connectivity
Connectivity PUBLIC 303](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-303-320.jpg)
![ Note
The response should be either an X.509 certificate or a PKCS#7 in PEM format.
6. To import the signing response, choose the Upload icon.
As of Cloud Connector version 2.13, you can also upload an existing PKCS#12 certificate directly (instead
of generating a CSR).
7. Select Browse to locate the file and then choose the Import button.
8. Review the certificate details that are displayed.
9. Restart the Cloud Connector to activate the new certificate.
Shadow Instance
In a High Availability setup, perform the same operation on the shadow instance.
1.2.1.7.1 [Deprecated] Replace the Default SSL Certificate
Note
This procedure only applies for Cloud Connector versions prior to 2.13. You can now use the UI-based
procedure instead, see Recommended: Exchange UI Certificates in the Administration UI [page 303].
306 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-306-320.jpg)
![Overview
By default, the Cloud Connector includes a self-signed UI certificate. It is used to encrypt the communication
between the browser-based user interface and the Cloud Connector itself. For security reasons, however, you
should replace this certificate with your own certificate so that the browser accepts the certificate without
security warnings.
Up to version 2.5.2, for this purpose, you need to know the password of the Cloud Connector's Java keystore.
This password is generated during installation and then kept in an encrypted secure storage area. To obtain the
password, follow the steps described below.
Note
As of version 2.6.0, you can easily replace the default certificate within the Cloud Connector administration
UI . See Recommended: Exchange UI Certificates in the Administration UI [page 303].
Caution
The Cloud Connector's keystore may contain a certificate used in the High Availability setup. This
certificate has the alias "ha". Any changes on it or removal would cause a disruption of communication
between the shadow and the master instance, and therefore to a failed procedure. We recommend that you
replace the keystore on both the master and shadow server before establishing the connection between
the two instances.
Procedure
You can read the password by executing the following command:
● on Microsoft Windows OS:
java -cp <scc_install_dir>pluginscom.sap.scc.rt*.jar -
Djava.library.path=<scc_install_dir>auditor com.sap.scc.jni.SecStoreAccess -
path <scc_install_dir>scc_config -p
● on Linux OS:
java -cp /opt/sap/scc/plugins/com.sap.scc.rt*.jar -
Djava.library.path=/opt/sap/scc/auditor com.sap.scc.jni.SecStoreAccess -
path /opt/sap/scc/scc_config -p
Note
Memorize the keystore password, as you will need it for later operations. See related links.
Make sure you go to directory /opt/sap/scc/config before executing the commands described in the
following procedures.
Note
For a detailed description of the keytool tool, see http:/
/docs.oracle.com/javase/7/docs/technotes/tools/
solaris/keytool.html .
SAP BTP Connectivity
Connectivity PUBLIC 307](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-307-320.jpg)
![Related Information
Recommended: Exchange UI Certificates in the Administration UI [page 303]
[Deprecated] Use a Self-Signed Certificate [page 308]
[Deprecated] Use Certificates Signed by a Trusted Certificate Authority [page 309]
1.2.1.7.2 [Deprecated] Use a Self-Signed Certificate
Generate a self-signed certificate for special purposes like, for example, a demo setup.
Context
Note
As of Cloud Connector 2.10 you can generate self-signed certificates also from the administration UI. See
Configure a CA Certificate for Principal Propagation [page 344] and Initial Configuration (HTTP) [page
319]. In this case, the steps below are not required.
If you want to use a simple, self-signed certificate, follow the procedure below.
Note
The parameter values in the following section are examples.
The server configuration delivered by SAP uses the same password for key store (option -storepass) and
key (option -keypass) under alias tomcat.
Procedure
1. Remove the current default certificate:
keytool -delete -alias tomcat -keystore ks.store -storepass <password>
2. Generate a certificate:
keytool -genkey -v -keyalg RSA -alias tomcat -keypass <password> -keystore
ks.store -storepass <password> -dname "CN=SCC, OU=<YourCompany>,
O=<YourCompany>"
3. Self-sign it - you will be prompted for the keypass password defined in step 2:
keytool -selfcert -v -alias tomcat -storepass <password> -keystore ks.store
308 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-308-320.jpg)
![1.2.1.7.3 [Deprecated] Use Certificates Signed by a
Trusted Certificate Authority
Use a signed certificate by a trusted certificate authority (CA) to increase the security level when running the
Cloud Connector.
Note
This procedure only applies for Cloud Connector versions prior to 2.13. You can now use the UI-based
procedure instead, see Recommended: Exchange UI Certificates in the Administration UI [page 303].
Before starting the procedure, note the following:
● The parameter values of the following steps are only examples.
● We recommend that you use a signed certificate by a trusted CA, because it is more secure than a self-
signed certificate.
● For your convenience, you can set the generated password as environment variable, like in the command
below, and then use $PASS as a password:
export PASS=`<the release-dependent command as given in the parent page>`
● The keytool supports delete and changealias commands. If the Cloud Connector SSL certificate is
changed on a running instance, we recommend that you prepare a new certificate under a temporary alias.
Once everything is ready, you change the alias.
Procedure
Note
If you already have a signed certificate produced by a trusted certificate authority (CA), skip steps 1,2, and
4, and only follow the instructions provided in step 3.
1. Generate your key pair if you start fresh:
keytool -genkey -v -keyalg RSA -alias tomcat -keypass <password> -keystore
ks.store -storepass <password> -dname "CN=SCC, OU=<YourCompany>,
O=<YourCompany>"
Alternatively, you may reuse an existing key store.
2. Create a local certificate signing request (CSR):
keytool -certreq -keyalg RSA -alias tomcat -keypass <password> -keystore
ks.store -storepass <password> -file <csr-file-name>
You now have a file called <csr-file-name> that you can submit to the certificate authority. In return,
you get a certificate.
3. Import the certificate chain that you obtained from your trusted CA:
keytool -import -alias root -keystore ks.store -storepass <password> -
trustcacerts -file <filename_of_the_certificate_chain>
SAP BTP Connectivity
Connectivity PUBLIC 309](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-309-320.jpg)
![Related Information
For more information about configuring SSL, see http:/
/tomcat.apache.org/tomcat-7.0-doc/ssl-
howto.html#SSL_and_Tomcat .
1.2.2 Configuration
Configure the Cloud Connector to make it operational for connections between your SAP BTP applications and
on-premise systems.
Topic Description
Initial Configuration [page 312] After installing the Cloud Connector and starting the Cloud
Connector daemon, you can log on and perform the required
configuration to make your Cloud Connector operational.
Managing Subaccounts [page 328] How to connect SAP BTP subaccounts to your Cloud
Connector.
Authenticating Users against On-Premise Systems [page
339]
Basic authentication and principal propagation (user propa
gation) are the authentication types currently supported by
the Cloud Connector.
Configure Access Control [page 369] Configure access control or copy the complete access con
trol settings from another subaccount on the same Cloud
Connector.
Configuration REST APIs [page 394] Configure a newly installed Cloud Connector (initial configu-
ration, subaccounts, access control) using the configuration
REST API.
Configure an On-Premise User Store [page 480] Configure applications running on SAP BTP to use your cor
porate LDAP server as a user store.
Using Service Channels [page 482] Service channels provide access from an external network to
certain services on SAP BTP, which are not exposed to direct
access from the Internet.
Configure Trust [page 490] Set up an allowlist for trusted cloud applications and a trust
store for on-premise systems in the Cloud Connector.
Connect DB Tools to SAP HANA via Service Channels [page
486]
How to connect database, BI, or replication tools running in
the on-premise network to a HANA database on SAP BTP
using the service channels of the Cloud Connector.
Configure Domain Mappings for Cookies [page 493] Map virtual and internal domains to ensure correct handling
of cookies in client/server communication.
Configure Solution Management Integration [page 494] Activate Solution Management reporting in the Cloud
Connector.
Configure Tunnel Connections [page 496] Adapt connectivity settings that control the throughput by
choosing the appropriate limits (maximal values).
Configure the Java VM [page 497] Adapt the JVM settings that control memory management.
SAP BTP Connectivity
Connectivity PUBLIC 311](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-311-320.jpg)
![Topic Description
Configuration Backup [page 498] Backup and restore your Cloud Connector configuration.
1.2.2.1 Initial Configuration
After installing and starting the Cloud Connector, log on to the administration UI and perform the required
configuration to make your Cloud Connector operational.
Tasks
Prerequisites [page 312]
Log on to the Cloud Connector [page 313]
Change your Password and Choose Installation Type [page 314]
Set up Connection Parameters and HTTPS Proxy [page 315]
Establish Connections to SAP BTP [page 318]
Prerequisites
● You have assigned one of these roles/role collections to the subaccount user that you use for initial Cloud
Connector setup, depending on the SAP BTP environment in which your subaccount is running:
Note
For the Cloud Foundry environment, you must know on which cloud management tools feature set (A
or B) your account is running. For more information on feature sets, see Cloud Management Tools —
Feature Set Overview.
Environment Required Roles/Role Collections More Information
Cloud Foundry [feature set A] The user must be a member of the
global account that the subaccount
belongs to.
Alternatively, you can assign the user
as Security Administrator.
Add Members to Your Global Account
Managing Security Administrators in
Your Subaccount [Feature Set A]
312 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-312-320.jpg)
![Environment Required Roles/Role Collections More Information
Cloud Foundry [feature set B] Assign at least one of these default
role collections (all of them including
the role Cloud Connector
Administrator):
○ Subaccount
Administrator
○ Cloud Connector
Administrator
○ Connectivity and
Destination
Administrator
Alternatively, you can assign a custom
role collection to the user that in
cludes the role Cloud Connector
Administrator.
Default Role Collections [Feature Set
B] [page 13]
Role Collections and Roles in Global
Accounts and Subaccounts [Feature
Set B]
Neo Assign at least one of these default
roles:
○ Cloud Connector Admin
○ Administrator
Alternatively, you can assign a custom
role to the user that includes the per
mission manageSCCTunnels.
Managing Member Authorizations in
the Neo Environment
After establishing the Cloud Connector connection, this user is not needed any more, since it serves only
for initial connection setup. You may revoke the corresponding role assignment then and remove the user
from the Members list.
Note
If the Cloud Connector is installed in an environment that is operated by SAP, SAP provides a user that
you can add as member in your SAP BTP subaccount and assign the required role.
● We strongly recommend that you read and follow the steps described in Recommendations for Secure
Setup [page 299]. For operating the Cloud Connector securely, see also Security Guidelines [page 563].
Back toTasks [page 312]
Log on to the Cloud Connector
To administer the Cloud Connector, you need a Web browser. To check the list of supported browsers, see
Prerequisites and Restrictions → section Browser Support.
1. In a Web browser, enter: https://<hostname>:<port>
SAP BTP Connectivity
Connectivity PUBLIC 313](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-313-320.jpg)
![○ <hostname> refers to the machine on which the Cloud Connector is installed. If installed on your
machine, you can simply enter localhost.
○ <port> is the Cloud Connector port specified during installation (the default port is 8443).
2. On the logon screen, enter Administrator / manage (case sensitive) for <User Name> / <Password>.
Back toTasks [page 312]
Change your Password and Choose Installation Type
1. When you first log in, you must change the password before you continue, regardless of the installation
type you have chosen.
2. Choose between master and shadow installation. Use Master if you are installing a single Cloud Connector
instance or a main instance from a pair of Cloud Connector instances. See Install a Failover Instance for
High Availability [page 508].
3. You can edit the password for the Administrator user from Configuration in the main menu, tab User
Interface, section Authentication:
Note
User name and password cannot be changed at the same time. If you want to change the user name, you
must enter only the current password in a first step. Do not enter values for <New Password> or <Repeat
New Password> when changing the user name. To change the password in second step, enter the old
password, the new one, and the repeated (new) password, but leave the user name unchanged.
314 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-314-320.jpg)
![Back toTasks [page 312]
Set up Connection Parameters and HTTPS Proxy
When logging in for the first time, the following screen is displayed every time you choose an option from the
main menu that requires a configured subaccount:
If your internal landscape is protected by a firewall that blocks any outgoing TCP traffic, you must specify an
HTTPS proxy that the Cloud Connector can use to connect to SAP BTP. Normally, you must use the same
proxy settings as those being used by your standard Web browser. The Cloud Connector needs this proxy for
two operations:
● Download the correct connection configuration corresponding to your subaccount ID in SAP BTP.
● Establish the SSL tunnel connection from the Cloud Connector user to your SAP BTP subaccount.
Note
If you want to skip the initial configuration, you can click the icon in the upper right corner. You might
need this in case of connectivity issues shown in your logs. You can add subaccounts later as described in
Managing Subaccounts [page 328].
The Cloud Connector collects the following required information for your subaccount connection:
1. For <Region>, specify the SAP BTP region that should be used. You can choose it from the drop-down list,
see Regions.
Note
You can also configure a region yourself, if it is not part of the standard list. Either insert the region host
manually, or create a custom region, as described in Configure Custom Regions [page 339].
SAP BTP Connectivity
Connectivity PUBLIC 315](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-315-320.jpg)
![2. For <Subaccount>, <Subaccount User> and <Password>, enter the values you obtained when you
registered your subaccount on SAP BTP.
Note
For a subaccount in the Cloud Foundry environment, you must enter the subaccount ID as
<Subaccount>, rather than its actual (technical) name. For information on getting the subaccount ID,
see Find Your Subaccount ID (Cloud Foundry Environment) [page 338]. As <Subaccount User> you
must provide your Login E-mail instead of a user ID. The user must be a member of the global
account the subaccount belongs to.
You can also add a new subaccount user with the role Cloud Connector Admin in the SAP BTP cockpit
and use the new user and password.
For the Neo environment, see Add Members to Your Neo Subaccount.
For the Cloud Foundry environment, see Add Org Members Using the Cockpit.
Tip
When using SAP Cloud Identity Services - Identity Authentication (IAS) as platform identity provider
with two-factor authentication for your subaccount, you can simply append the required token to the
regular password.
Tip
For a subaccount in the Cloud Foundry environment, the Cloud Connector supports the use of a
custom identity provider (IDP) via single sign-on (SSO) passcode. For more information, see Use a
Custom IDP for Subaccount Configuration [page 324].
3. (Optional) You can define a <Display Name> that lets you easily recognize a specific subaccount in the UI
compared to the technical subaccount name.
4. (Optional) You can define a <Location ID> identifying the location of this Cloud Connector for a specific
subaccount. As of Cloud Connector release 2.9.0, the location ID is used as routing information and
therefore you can connect multiple Cloud Connectors to a single subaccount. If you don't specify any value
for <Location ID>, the default is used, which represents the behavior of previous Cloud Connector
versions. The location ID must be unique per subaccount and should be an identifier that can be used in a
URI. To route requests to a Cloud Connector with a location ID, the location ID must be configured in the
respective destinations.
Note
Location IDs provided in older versions of the Cloud Connector are discarded during upgrade to ensure
compatibility for existing scenarios.
5. Enter a suitable proxy host from your network and the port that is specified for this proxy. If your network
requires an authentication for the proxy, enter a corresponding proxy user and password. You must specify
a proxy server that supports SSL communication (a standard HTTP proxy does not suffice).
Note
These settings strongly depend on your specific network setup. If you need more detailed information,
please contact your local system administrator.
316 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-316-320.jpg)
![Back toTasks [page 312]
Establish Connections to SAP BTP
As soon as the initial setup is complete, the tunnel to the cloud endpoint is open, but no requests are allowed to
pass until you have performed the Access Control setup, see Configure Access Control [page 369].
To manually close (and reopen) the connection to SAP BTP, choose your subaccount from the main menu and
select the Disconnect button (or the Connect button to reconnect to SAP BTP).
● The green icon next to Region Host indicates that it is valid and can be reached.
● If an HTTPS Proxy is configured, its availability is shown the same way. In the screenshot, the grey diamond
icon next to HTTPS Proxy indicates that connectivity is possible without proxy configuration.
In case of a timeout or a connectivity issue, these icons are yellow (warning) or red (error), and a tooltip shows
the cause of the problem. Initiated By refers to the user that has originally established the tunnel. During
normal operations, this user is no longer needed. Instead, a certificate is used to open the connection to a
subaccount.
● The status of the certificate is shown next to Subaccount Certificate. It is shown as valid (green icon), if the
expiration date is still far in the future, and turns to yellow if expiration approaches according to your alert
settings. It turns red as soon as it has expired. This is the latest point in time, when you should Update the
Certificate for Your Subaccount [page 335].
318 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-318-320.jpg)
![ Note
When connected, you can monitor the Cloud Connector also in the Connectivity section of the SAP BTP
cockpit. There, you can track attributes like version, description and high availability set up. Every Cloud
Connector configured for your subaccount automatically appears in the Connectivity section of the cockpit.
Back toTasks [page 312]
Related Information
Managing Subaccounts [page 328]
Initial Configuration (HTTP) [page 319]
Initial Configuration (RFC) [page 321]
Configuring the Cloud Connector for LDAP [page 323]
Managing Member Authorizations in the Neo Environment
Use a Custom IDP for Subaccount Configuration [page 324]
1.2.2.1.1 Initial Configuration (HTTP)
Configure the Cloud Connector for HTTP communication.
Installation of a System Certificate for Mutual Authentication
To set up a mutual authentication between the Cloud Connector and any backend system it connects to, you
can import an X.509 client certificate into the Cloud Connector. The Cloud Connector then uses the so-called
system certificate for all HTTPS requests to backends that request or require a client certificate. The CA that
signed the Cloud Connector's client certificate must be trusted by all backend systems to which the Cloud
Connector is supposed to connect.
You must provide the system certificate as PKCS#12 file containing the client certificate, the corresponding
private key and the CA root certificate that signed the client certificate (plus potentially the certificates of any
intermediate CAs, if the certificate chain is longer than 2).
Procedure
From the left panel, choose Configuration. On the tab On Premise, choose System Certificate Import a
certificate to upload a certificate and provide its password:
SAP BTP Connectivity
Connectivity PUBLIC 319](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-319-320.jpg)
![A second option is to start a certificate signing request procedure as described for the UI certificate in
Recommended: Exchange UI Certificates in the Administration UI [page 303] and upload the resulting signed
certificate.
As of version 2.10, there is a third option - generating a self-signed certificate. It might be useful if no CA is
needed, for example, in a demo setup or if you want to use a dedicated CA. For this option, choose Create and
import a self-signed certificate:
320 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-320-320.jpg)
![If a system certificate has been imported successfully, its distinguished name, the name of the issuer, and the
validity dates are displayed:
If a system certificate is no longer required, you can delete it. To do this, use the respective button and confirm
deletion. If you need the public key for establishing trust with a server, you can simply export the full chain via
the Export button.
Related Information
Configure Access Control (HTTP) [page 370]
1.2.2.1.2 Initial Configuration (RFC)
Configure a Secure Network Connection (SNC) to set up the Cloud Connector for RFC communication to an
ABAP backend system.
SAP BTP Connectivity
Connectivity PUBLIC 321](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-321-320.jpg)
![SNC Configuration for Mutual Authentication
To set up a mutual authentication between Cloud Connector and an ABAP backend system (connected via
RFC), you can configure SNC for the Cloud Connector. It will then use the associated PSE for all RFC SNC
requests. This means that the SNC identity, represented by this PSE, must:
● Be trusted by all backend systems to which the Cloud Connector is supposed to connect
● Play the role of a trusted external system by adding the SNC name of the Cloud Connector to the
SNCSYSACL table. You can find more details in the SNC configuration documentation for the release of
your ABAP system.
Prerequisites
You have configured your ABAP system(s) for SNC. For detailed information on configuring SNC for an ABAP
system, see also Configuring SNC on AS ABAP. In order to establish trust for Principal Propagation, follow the
steps described in Configure Principal Propagation for RFC [page 354].
Configuration Steps
1. Logon to the Cloud Connector
2. Choose Configuration from the main menu and go to tab On Premise, section SNC.
3. Enter the corresponding values in the fields Library Name, My Name, and Quality of Protection
4. Press Save.
Example:
○ Library Name: Provides the location of the SNC library you are using for the Cloud Connector.
Note
Bear in mind that you must use one and the same security product on both sides of the
communication.
322 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-322-320.jpg)
![○ My Name: The SNC name that identifies the Cloud Connector. It represents a valid scheme for the
SNC implementation that is used.
○ Quality of Protection: Determines the level of protection that you require for the connectivity to the
ABAP systems.
Note
When using CommonCryptoLibrary as SNC implementation, note 1525059 will help you to configure
the PSE to be associated with the user running the Cloud Connector process.
Related Information
Configure Principal Propagation for RFC [page 354]
1.2.2.1.3 Configuring the Cloud Connector for LDAP
Configure the Cloud Connector to support LDAP in different scenarios (cloud applications using LDAP or Cloud
Connector authentication).
Prerequisites
You have installed the Cloud Connector and done the basic configuration:
Installation [page 273]
Initial Configuration [page 312]
Steps
When using LDAP-based user management, you have to confgure the Cloud Connector to support this feature.
Depending on the scenario, you need to perform the following steps:
Scenario 1: Cloud applications using LDAP for authentication. Configure the destination of the LDAP server in
the Cloud Connector: Configure Access Control (LDAP) [page 383].
Scenario 2: Internal Cloud Connector user management. Activate LDAP user management in the Cloud
Connector: Use LDAP for Authentication [page 503].
SAP BTP Connectivity
Connectivity PUBLIC 323](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-323-320.jpg)
![1.2.2.1.4 Use a Custom IDP for Subaccount Configuration
Enable custom identity provider (IDP) authentication to configure a Cloud Foundry subaccount in the Cloud
Connector by using a one-time passcode.
Content
Context [page 324]
Get the URL [Feature Set A] [page 327]
Get the URL [Feature Set B] [page 328]
Get the One-Time Passcode [page 328]
Context
For a subaccount in the Cloud Foundry environment that uses a custom IDP, you can choose this IDP for
authentication instead of the (default) SAP ID service when configuring the subaccount in the Cloud
Connector.
Using custom IDP authentication, you can perform the following operations in the Cloud Connector:
Operation Description
Set up Connection Parameters and HTTPS Proxy [page 315] Add an initial subaccount to a fresh Cloud Connector instal
lation.
Managing Subaccounts [page 328] Add additonal subaccounts to an existing Cloud Connector
installation.
Update the Certificate for a Subaccount [page 335] Refresh a subaccount certificate's validity period.
To enable custom IDP authentication, for each of these operations you must enter the marker value $SAP-CP-
SSO-PASSCODE$ in the <Subaccount User> or <User Name> field, and a one-time generated passcode
(known as temporary authentication code) in the <Password> field:
● When adding the initial subaccount to a fresh Cloud Connector installation, enter the user name $SAP-
CP-SSO-PASSCODE$ and the passcode on the Cloud Connector's Define Subaccount screen (see also Set
up Connection Parameters and HTTPS Proxy [page 315]):
324 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-324-320.jpg)
![● When adding one ore more additonal subaccount(s) to an existing Cloud Connector installation, provide
the user name $SAP-CP-SSO-PASSCODE$ and the passcode via the Connector screen (see also Managing
Subaccounts [page 328]):
SAP BTP Connectivity
Connectivity PUBLIC 325](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-325-320.jpg)
![● To refresh a subaccount certificate, enter the user name $SAP-CP-SSO-PASSCODE$ and the passcode
via the corresponding <Subaccount> screen (see also Update the Certificate for a Subaccount [page
335]):
To retrieve the one-time generated passcode, you must use the correct login URL for single sign-on (SSO) to
access your custom IDP. The procedure to get this URL depends on the SAP BTP feature set you are using.
Note
To choose the right procedure, you must know on which cloud management tools feature set (A or B) your
SAP BTP account is running. For more information on feature sets, see Cloud Management Tools — Feature
Set Overview.
326 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-326-320.jpg)
![Next Step
Get the URL [Feature Set A] [page 327]
Get the URL [Feature Set B] [page 328]
Caution
Mind the respective user rights described in the prerequisites for Initial Configuration [page 312] and
Managing Subaccounts [page 328]. For feature set A, it is mandatory to be a subaccount Security
Administrator, not only a global account member.
Back to Content [page 324]
Get the URL [Feature Set A]
Choose one of the following options:
Option 1: Assemble the URL
The URL pattern is https:/
/login.cf.<btp-region-host>/passcode.
1. Get the SAP BTP region host, for example, eu10.hana.ondemand.com.
2. Assemble the final URL to be used, in this case: https:/
/login.cf.eu10.hana.ondemand.com/passcode.
Option 2: Get the URL Using the Cloud Foundry CLI
Use the Cloud Foundry CLI to perform the following steps:
1. Execute the command cf api to navigate to the SAP BTP region.
2. Execute cf login --sso to get the URL.
Sample Code
$ cf api api.cf.eu10.hana.ondemand.com
Setting api endpoint to api.cf.eu10.hana.ondemand.com...
OK
api endpoint: https://api.cf.eu10.hana.ondemand.com
api version: 2.156.0
$ cf login --sso
API endpoint: https://api.cf.eu10.hana.ondemand.com
Temporary Authentication Code ( Get one at https://
login.cf.eu10.hana.ondemand.com/passcode ):
Next Step
Get the One-Time Passcode [page 328]
Back to Content [page 324]
SAP BTP Connectivity
Connectivity PUBLIC 327](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-327-320.jpg)
![Get the URL [Feature Set B]
Choose one of the following options:
Option 1: Assemble the URL
The URL pattern is https:/
/<subdomain>.authentication.<btp-XSUAA-host>/passcode.
1. Get the SAP BTP region host, for example, eu10.hana.ondemand.com.
2. Assemble the final URL to be used, in this case: https:/
/
mysubdomain.authentication.eu10.hana.ondemand.com/passcode.
Option 2: Get the URL Using the Connectivity Service Instance Credentials
1. Choose one of these steps to obtain the URL:
○ Create and Bind a Connectivity Service Instance [page 159]
○ Create a service key
2. Get the value of the token_service_url attribute.
3. Append /passcode at the end of the obtained URL.
Next Step
Get the One-Time Passcode [page 328]
Back to Content [page 324]
Get the One-Time Passcode
1. Open the resulting URL in your browser to get the one-time passcode via SSO:
○ If there is an active user session, the passcode is generated automatically and returned right away.
○ If there is no active user session, you are asked to log on to the IDP manually. If several IDPs are
configured, you can choose one from the available options.
2. Use the passcode to proceed with the subaccount configuration in the Cloud Connector UI.
Back to Content [page 324]
1.2.2.2 Managing Subaccounts
Add and connect your SAP BTP subaccounts to the Cloud Connector.
328 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-328-320.jpg)
![Environment Required Roles/Role Collections More Information
Cloud Foundry [feature set A] The user must be a member of the
global account that the subaccount be
longs to.
Alternatively, you can assign the user as
Security Administrator.
Add Members to Your Global Account
Managing Security Administrators in
Your Subaccount [Feature Set A]
Cloud Foundry [feature set B] Assign at least one of these default role
collections (all of them including the
role Cloud Connector
Administrator):
● Subaccount
Administrator
● Cloud Connector
Administrator
● Connectivity and
Destination
Administrator
Alternatively, you can assign a custom
role collection to the user that includes
the role Cloud Connector
Administrator.
Default Role Collections [Feature Set B]
[page 13]
Role Collections and Roles in Global Ac
counts and Subaccounts [Feature Set
B]
Neo Assign at least one of these default
roles:
● Cloud Connector Admin
● Administrator
Alternatively, you can assign a custom
role to the user that includes the per
mission manageSCCTunnels.
Managing Member Authorizations in
the Neo Environment
After establishing the Cloud Connector connection, this user is not needed any more, since it serves only for
initial connection setup. You may revoke the corresponding role assignment then and remove the user from the
Members list.
Note
If the Cloud Connector is installed in an environment that is operated by SAP, SAP provides a user that you
can add as member in your SAP BTP subaccount and assign the required role.
Subaccount Dashboard
In the subaccount dashboard (choose your Subaccount from the main menu), you can check the state of all
subaccount connections managed by this Cloud Connector at a glance.
330 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-330-320.jpg)
![Procedure
1. The <Region> field specifies the SAP BTP region that should be used, for example, Europe (Rot).
Choose the one you need from the drop-down list.
Note
You can also configure a region yourself, if it is not part of the standard list. Either insert the region host
manually, or create a custom region, as described in Configure Custom Regions [page 339].
2. For <Subaccount> and <Subaccount User> (user/password), enter the values you obtained when you
registered your account on SAP BTP.
Note
If your subaccount is on Cloud Foundry, you must enter the subaccount ID as <Subaccount>, rather
than its actual (technical) name. For information on getting the subaccount ID, see Find Your
Subaccount ID (Cloud Foundry Environment) [page 338]. As <Subaccount User> you must provide
your Login E-mail instead of a user ID.
For the Neo environment, enter the subaccount's technical name in the field <Subaccount>, not the
subaccount ID.
Alternatively, you can add a new subaccount user in the SAP BTP cockpit, assign the required
authorization (see section Prerequisites above), and use the new user and password.
Tip
When using SAP Cloud Identity Services - Identity Authentication (IAS) as platform identity provider
with two-factor authentication for your subaccount, you can simply append the required token to the
regular password.
Tip
For a subaccount in the Cloud Foundry environment, the Cloud Connector supports the use of a
custom identity provider (IDP) via single sign-on (SSO) passcode. For more information, see Use a
Custom IDP for Subaccount Configuration [page 324].
3. (Optional) You can define a <Display Name> that allows you to easily recognize a specific subaccount in
the UI compared to the technical subaccount name.
4. (Optional) You can define a <Location ID> that identifies the location of this Cloud Connector for a
specific subaccount. As of Cloud Connector release 2.9.0, the location ID is used as routing information
and therefore you can connect multiple Cloud Connectors to a single subaccount. If you don't specify any
value for <Location ID>, the default is used, which represents the behavior of previous Cloud Connector
versions. The location ID must be unique per subaccount and should be an identifier that can be used in a
URI. To route requests to a Cloud Connector with a location ID, the location ID must be configured in the
respective destinations.
5. (Optional) You can provide a <Description> of the subaccount that is shown when clicking on the Details
icon in the Actions column.
6. Choose Save.
332 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-332-320.jpg)
![Next Steps
● To modify an existing subaccount, choose the Edit icon and change the <Display Name>, <Location
ID> and/or <Description>.
● You can also delete a subaccount from the list of connections.The subaccount will be disconnected and all
configurations will be removed from the installation.
Related Information
Managing Member Authorizations in the Neo Environment
Copy a Subaccount Configuration [page 333]
Update the Certificate for a Subaccount [page 335]
Configure a Disaster Recovery Subaccount [page 336]
Find Your Subaccount ID (Cloud Foundry Environment) [page 338]
Configure Custom Regions [page 339]
1.2.2.2.1 Copy a Subaccount Configuration
Copy an existing subcaccount configuration in the Cloud Connector to another subaccount.
You can copy the configuration of a subaccount's Cloud To On-Premise and On-Premise To Coud sections to a
new subaccount, by using the export and import functions in the Cloud Connector administration UI.
SAP BTP Connectivity
Connectivity PUBLIC 333](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-333-320.jpg)
![ Note
The technical subaccount name, the display name, and the location ID must remain the same. They are set
automatically and cannot be changed.
Note
You cannot choose another original subaccount nor a trial subaccount to become a disaster recovery
subaccount.
Note
If you want to change a disaster recovery subaccount, you must delete it first and then configure it again.
To switch from the original subaccount to the disaster recovery subaccount, choose Employ disaster recovery
subaccount.
The disaster recovery subaccount then becomes active, and the original subaccount is deactivated.
You can switch back to the original subaccount as soon as it is available again.
Note
As of Cloud Connector 2.11, the cloud side informs about a disaster by issuing an event. In this case, the
switch is performed automatically.
Related Information
Convert a Disaster Recovery Subaccount into a Standard Subaccount [page 338]
SAP BTP Connectivity
Connectivity PUBLIC 337](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-337-320.jpg)
![1.2.2.2.5 Configure Custom Regions
Configure regions that are not available in the standard selection.
If you want to use a custom region for your subaccount, you can configure regions in the Cloud Connector,
which are not listed in the selection of standard regions.
To add a custom region, do the following:
1. From the Cloud Connector main menu, choose Configuration Cloud and go to the Custom Regions
section.
2. To add a region to the list, choose the Add icon.
3. In the Add Region dialog, enter the <Region> and <Region Host> you want to use.
4. Choose Save.
5. To edit a region from the list, select the corresponding line and choose the Edit icon.
1.2.2.3 Authenticating Users against On-Premise Systems
Authentication types supported by the Cloud Connector.
Currently, the Cloud Connector supports basic authentication and principal propagation (user propagation)
as user authentication types towards internal systems. The destination configuration of the used cloud
application defines which of these types is used for the actual communication to an on-premise system
through the Cloud Connector, see Managing Destinations [page 38].
● To use basic authentication, configure an on-premise system to accept basic authentication and to
provide one or multiple service users. No additional steps are necessary in the Cloud Connector for this
authentication type.
SAP BTP Connectivity
Connectivity PUBLIC 339](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-339-320.jpg)
![● To use principal propagation, you must explicitly configure trust to those cloud entities from which user
tokens are accepted as valid. You can do this in the Trust view of the Cloud Connector, see Set Up Trust for
Principal Propagation [page 341].
Related Information
Configuring Principal Propagation [page 340]
1.2.2.3.1 Configuring Principal Propagation
Use principal propagation to simplify the access of SAP BTP users to on-premise systems.
Tasks in this section:
Task Description
Set Up Trust for Principal Propagation [page 341] Configure a trusted relationship in the Cloud Connector to
support principal propagation. Principal propagation lets you
forward the logged-on identity in the cloud to the internal
system without requesting a password.
Configure a CA Certificate for Principal Propagation [page
344]
Install and configure an X.509 certificate to enable support
for principal propagation.
Configuring Principal Propagation to an ABAP System [page
347]
Learn more about the different types of configuring and sup
porting principal propagation for a particular AS ABAP.
Configure a Subject Pattern for Principal Propagation [page
359]
Define a pattern identifying the user for the subject of the
generated short-lived X.509 certificate, as well as its valid
ity period.
Configure a Secure Login Server [page 361] Configuration steps for Java Secure Login Server (SLS) sup
port.
Configure Kerberos [page 365] The Cloud Connector lets you propagate users authenti
cated in SAP BTP via Kerberos against back-end systems. It
uses the Service For User and Constrained Delegation pro
tocol extension of Kerberos.
Configuring Principal Propagation to SAP NetWeaver AS for
Java [page 367]
Find step-by-step instructions on how to configure principal
propagation to an application server Java (AS Java).
Related Information
340 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-340-320.jpg)
![Principal Propagation [page 121] (Cloud Foundry environment)
Principal Propagation (Neo environment)
1.2.2.3.1.1 Set Up Trust for Principal Propagation
Establish trust to an identiy provider to support principal propagation.
Tasks
Configure Trusted Entities in the Cloud Connector [page 341]
Configure an On-Premise System for Principal Propagation [page 342]
Trust Cloud Applications in the Cloud Connector [page 343]
Set up a Trust Store [page 343]
Configure Trusted Entities in the Cloud Connector
You perform trust configuration to support principal propagation. By default, your Cloud Connector does not
trust any entity that issues tokens for principal propagation. Therefore, the list of trusted identity providers is
empty by default. If you decide to use the principal propagation feature, you must establish trust to at least one
identiy provider. Currently, SAML2 identity providers are supported. You can configure trust to one or more
SAML2 IdPs per subaccount. After you've configured trust in the cockpit for your subaccount, for example, to
your own company's identity provider(s), you can synchronize this list with your Cloud Connector.
As of Cloud Connector 2.4, you can also trust HANA instances and Java applications to act as identity
providers.
From your subaccount menu, choose Cloud to On-Premise and go to the Principal Propagation tab. Choose the
Synchronize button to store the list of existing identity providers locally in your Cloud Connector.
Select an entry to see its details:
SAP BTP Connectivity
Connectivity PUBLIC 341](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-341-320.jpg)
![● Name: the name associated with the identity provider.
● Description: descriptive information about this entry.
● Type: type of the trusted entity.
● Trusted: indicates whether the entry is trusted for principal propagation.
● Actions: Choose the Show Certificate Information icon to display detail information for the corresponding
entry. The Cloud Connector runtime will use the certificate associated with the entry to verify that the
assertion used for principal propagation was issued by a trusted entity.
You can decide for each entry, whether to trust it for the principal propagation use case by choosing Edit and
(de)selecting the Trusted checkbox.
Note
Whenever you update the SAML IdP configuration for a subaccount on cloud side, you must synchronize
the trusted entities in theCloud Connector. Otherwise the validation of the forwarded SAML assertion will
fail with an exception containing an exception message similar to this: Caused by:
com.sap.engine.lib.xml.signature.SignatureException: Unable to validate signature ->
java.security.SignatureException: Signature decryption error: javax.crypto.BadPaddingException: Invalid
PKCS#1 padding: encrypted message and modulus lengths do not match!.
Back to Tasks [page 341]
Configure an On-Premise System for Principal Propagation
Set up principal propagation from SAP BTP to your internal system that is used in a hybrid scenario.
Note
As a prerequisite for principal propagation for RFC, the following cloud application runtime versions are
required:
● for Java Web: 1.51.8 or higher
● for Java EE 6 Web Profile: 2.31.11 or higher
● other runtimes support it with any version
1. Set up trust to an entity that is issuing an assertion for the logged-on user (see section above).
2. Set up the system identity for the Cloud Connector.
○ For HTTPS, you must import a system certificate into your Cloud Connector.
○ For RFC, you must import an SNC PSE into your Cloud Connector.
3. Configure the target system to trust the Cloud Connector.
There are two levels of trust:
1. First, you must allow the Cloud Connector to identify itself with its system certificate (for HTTPS), or
with the SNC PSE (for RFC).
2. Then, you must allow this identity to propagate the user accordingly:
342 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-342-320.jpg)
![○ For HTTPS, the Cloud Connector forwards the true identity in a short-lived X.509 certificate in an
HTTP header named SSL_CLIENT_CERT. The system must use this certificate for logging on the
real user. The SSL handshake, however, is performed through the system certificate.
○ For RFC, the Cloud Connector forwards the true identity as part of the RFC protocol.
For more information, see Configuring Principal Propagation to an ABAP System [page 347].
4. Configure the user mapping in the target system. The X.509 certificate contains information about the
cloud user in its subject. Use this information to map the identity to the appropriate user in this system.
This step applies for both HTTPS and RFC.
Note
If you have the following scenario: Application1->AppToAppSS0->Application2->Principal Propagation->On
premise Backend System you must mark Application2 as trusted by the Cloud Connector in tab Principal
Propagation, section Trust Configuration.
If you use an identity provider that issues unsigned assertions, you must mark all relevant applications as
trusted by the Cloud Connector in tab Principal Propagation, section Trust Configuration.
Back to Tasks [page 341]
Trust Cloud Applications in the Cloud Connector
Configure an allowlist for trusted cloud applications, see Configure Trust [page 490].
Back to Tasks [page 341]
Set up a Trust Store
Configure a trust store that acts as an allowlist for trusted on-premise systems. See Configure Trust [page
490].
Back to Tasks [page 341]
Related Information
Principal Propagation [page 121] (Cloud Foundry)
Principal Propagation (Neo)
SAP BTP Connectivity
Connectivity PUBLIC 343](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-343-320.jpg)
![1.2.2.3.1.2 Configure a CA Certificate for Principal
Propagation
Install and configure an X.509 certificate to enable support for principal propagation in the Cloud Connector.
Supported CA Mechanisms
You can enable support for principal propagation with X.509 certificates by performing either of the following
procedures:
● Using a Local CA in the Cloud Connector.
Note
Prior to version 2.7.0, this was the only option and the system certificate was acting both as client
certificate and CA certificate in the context of principal propagation.
● Using a Secure Login Server and delegate the CA functionality to it.
The Cloud Connector uses the configured CA approach to issue short-lived certificates for logging on the same
identity in the back end that is logged on in the cloud. For establishing trust with the back end, the respective
configuration steps are independent of the approach that you choose for the CA.
Install a local CA Certificate
To issue short-lived certificates that are used for principal propagation to a back-end system, you can import an
X.509 client certificate into the Cloud Connector. This CA certificate must be provided as PKCS#12 file
containing the (intermediate) certificate, the corresponding private key, and the CA root certificate that signed
the intermediate certificate (plus the certificates of any other intermediate CAs, if the certificate chain includes
more than those two certificates).
Use either of the following options to install a local CA certificate:
● Option 1: Choose the PKCS#12 file from the file system, using the file upload dialog. For the import
process, you must also provide the file password.
● Option 2: Start a Certificate Signing Request (CSR) procedure like for the UI certificate, see Recommended:
Exchange UI Certificates in the Administration UI [page 303].
● Option 3: (As of version 2.10) Generate a self-signed certificate, which might be useful in a demo setup or if
you need a dedicated CA. In particular for this option, it is useful to export the public key of the CA via the
button Download certificate in DER format.
Note
The CA certificate should have the KeyUsage attribute keyCertSign. Many systems verify that the issuer
of a certificate includes this attribute and deny a client certificate without this attribute. When using the
CSR procedure, the attribute is requested for the CA certificate. Also, when generating a self-signed
certificate, this attribute is added automatically.
344 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-344-320.jpg)
![If a CA certificate is no longer required, you can delete it. Use the respective Delete button and confirm the
deletion.
Configure a CA Hosted by a Secure Login Server
If you want to delegate the CA functionality to a Secure Login Server, choose the CA using Secure Login Server
option and configure the Secure Login Server as follows, after having configured the Secure Login server as
described in Configure a Secure Login Server [page 361].
Enter the following:
● <Host Name>: The host, on which your Secure Login Server (SLS) is installed.
● <Profiles Port>: The profiles port must be provided only when your Secure Login Server is configured
to not allow to fetch profiles via the privileged authentication port. In this case, you can provide here the
port that is configured for that functionality.
● <Authentication Port>: The port, over which the Cloud Connector is requesting the short-lived
certificates from SLS. Choose Next.
Note
For this privileged port, a client certificate authentication is required, for which the Cloud Connector
system certificate is used.
● <Profile>: The Secure Login Server profile that allows to issue certificates as needed for principal
propagation with the Cloud Connector.
Choose Finish to store the configuration.
346 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-346-320.jpg)
![Related Information
Configure a Secure Login Server [page 361]
Initial Configuration (HTTP) [page 319]
Initial Configuration (RFC) [page 321]
1.2.2.3.1.3 Configuring Principal Propagation to an ABAP
System
Learn more about the different types of configuring and supporting principal propagation for a particular AS
ABAP.
Task Description
Configure Principal Propagation for HTTPS [page 347] Step-by-step instructions to configure principal propagation
to an ABAP server for HTTPS.
Configure Principal Propagation via SAP Web Dispatcher
[page 351]
Set up a trust chain to use principal propagation to an ABAP
server for HTTPS via SAP Web Dispatcher.
Configure Principal Propagation for RFC [page 354] Step-by-step instructions to configure principal propagation
to an ABAP server for RFC.
Rule-Based Mapping of Certificates [page 358] Map short-lived certificates to users in the ABAP server.
1.2.2.3.1.3.1 Configure Principal Propagation for HTTPS
Find step-by-step instructions to configure principal propagation to an ABAP server for HTTPS.
Example Data
The following data are used in this example:
● System certificate was issued by: CN=MyCompany CA, O=Trust Community, C=DE.
● It has the subject: CN=SCC, OU=HCP Scenarios, O=Trust Community, C=DE.
● The short-lived certificate has the subject CN=P1234567890, where P1234567890 is the platform user.
Tasks
Prerequisites [page 348]
SAP BTP Connectivity
Connectivity PUBLIC 347](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-347-320.jpg)
![Configure an ABAP System to Trust the Cloud Connector's System Certificate [page 348]
Map Short-Lived Certificates to Users [page 350]
Access ICF Services [page 350]
Prerequisites
To perform the following steps, you must have the corresponding authorizations in the ABAP system for the
transactions mentioned below (administrator role according to your specific authorization management) as
well as an administrator user for the Cloud Connector.
Back to Tasks [page 347]
Back to Example Data [page 347]
1. Configure an ABAP System to Trust the Cloud Connector's System
Certificate
This step includes two sub-steps:
Configure the ABAP system to trust the Cloud Connector's system certificate [page 348]
Configure the Internet Communication Manager (ICM) to trust the system certificate for principal propagation
[page 349]
Configure the ABAP system to trust the Cloud Connector's system certificate:
1. Open the Trust Manager (transaction STRUST).
2. Double-click the SSL-Server Standard folder in the menu tree on the left.
3. In the displayed screen, click the Import certificate button.
4. In the dialog window, choose the certificate file representing the public key of the issuer of the system
certificate, for example, in DER format. Typically, this is a CA certificate. If you decide to use a self-signed
system certificate, it is the system certificate itself.
5. The details of this certificate are shown in the section above. Using the example certificate data, you would
see CN=MyCompany CA, O=Trust Community, C=DE as subject.
6. If you are sure that you are importing the correct certificate, you can integrate the certificate into the
certificate list by choosing the Add to Certificate List button.
7. Now, the CA certificate (CN=MyCompany CA, O=Trust Community, C=DE) is part of the certificate list.
Back to Step [page 348]
348 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-348-320.jpg)
![Configure the Internet Communication Manager (ICM) to trust the system certificate for principal
propagation:
1. Open the Profile Editor (transaction RZ10).
2. Select the profile you want to edit, for example, the DEFAULT profile.
3. Select the Extended maintenance radio button and choose the Change button.
4. Create the following parameter: icm/trusted_reverse_proxy_<x> = SUBJECT="<subject>",
ISSUER="<issuer>".
○ Select a free index for <x>.
○ <subject> is the subject of the system certificate (example data: CN=SCC, OU=BTP Scenarios,
O=Trust Community, C=DE).
○ <issuer> is the issuer of the system certificate (example data: CN=MyCompany CA, O=Trust
Community, C=DE ).
○ Example: icm/trusted_reverse_proxy_2 = SUBJECT=" CN=SCC, OU=BTP Scenarios,
O=Trust Community, C=DE ", ISSUER=" CN=MyCompany CA, O=Trust Community, C=DE
".
Note
If your ABAP system uses kernel 7.42 or lower, see SAP note 2052899 or set the following two
parameters:
○ icm/HTTPS/trust_client_with_issuer: this is the issuer of the system certificate (example
data: CN=MyCompany CA, O=Trust Community, C=DE).
○ icm/HTTPS/trust_client_with_subject: this is the subject of the system certificate
(example data: CN=SCC, OU=HCP Scenarios, O=Trust Community, C=DE).
Caution
Make sure that icm/HTTPS/verify_client is set to either 1 (request certificate) or 2 (require
certificate). If the parameter is set to 0, trust cannot be established.
5. Save the profile.
6. Open the ICM Monitor (transaction SMICM) and restart the ICM by choosing Administration ICM Exit
Hard Global .
7. Verify that the two profile parameters have been taken over by ICM by choosing Goto Parameters
Display .
Note
If you have an SAP Web Dispatcher installed in front of the ABAP system, trust must be added in its
configuration files with the same parameters as for the ICM. Also, you must add the system certificate of
the Cloud Connector to the trust list of the Web dispatcher Server PSE. For more information, see
Configure Principal Propagation via SAP Web Dispatcher [page 351].
Caution
When using principal propagation with X.509 certificates, you cannot use the strict mode in certificate
block management (transaction code: CRCONFIG) for the CRL checks within profile SSL_SERVER.
SAP BTP Connectivity
Connectivity PUBLIC 349](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-349-320.jpg)
![Back to Step [page 348]
Back to Tasks [page 347]
Back to Example Data [page 347]
2. Map Short-Lived Certificates to Users
For systems later than SAP NetWeaver 7.3 EHP1 (7.31), you can use rule-based certificate mapping, which is the
recommended way to create the required user mappings. For more information, see Rule-Based Mapping of
Certificates [page 358].
In older releases (for which this feature does not exist yet), you can do this manually in the system as described
below, or use an identity management solution generating the mapping table for a more comfortable approach.
1. Open Assignment of External ID to Users (transaction EXTID_DN).
2. Switch to the edit mode.
3. Create a new entry. Specify the subject of the certificate as External ID. When using the example data,
this is CN=P1234567890. In the User field, provide the appropriate ABAP user, for example JOHNSMITH.
4. Choose Activate.
5. Save the mapping.
6. Repeat the previous steps for all users that should be supported for the scenario.
Back to Tasks [page 347]
Back to Example Data [page 347]
3. Access ICF Services
To access the required ICF services for your scenario in the ABAP system, choose one of the following
procedures:
● To access ICF services via certificate logon, choose the principal type X.509 Certificate (general
usage) in the corresponding system mapping. This setting lets you use the system certificate for trust as
well as for user authentication. For details, see Configure Access Control (HTTP) [page 370], step 7.
Additionally, make sure that all required ICF services allow Logon Through SSL Certificate as logon
method.
● To access ICF services via the logon method Basic Authentication (logon with user/password) and
principal propagation, choose the principal type X.509 Certificate (strict usage) in the
corresponding system mapping. This setting lets you use the system certificate for trust, but prevents its
usage for user authentication. For details, see Configure Access Control (HTTP) [page 370], step 7.
Additionally, make sure that all required ICF services allow Basic Authentication and Logon Through
SSL Certificate as logon methods.
350 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-350-320.jpg)
![● If some of the ICF services require Basic Authentication, while others should be accessed via system
certificate logon, proceed as follows:
1. In the Cloud Connector sytem mapping, choose the principal type X.509 Certificate (general
usage) as described above.
2. In the ABAP system, choose transaction code SICF and go to Maintain Services.
3. Select the service that requires Basic Authentication as logon method.
4. Double-click the service and go to tab Logon Data.
5. Switch to Alternative Logon Procedure and ensure that the Basic Authentication logon procedure
is listed before Logon Through SSL Certificate.
Note
If you are using SAP Web Dispatcher for communication, you must configure it to forward the SSL
certficate to the ABAP backend system, see Forward SSL Certificates for X.509 Authentication (SAP Web
Dispatcher documentation).
Back to Tasks [page 347]
Back to Example Data [page 347]
Related Information
Configure Principal Propagation via SAP Web Dispatcher [page 351]
Rule-Based Mapping of Certificates [page 358]
Configure a Subject Pattern for Principal Propagation [page 359]
Set Up Trust for Principal Propagation [page 341]
Principal Propagation [page 121] (Cloud Foundry environment)
Principal Propagation (Neo environment)
1.2.2.3.1.3.1.1 Configure Principal Propagation via SAP Web
Dispatcher
Set up a trust chain to use principal propagation to an ABAP System for HTTPS via SAP Web Dispatcher.
Concept
SAP BTP Connectivity
Connectivity PUBLIC 351](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-351-320.jpg)
![If you are using an intermediate SAP Web Dispatcher to connect to your ABAP backend system, you must set
up a trust chain between the involved components Cloud Connector, SAP Web Dispatcher, and ABAP backend
system.
Before configuring the ABAP system (see Configure Principal Propagation for HTTPS [page 347]), in a first step
you must configure SAP Web Dispatcher to accept and forward user principals propagated from a cloud
account to an ABAP backend.
To do this, follow the step-by-step instructions below.
Example Data
The following data and setup is used for this scenario:
● System certificate was issued by CN=MyCompany CA, O=Trust Community, C=DE
● It has the subject CN=SCC, OU=BTP Scenarios, O=Trust Community, C=DE
Tasks
● Prerequisites [page 352]
● Configure the SAP Web Dispatcher to Trust the Cloud Connector's System Certificate [page 353]
● Next Steps [page 354]
Prerequisites
● Your SAP Web Dispatcher version is 7.53 or higher. See SAP note 908097 for information on
recommended SAP Web Dispatcher versions.
● Make sure your SAP Web Dispatcher supports SSL. See Configure SAP Web Dispatcher to Support SSL.
● Ensure that SSL client certificates can be used for authentication in the backend system. See How to
Configure SAP Web Dispatcher to Forward SSL Certificates for X.509 Authentication for step-by-step
instructions.
Back to Tasks [page 352]
Back to Concept [page 351]
352 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-352-320.jpg)
![Configure SAP Web Dispatcher to Trust the Cloud Connector's System
Certificate
To allow Cloud Connector client certificates for authentication in the backend system, perform the following
two steps:
1. Configure SAP Web Dispatcher to trust the Cloud Connector's system certificate:
1. To import the system certificate to SAP Web Dispatcher, open the SAP Web Dispatcher administration
interface in your browser.
Note
The interface is usually configured on /sap/wdisp/admin.
2. In the menu, navigate to SSL and Trust Configuration and select PSE Management.
3. In the Manage PSE section, select SAPSSLS.pse from the drop-down list. By default, SAPSSLS.pse
contains the server certificate and the list of trusted clients that SAP Web Dispatcher trusts as a
server.
4. In the Trusted Certificates section, choose Import Certificate.
5. Enter the certificate as base64-encoded into the text box. The procedure to export your certificate in
such a format is described in Forward SSL Certificates for X.509 Authentication, step 1.
Note
Typically, this is a CA certificate. If you are using a self-signed system certificate, it's the system
certificate itself.
6. Choose Import.
7. The certificate details are now shown in section Trusted Certificates.
2. Configure SAP Web Dispatcher to trust the Cloud Connector's system certificate for principal
propagation:
○ Create or edit the following parameter in SAP Web Dispatcher:
icm/trusted_reverse_proxy_<x> = SUBJECT="<subject>", ISSUER="<issuer>"
○ Select a free index for <x>.
○ <subject>: Subject of the system certificate (example data: CN=SCC, OU=BTP Scenarios,
O=Trust Community, C=DE)
○ <issuer>: Issuer of the system certificate (example data: CN=MyCompany CA, O=Trust
Community, C=DE)
Example: icm/trusted_reverse_proxy_0 = SUBJECT="CN=SCC, OU=BTP Scenarios,
O=Trust Community, C=DE", ISSUER="CN=MyCompany CA, O=Trust Community, C=DE"
○ [Deprecated] Create or edit the following two parameters in SAP Web Dispatcher:
Note
Use the parameters below (instead of icm/trusted_reverse_proxy_<x>) only if your kernel
release does not yet support parameter icm/trusted_reverse_proxy_<x>.
○ icm/HTTPS/trust_client_with_issuer: Issuer of the system certificate (example data:
CN=MyCompany CA, O=Trust Community, C=DE)
SAP BTP Connectivity
Connectivity PUBLIC 353](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-353-320.jpg)
![○ icm/HTTPS/trust_client_with_subject: Subject of the system certificate (example data:
CN=SCC, OU=BTP Scenarios, O=Trust Community, C=DE )
Note
Make sure icm/HTTPS/verify_client is set to 1 (request certificate) or 2 (require certificate). If set to
0, trust cannot be established. The default value is 1, so it is OK if the parameter is not set at all.
Back to Tasks [page 352]
Back to Concept [page 351]
Next Steps
Now you can proceed with:
● Step 1 of the basic principal propagation setup for HTTPS, see Configure an ABAP System to Trust the
Cloud Connector's System Certificate [page 348]. However, when using SAP Web Dispatcher, the ABAP
backend must trust the SAP Web Dispatcher instead of the Cloud Connector, see Forward SSL Certificates
for X.509 Authentication, step 2 for details.
Then perform the remaining steps of the basic principal propagation setup for HTTPS as described here:
● Map Short-Lived Certificates to Users [page 350]
● Access ICF Services [page 350]
Back to Tasks [page 352]
Back to Concept [page 351]
1.2.2.3.1.3.2 Configure Principal Propagation for RFC
Find step-by-step instructions to configure principal propagation to an ABAP server for RFC.
Configuring principal propagation for RFC requires an SNC (Secure Network Communications) connection. To
enable SNC, you must configure the ABAP system and the Cloud Connector accordingly.
The following example provides step-by-step instructions for the SNC setup.
Note
It is important that you use the same SNC implementation on both communication sides. Contact the
vendor of your SNC solution to check the compatibility rules.
354 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-354-320.jpg)
![Example Data
The following data and setup is used:
Note
The parameters provided in this example are based on an SNC implementation that uses the SAP
Cryptographic Library. Other vendors' libraries may require different values.
● An SNC identity has been generated and installed on the Cloud Connector host. Generating this identity for
the SAP Cryptographic Library is typically done using the tool SAPGENPSE. For more information, see
Configuring SNC for SAPCRYPTOLIB Using SAPGENPSE.
● The ABAP system is configured properly for SNC.
Note
For the latest system releases, you can use the SSO wizard to configure SNC (transaction code:
SNCWIZARD). System prerequisites are described in SAP note 2015966 .
● The Cloud Connector system identity's SNC name is p:CN=SCC, OU=SAP CP Scenarios, O=Trust
Community, C=DE.
● The ABAP system's SNC identity name is p:CN=SID, O=Trust Community, C=DE. This value can
typically be found in the ABAP system instance profile parameter snc/identity/as and hence is
provided per application server.
● When using the SAP Cryptographic Library, the ABAP system's SNC identity and the Cloud Connector's
system identity should be signed by the same CA for mutual authentication.
● The example short-lived certificate has the subject CN=P1234567, where P1234567 is the SAP BTP
application user.
Tasks
1. Configure the ABAP System [page 355]
2. Map Short-Lived Certificates to Users [page 356]
3. Configure the Cloud Connector [page 356]
1. Configure the ABAP System to Trust the Cloud Connector's System SNC
identity
1. Open the SNC Access Control List for Systems (transaction SNC0).
2. As the Cloud Connector does not have a system ID, use an arbitray value for <System ID> and enter it
together with its SNC name: p:CN=SCC, OU=SAP CP Scenarios, O=Trust Community, C=DE.
3. Save the entry and choose the Details button.
SAP BTP Connectivity
Connectivity PUBLIC 355](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-355-320.jpg)
![4. In the next screen, activate the checkboxes for Entry for RFC activated and Entry for certificate activated.
5. Save your settings.
Back to Tasks [page 355]
Back to Example Data [page 355]
2. Map Short-Lived Certificates to Users
You can do this manually in the system as described below or use an identity management solution for a more
comfortable approach. For example, for large numbers of users the rule-based certificate mapping is a good
way to save time and effort. See Rule-Based Certificate Mapping.
1. Open Assignment of External ID to Users (transaction EXTID_DN).
2. Switch to the edit mode.
3. Create a new entry. Specify the subject of the certificate as External ID. Using the example data, this is
CN=P1234567. In the <User> field, provide an appropriate ABAP user, for example JOHNDOE.
4. Save the mapping.
5. Repeat the previous steps for all users that should be supported for the scenario.
Back to Tasks [page 355]
Back to Example Data [page 355]
3. Configure the Cloud Connector
Prerequisites [page 356]
Set up the Cloud Connector to Use the SNC Implementation [page 357]
Create an RFC Hostname Mapping [page 357]
Prerequisites
● The required security product for the SNC flavor that is used by your ABAP back-end systems, is installed
on the Cloud Connector host.
● The Cloud Connector's system SNC identity is associated with the operating system user under which the
Cloud Connector process is running.
Note
SAP note 2642538 provides a description how you can associate an SNC identity of the SAP
Cryptographic Library with a user running an external program that uses JCo. If you use the SAP
Cryptographic Library as SNC implementation, perform the corresponding steps for the Cloud
Connector. When using a different product, contact the SNC library vendor for details.
Back to Step [page 356]
356 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-356-320.jpg)
![Set up the Cloud Connector to Use the SNC Implementation
1. In the Cloud Connector UI, choose Configuration from the main menu, select the On Premise tab, and go to
the SNC section.
2. Provide the fully qualified name of the SNC library (the security product's shared library implementing the
GSS API), the SNC name of the above system identity, and the desired quality of protection by choosing
the Edit icon.
For more information, see Initial Configuration (RFC) [page 321].
Note
The example in Initial Configuration (RFC) [page 321] shows the library location if you use the SAP
Secure Login Client as your SNC security product. In this case (as well as for some other security
products), SNC My Name is optional, because the security product automatically uses the identity
associated with the current operating system user under which the process is running, so you can
leave that field empty. (Otherwise, in this example it should be filled with p:CN=SCC, OU=SAP CP
Scenarios, O=Trust Community, C=DE.)
We recommend that you enter Maximum Protection for <Quality of Protection>, if your
security solution supports it, as it provides the best protection.
3. Choose Save and Close.
Back to Step [page 356]
Create an RFC Hostname Mapping
1. In the Access Control section of the Cloud Connector, create a hostname mapping corresponding to the
cloud-side RFC destination. See Configure Access Control (RFC) [page 377].
2. Make sure you choose RFC SNC as <Protocol> and ABAP System as <Back-end Type>. In the <SNC
Partner Name> field, enter the ABAP system's SNC identitiy name, for example, p:CN=SID, O=Trust
Community, C=DE.
3. Save your mapping.
Back to Step [page 356]
Back to Tasks [page 355]
Back to Example Data [page 355]
Related Information
Secure Network Communications (SNC)
Using the SAP Cryptographic Library for SNC
Rule-Based Mapping of Certificates [page 358]
Principal Propagation [page 121] (Cloud Foundry environment)
Principal Propagation (Neo environment)
SAP BTP Connectivity
Connectivity PUBLIC 357](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-357-320.jpg)
![1.2.2.3.1.3.3 Rule-Based Mapping of Certificates
Learn how to efficiently map short-lived certificates to users in the ABAP server.
To perform rule-based mapping of certificates in the ABAP server, proceed as follows:
1. Enter a dynamic parameter using transaction RZ11.
1. Enter the login/certificate_mapping_rulebased parameter.
2. Choose the Change Value button.
3. Enter the value 1.
4. Save the value.
Note
If dynamic parameters are disabled, enter the value using transaction RZ10 and restart the whole
ABAP system.
2. Configure rule-based mapping
1. To create a sample certificate with the Cloud Connector, logon to the Cloud Connector UI and from the
main menu, choose Configuration. In the System Certificate section, enter a sample CN name and
download the sample certificate to the Downloads folder of your machine.
2. To import the sample certificate into the ABAP server, choose transaction CERTRULE and
selectImport certificate.
Note
To access transaction CERTRULE, you need the corresponding authorizations (see: Assign
Authorization Objects for Rule-based Mapping [page 359]).
3. To create explicit rule mappings, choose the Rule button.
4. Choose Save.
Note
When you save the changes and return to transaction CERTRULE, the sample certificate which you
imported in Step 2b will not be saved. This is just a sample editor view to see the sample
certificates and mappings.
Related Information
Rule-Based Certificate Mapping
358 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-358-320.jpg)
![● <OU>: (name of organizational unit) – the organizational unit to which the certificate owner belongs
● <ST>: (state of residence) – the state in which the certificate issuer resides
● <C>: (country of residence) – the country in which the certificate owner resides
● <Expiration Tolerance (h)>: The length of time in hours, that an application can use a principal
issued for a user after the token from cloud side has expired.
● <Certificate Validity (min)>: The length of time in minutes, that a certificate generated for
principal propagation can authenticate against the back end. You can reuse a previously generated
certificate to improve performance.
Sample Certificate
By choosing Generate Sample Certificate you can create a sample certificate that looks like one of the short-
lived certificates created at runtime. You can use this certificate to, for example, generate user mapping rules in
the target system, via transaction CERTRULE in an ABAP system. If your subject pattern contains variable
fields, a wizard lets you provide meaningful values for each of them and eventually you can save the sample
certificate in DER format.
Related Information
Server Certificate Authentication [page 65]
1.2.2.3.1.5 Configure a Secure Login Server
Configuration steps for Java SLS support.
SAP BTP Connectivity
Connectivity PUBLIC 361](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-361-320.jpg)
![Content
Overview [page 362]
Requirements [page 363]
Implementation [page 363]
Overview
The Cloud Connector can use on-the-fly generated X.509 user certificates to log in to on-premise systems if
the external user session is authenticated (for example by means of SAML). If you do not want to use the built-
in certification authority (CA) functionality of the Cloud Connector (for example because of security
considerations), you can connect SAP SSO 2.0 Secure Login Server (SLS).
SLS is a Java application running on AS JAVA 7.20 or higher, which provides interfaces for certificate
enrollment.
SLS supports the following formats:
● HTTPS
● REST
● JSON
● PKCS#10/PKCS#7
Note
Any enrollment requires a successful user or client authentication, which can be a single, multiple or even a
multi factor authentication.
The following schemes are supported:
● LDAP/ADS
● RADIUS
● SAP SSO OTP
● ABAP RFC
● Kerberos/SPNego
● X.509 TLS Client Authentication
SLS lets you define arbitrary enrollment profiles, each with a unique profile UID in its URL, and with a
configurable authentication and certificate generation.
Back to Content [page 362]
362 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-362-320.jpg)
![Requirements
For user certification, SLS must provide a profile that adheres to the following:
● Cloud Connector client authentication by its X.509 service certificate
● Cloud Connector service certificate and SLS may live in different PKIs
● Cloud Connector hands over the full user´s certificate subject name
With SAP SSO 2.0 SP06, SLS provides the following required features:
● TLS Client Authentication-based enrollment with SecureLoginModuleUserDelegationWithSSL
(available since SP04)
● multi-PKI support is implemented by all standard components of Application Server (AS) JAVA, AS ABAP,
HANA, by importing trusted root CA certificates
● SLS allows PKCS10:SUBJECT in a profile´s certificate configuration (SP06)
Back to Content [page 362]
Implementation
INSTALLATION
Follow the standard installation procedures for SLS. This includes the initial setup of a PKI (public key
infrastructure).
Note
SLS allows you to set up one or more own PKIs with Root CA, User CA, and so on. You can also import CAs
as PKCS#12 file or use a hardware security module (HSM) as "External User CA".
Note
You should only use HTTPS connections for any communication with SLS. AS JAVA / ICM supports TLS,
and the default configuration comes with a self-signed sever certificate. You may use SLS to replace this
certificate by a PKI certificate.
CONFIGURATION
SSL Ports
1. Open the NetWeaver Administrator, choose Configuration SSL and define a new port with Client
Authentication Mode = REQUIRED.
Note
You may also define another port with Client Authentication Mode = Do not request if you
did not do so yet.
2. Import the root CA of the PKI that issued your Cloud Connector service certificate.
SAP BTP Connectivity
Connectivity PUBLIC 363](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-363-320.jpg)
![1. Open SLS Administration Console (SLAC, https:/
/host:port/slac).
2. Go to the top level menu and choose Certificate Management.
3. Select the Root CA certificate you are using in your profile.
4. Choose Export entry X.509 Certificate and download the certificate file.
Cloud Connector
Follow the standard installation procedure of the Cloud Connector and configure SLS support:
1. Enter the policy URL that points to the SLS user profile group.
2. Select the profile, for example, Cloud Connector User Certificates.
3. Import the Root CA certificate of SLS into the Cloud Connector´s Trust Store.
On-Premise Target Systems
Follow the standard configuration procedure for Cloud Connector support in the corresponding target system
and configure SLS support.
To do so, import the Root CA certificate of SLS into the system´s truststore:
● AS ABAP: choose transaction STRUST and follow the steps in Maintaining the SSL Server PSE's Certificate
List.
● AS Java: open the Netweaver Administrator and follow the steps described in Configuring the SSL Key Pair
and Trusted X.509 Certificates.
Back to Content [page 362]
1.2.2.3.1.6 Configure Kerberos
Context
The Cloud Connector allows you to propagate users authenticated in SAP BTP via Kerberos against backend
systems. It uses the Service For User and Constrained Delegation protocol extension of Kerberos.
Note
This feature is not supported for ABAP backend systems. In this case, you can use the certificate-based
principal propagation, see Configure a CA Certificate for Principal Propagation [page 344].
The Key Distribution Center (KDC) is used for exchanging messages in order to retrieve Kerberos tokens for a
certain user and backend system.
For more information, see Kerberos Protocol Extensions: Service for User and Constrained Delegation Protocol
.
SAP BTP Connectivity
Connectivity PUBLIC 365](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-365-320.jpg)
![Example
You have a backend system protected with SPNego authentication in your corporate network. You want to call
it from a cloud application while preserving the identity of a cloud-authenticated user.
Define the following:
● A connectivity destination in SAP BTP, with ProxyType = OnPremise.
● A system mapping made in the Cloud Connector. (Choose Cloud to On Premise from your subaccount
menu, Go to tab Access Control Add , and for Principal Type, select Kerberos.)
● Kerberos configuration in the Cloud Connector, where the service user is allowed to delegate calls for your
backend host service.
Result:
When you now call a backend system, the Cloud Connector obtains an SPNego token from your KDC for the
cloud-authenticated user. This token is sent along with the request to the back end, so that it can authenticate
the user and the identity to be preserved.
Related Information
Set Up Trust for Principal Propagation [page 341]
1.2.2.3.1.7 Configuring Principal Propagation to SAP
NetWeaver AS for Java
Find step-by-step instructions on how to set up an application server for Java (AS Java) to enable principal
propagation for HTTPS.
Prerequisites
To perform the following steps, you must have the corresponding administrator authorizations in AS Java (SAP
NetWeaver Administrator) as well as an administrator user for the Cloud Connector.
SAP BTP Connectivity
Connectivity PUBLIC 367](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-367-320.jpg)
![Configure AS Java to Trust the Cloud Connector's System
Certificate
Procedure
1. Go to SAP NetWeaver Administrator Certificates and Keys and import the Cloud Connector's system
certificate into the Trusted CAs keystore view. See Importing Certificate and Key From the File System.
2. Configure the Internet Communication Manager (ICM) to trust the system certificate for principal
propagation.
a. Add a new SSL access point. See Adding New SSL Access Points.
b. Generate a certificate signing request and send it to the CA of your choice. See Configuration of the AS
Java Keystore Views for SSL.
c. Import the certificates and save the configuration.
Import the certificate signing response, the root X.509 certificate of the trusted CA, and the Cloud
Connector's system certificate into the new SSL access point from step 2a. Save the configuration and
restart the ICM. See Configuring the SSL Key Pair and Trusted X.509 Certificates.
d. Test the SSL connection. See Testing the SSL Connection.
Define Rules for User Mapping
Procedure
1. Add the ClientCertLoginModule to the policy configuration that the Cloud Connector connects to. See
Configuring the Login Module on the AS Java.
2. Define the rules to map users authenticated with their certificate to users that exist in the User
Management Engine. See Using Rules for User Mapping in Client Certificate Login Module.
○ To map the user ID of the certificate’s subject name field to users, see Using Rules Based on Client
Certificate Subject Names.
○ To map the user ID based on rules for the certificate V3 extension SubjectAlternativeName, see Using
Rules Based on Client Certificate V3 Extensions.
○ To use client certificate filters, see Defining Rules for Filtering Client Certificates.
Related Information
Configuring Transport Layer Security on SAP NetWeaver AS for Java
Using X.509 Client Certificates
Configure Principal Propagation for HTTPS [page 347]
368 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-368-320.jpg)
![1.2.2.4 Configure Access Control
Specify the backend systems that can be accessed by your cloud applications.
To allow your cloud applications to access a certain backend system on the intranet, you must specify this
system in the Cloud Connector. The procedure is specific to the protocol that you are using for communication.
Find the detailed configuration steps for each communication protocol here:
Configure Access Control (HTTP) [page 370]
Configure Access Control (RFC) [page 377]
Configure Access Control (LDAP) [page 383]
Configure Access Control (TCP) [page 386]
Copy Access Control Settings
When you add new subaccounts, you can copy the complete access control settings from another subaccount
on the same Cloud Connector. You can also do it any time later by using the import/export mechanism
provided by the Cloud Connector.
Export Access Control Settings
1. From your subaccount menu, choose Cloud To On-Premise and select the tab Access Control.
2. To store the current settings in a ZIP file, choose Download icon in the upper-right corner.
3. You can later import this file into a different Cloud Connector.
Import Access Control Settings
There are two locations from which you can import access control settings:
● A file that was previously exported from a Cloud Connector
● A different subaccount on the same Cloud Connector
SAP BTP Connectivity
Connectivity PUBLIC 369](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-369-320.jpg)
![Two additional options define the behavior of the import:
● Overwrite: Select this checkbox if you want to replace existing system mappings with imported ones. Do
not select this checkbox if you want to keep existing mappings and only import the ones that are not yet
available (default).
Note
A system mapping is uniquely identified by the combination of virtual host and port.
● Include Resources: When this checkbox is selected (default), the resources that belong to an imported
system are also imported. Otherwise no resources are imported, that is, imported system mappings do not
expose any resources.
Related Information
Configure Access Control (HTTP) [page 370]
Configure Access Control (RFC) [page 377]
Configure Access Control (LDAP) [page 383]
Configure Access Control (TCP) [page 386]
Configure Accessible Resources [page 389]
Configure Domain Mappings for Cookies [page 493]
1.2.2.4.1 Configure Access Control (HTTP)
Specify the backend systems that can be accessed by your cloud applications using HTTP.
To allow your cloud applications to access a certain backend system on the intranet via HTTP, you must specify
this system in the Cloud Connector.
370 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-370-320.jpg)
![ Note
Make sure that also redirect locations are configured as internal hosts.
If the target server responds with a redirect HTTP status code (30x), the cloud-side HTTP client usually
sends the redirect over the Cloud Connector as well. The Cloud Connector runtime then performs a reverse
lookup to rewrite the location header that indicates where to route the redirected request.
If the redirect location is ambiguous (that is, several mappings point to the same internal host and port),
the first one found is used. If none is found, the location header stays untouched.
Tasks
Expose Intranet Systems [page 371]
Limit the Accessible Services for HTTP(S) [page 375]
Activate or Suspend Resources [page 376]
Expose Intranet Systems
Insert a new entry in the Cloud Connector access control management:
1. Choose Cloud To On Premise from your Subaccount menu.
2. Choose Add. A wizard will open and ask for the required values.
3. Backend Type: Select the description that matches best the addressed backend system.
When you are done, choose Next.
4. Protocol: This field allows you to decide whether the Cloud Connector should use HTTP or HTTPS for the
connection to the backend system. Note that this is completely independent from the setting on cloud
side. Thus, even if the HTTP destination on cloud side specifies "http://" in its URL, you can select
HTTPS. This way, you are ensured that the entire connection from the cloud application to the actual
backend system (provided through the SSL tunnel) is SSL-encrypted. The only prerequisite is that the
SAP BTP Connectivity
Connectivity PUBLIC 371](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-371-320.jpg)
![backend system supports HTTPS on that port. For more information, see Initial Configuration (HTTP)
[page 319].
○ If you specify HTTPS and there is a "system certificate" imported in the Cloud Connector, the latter
attempts to use that certificate for performing a client-certificate-based logon to the backend system.
○ If there is no system certificate imported, the Cloud Connector opens an HTTPS connection without
client certificate.
5. Internal Host and Internal Port specify the actual host and port under which the target system can be
reached within the intranet. It needs to be an existing network address that can be resolved on the intranet
and has network visibility for the Cloud Connector without any proxy. Cloud Connector will try to forward
the request to the network address specified by the internal host and port, so this address needs to be real.
6. Virtual Host specifies the host name exactly as it is specified as the URL property in the HTTP destination
configuration in SAP BTP
See:
Create HTTP Destinations [page 43] (Cloud Foundry environment)
The virtual host can be a fake name and does not need to exist. The Virtual Port allows you to distinguish
between different entry points of your backend system, for example, HTTP/80 and HTTPS/443, and have
different sets of access control settings for them. For example, some noncritical resources may be
accessed by HTTP, while some other critical resources are to be called using HTTPS only. The fields will be
prepopulated with the values of the Internal Host and Internal Port. In case you don't modify them, you
must provide your internal host and port also in the cloud-side destination configuration or in the URL used
for your favorite HTTP client.
372 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-372-320.jpg)
![7. Principal Type defines what kind of principal is used when configuring a destination on the cloud side using
this system mapping with authentication type Principal Propagation. Regardless of what you choose,
make sure that the general configuration for the principal type has been done to make it work correctly. For
destinations using different authentication types, this setting is ignored. If you choose None as principal
type, it is not possible to use principal propagation to this system.
Note
There are two variants of a principal type X.509 certificate: X.509 Certificate (General Usage)
and X.509 Certificate (Strict Usage). The latter was introduced with Cloud Connector 2.11. If
the cloud side sends a principal, these variants behave identically. If no principal is sent, the injected
HTTP headers indicate that the system certificate used for trust is not used for authentication.
The recommended variant is X.509 Certificate (Strict Usage) as this lets you use principal
propagation and basic authentication over the same access control entry, regardless of the logon order
settings in the target system.
For more information on principal propagation, see Configuring Principal Propagation [page 340].
8. Host In Request Header lets you define, which host is used in the host header that is sent to the target
server. By choosing Use Internal Host, the actual host name is used. When choosing Use Virtual
Host, the virtual host is used. In the first case, the virtual host is still sent via the X-Forwarded-Host
header.
SAP BTP Connectivity
Connectivity PUBLIC 373](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-373-320.jpg)
![cannot edit the virtual name of this system mapping. If you want to use a different fictional host name in
your cloud application, you must delete the mapping and create a new one.
Back to Tasks [page 371]
Limit the Accessible Services for HTTP(S)
In addition to allowing access to a particular host and port, you also must specify which URL paths (Resources)
are allowed to be invoked on that host. The Cloud Connector uses very strict allowlists for its access control.
Only those URLs for which you explicitly granted access are allowed. All other HTTP(S) requests are denied by
the Cloud Connector.
To define the permitted URLs for a particular backend system, choose the line corresponding to that backend
system and choose Add in section Resources Accessible On... below. A dialog appears prompting you to enter
the specific URL path that you want to allow to be invoked.
SAP BTP Connectivity
Connectivity PUBLIC 375](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-375-320.jpg)
![The Cloud Connector checks that the path part of the URL (up to but not including a possible question mark
(?) that may denote the start of optional CGI-style query parameters) is exactly as specified in the
configuration. If it is not, the request is denied. If you select option Path and all sub-paths, the Cloud Connector
allows all requests for which the URL path (not considering any query parameters) starts with the specified
string.
The Active checkbox lets you specify, if that resource is initially enabled or disabled. See the section below for
more information on enabled and disabled resources.
The WebSocket Upgrade checkbox lets you specify, whether that resource allows a protocol upgrade.
Back to Tasks [page 371]
Activate or Suspend Resources
In some cases, it is useful for testing purposes to temporarily disable certain resources without having to delete
them from the configuration. This allows you to easily reprovide access to these resources at a later point of
time without having to type in everything once again.
● To suspend a resource, select it and choose the Suspend button:
The status icon turns red, and from now on, the Cloud Connector will deny all requests coming in for this
resource.
● To activate the resource again, select it and choose the Activate button.
● By choosing Allow WebSocket upgrade/Disallow WebSocket upgrade this is possible for the protocol
upgrade setting as well.
● It is also possible to mark multiple lines and then suspend or activate all of them in one go by clicking the
Activate/Suspend icons in the top row. The same is true for the corresponding Allow WebSocket upgrade/
Disallow WebSocket icons.
Examples:
● /production/accounting and Path only (sub-paths are excluded) are selected. Only requests of the form
GET /production/accounting or GET /production/accounting?
name1=value1&name2=value2... are allowed. (GET can also be replaced by POST, PUT, DELETE, and so
on.)
● /production/accounting and Path and all sub-paths are selected. All requests of the form GET /
production/accounting-plus-some-more-stuff-here?name1=value1... are allowed.
● / and Path and all sub-paths are selected. All requests to this server are allowed.
Back to Tasks [page 371]
376 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-376-320.jpg)
![Related Information
Configure Domain Mappings for Cookies [page 493]
Consume Backend Systems (Java Web or Java EE 6 Web Profile)
1.2.2.4.2 Configure Access Control (RFC)
Specify the backend systems that can be accessed by your cloud applications using RFC.
Tasks
Expose Intranet Systems [page 377]
Limit the Accessible Resources for RFC [page 382]
Expose Intranet Systems
To allow your cloud applications to access a certain backend system on the intranet, insert a new entry in the
Cloud Connector Access Control management.
1. Choose Cloud To On-Premise from your Subaccount menu and go to tab Access Control.
2. Choose Add.
3. Backend Type: Select the backend system type ( ABAP System or SAP Gateway for RFC).
4. Choose Next.
5. Protocol: Choose RFC or RFC SNC for connecting to the backend system.
SAP BTP Connectivity
Connectivity PUBLIC 377](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-377-320.jpg)
![ Note
The value RFC SNC is independent from your settings on the cloud side, since it only specifies the
communication beween Cloud Connector and backend system. Using RFC SNC, you can ensure that
the entire connection from the cloud application to the actual backend system (provided by the SSL
tunnel) is secured, partly with SSL and partly with SNC. For more information, see Initial Configuration
(RFC) [page 321].
Note
○ The back end must be properly configured to support SNC connections.
○ SNC configuration must be provided in the Cloud Connector.
6. Choose Next.
7. Choose whether you want to configure a load balancing logon or connect to a specific application server.
8. Specify the parameters of the backend system. It needs to be an existing network address that can be
resolved on the intranet and has network visibility for the Cloud Connector. If this is only possible using a
valid SAProuter, specify the router in the respective field. The Cloud Connector will try to establish a
connection to this system, so the address has to be real.
○ When using a load-balancing configuration, the Message Server specifies the message server of the
ABAP system. The system ID is a three-char identifier that is also found in the SAP Logon
configuration. Alternatively, it's possible to directly specify the message server port in the System ID
field.
378 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-378-320.jpg)
![○ Virtual Application Server - it specifies the host name exactly as specified as the jco.client.ashost
property in the RFC destination configuration in the cloud. The Virtual Instance Number allows you to
distinguish between different entry points of your backend system that have different sets of access
control settings. The value needs to be the same like for the jco.client.sysnr property in the RFC
destination configuration in the cloud.
10. This step is only relevant if you have chosen RFC SNC. The <Principal Type> field defines what kind of
principal is used when configuring a destination on the cloud side using this system mapping with
authentication type Principal Propagation. No matter what you choose, make sure that the general
configuration for the <Principal Type> has been done to make it work correctly. For destinations using
different authentication types, this setting is ignored. In case you choose None as <Principal Type>, it
is not possible to apply principal propagation to this system.
Note
If you use an RFC connection, you cannot choose between different principal types. Only the X.509
certificate is supported. You need an SNC-enabled backend connection to use it. For RFC, the two X.
509 certificate variants X.509 certificate (general usage) and X.509 certificate (strict usage) do not
differ in behavior.
For more information on principal propagation, see Configuring Principal Propagation [page 340].
11. SNC Partner Name: This step will only come up if you have chosen RFC SNC. The SNC partner name needs
to contain the correct SNC identification of the target system.
380 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-380-320.jpg)
![15. Optional. You can later edit a system mapping to add more protection to your system when using RFC via
theCloud Connector, by restricting the mapping to specified clients and users: in column Actions, choose
the button Maintain Authority Lists (only RFC) to open an allowlist/blocklist dialog. In section Authority
Client Allowlist, enter all clients of the corresponding system in the field <Client ID> that you want to
allow to use the Cloud Connector connection. In section Authority User Blocklist, press the button Add a
user authority (+) to enter all users you want to exclude from this connection. Each user must be assigned
to a specified client. When you are done, press Save.
Note
This function applies for RFC/RFC SNC only.
Back to Tasks [page 377]
Limit the Accessible Resources for RFC
In addition to allowing access to a particular host and port, you also must specify which function modules
(Resources) are allowed to be invoked on that host. You can enter an optional description at this stage. The
382 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-382-320.jpg)
![Cloud Connector uses very strict allowlists for its access control. Besides internally used infrastructure
function modules, only function modules for which you explicitly granted access are allowed.
1. To define the permitted function modules for a particular backend system, choose the row corresponding
to that backend system and press Add in section Resources Accessible On... below. A dialog appears,
prompting you to enter the specific function module name whose invoking you want to allow.
2. The Cloud Connector checks that the function module name of an incoming request is exactly as specified
in the configuration. If it is not, the request is denied.
3. If you select the Prefix option, the Cloud Connector allows all incoming requests, for which the function
module name begins with the specified string.
4. The Active checkbox allows you to specify whether that resource should be initially enabled or disabled.
Back to Tasks [page 377]
1.2.2.4.3 Configure Access Control (LDAP)
Add a specified system mapping to the Cloud Connector if you want to use an on-premise LDAP server or user
authentication in your cloud application.
To allow your cloud applications to access an on-premise LDAP server, insert a new entry in the Cloud
Connector access control management.
1. Choose Cloud To On-Premise from your Subaccount menu.
2. Choose Add (+). A wizard opens and asks for the required values.
3. Backend Type: Select Non-SAP System from the drop down list. When you are done, choose Next.
SAP BTP Connectivity
Connectivity PUBLIC 383](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-383-320.jpg)
![trustworthy applications have access. The reason is that using plain TCP, the Cloud
Connector cannot see or log any detail information about the calls. Therefore, in contrast to HTTP or
RFC (both running on top of TCP), the Cloud Connector cannot check the validity of a request. To
minimize this risk, make sure you
○ deploy only trusted applications on SAP BTP.
○ configure an application allowlist in the Cloud Connector, see Set Up Trust for Principal
Propagation [page 341].
○ take the recommended security measures for your SAP BTP (sub)account. See section Security in
the SAP BTP documentation.
5. Internal Host and Port or Port Range: specify the host and port under which the target system can be
reached within the intranet. It needs to be an existing network address that can be resolved on the intranet
and has network visibility for the Cloud Connector. The Cloud Connector will try to forward the request to
the network address specified by the internal host and port. That is why this address needs to be real.
For TCP and TCP SSL, you can also specify a port range through its lower and upper limit, separated by a
hyphen.
6. Enter a Virtual Host and Virtual Port. The virtual host can be a fake name and does not need to exist. The
fields are prepopulated with the values of the Internal Host and Port or Port Range.
SAP BTP Connectivity
Connectivity PUBLIC 387](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-387-320.jpg)
![1.2.2.4.5 Configure Accessible Resources
Configure backend systems and resources in the Cloud Connector, to make them available for a cloud
application.
Tasks
Map Systems and Limit Access [page 389]
Use Scenarios for Resources [page 391]
Map Systems and Limit Access
Initially, after installing a new Cloud Connector, no network systems or resources are exposed to the cloud. You
must configure each system and resource used by applications of the connected cloud subaccount. To do this,
choose Cloud To On Premise from your subaccount menu and go to tab Access Control:
SAP BTP Connectivity
Connectivity PUBLIC 389](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-389-320.jpg)
![The Cloud Connector supports any type of system (SAP or non-SAP system) that can be called via one of the
supported protocols. For example, a convenient way to access an ABAP system from a cloud application is via
SAP NetWeaver Gateway, as it allows the consumption of ABAP content via HTTP and open standards.
● For systems using HTTP communication, see: Configure Access Control (HTTP) [page 370].
● For information on configuring RFC resources, see: Configure Access Control (RFC) [page 377].
We recommend that you limit the access to backend services and resources. Instead of configuring a system
and granting access to all its resources, grant access only to the resources needed by the cloud application. For
example, define access to an HTTP service by specifying the service URL root path and allowing access to all its
subpaths.
When configuring an on-premise system, you can define a virtual host and port for the specified system. The
virtual host name and port represent the fully qualified domain name of the related system in the cloud. We
recommend that you use the virtual host name/port mapping to prevent leaking information about a system's
physical machine name and port to the cloud.
390 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-390-320.jpg)
![Back to Tasks [page 389]
Use Scenarios for Resources
As of version 2.12, the Cloud Connector lets you define a set of resources as a scenario that you can export,
and import into another Cloud Connector.
SAP BTP Connectivity
Connectivity PUBLIC 391](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-391-320.jpg)
![Scenarios are useful if you provide an application to many consumers, which invokes a large number of
resources in an on-premise system. In this case, you must expose a system on your Cloud Connector that
covers all required resources, which increases the risk of incorrect configuration.
Define and Export a Scenario [page 392]
Import a Scenario [page 392]
Remove a Scenario [page 393]
Define and Export a Scenario
If you, as application owner, have implemented and tested a scenario, and configured a Cloud Connector
accordingly, you can define the scenario as follows:
1. Choose the Export Scenario button.
2. In the dialog, select the resources that belong to the scenario.
3. In the field <Scenario Name>, choose a descriptive name, under which the set of resources can be
identified in the consuming Cloud Connector.
4. Choose Export to store the scenario.
Note
For applications provided by SAP, default scenario definitions may be available. To verify this, check the
corresponding application documentation.
Back to Use Scenarios for Resources [page 391]
Back to Tasks [page 389]
Import a Scenario
392 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-392-320.jpg)
![As an administrator taking care for a scenario configuration in some other Cloud Connector, perform the
following steps:
1. Choose the Import Scenario button to add all required resources to the desired access control entry.
2. In the dialog, navigate to the folder of the archive that contains the scenario definition.
3. Choose Import. The resources of the scenario are merged with the existing set of resources which are
already available in the access control entry.
All resources belonging to a scenario get an additional scenario icon in their status. When hovering over it, the
assigned scenario(s) of this resource are listed.
Back to Use Scenarios for Resources [page 391]
Back to Tasks [page 389]
Remove a Scenario
To remove a scenario:
1. Choose the Remove Scenario button.
2. In the dialog, choose the scenario(s) you want to remove.
3. Choose Remove to remove all resources associated with the chosen entry from the access control entry.
Resources that existed before, or are assigned to another scenario as well, are not removed.
SAP BTP Connectivity
Connectivity PUBLIC 393](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-393-320.jpg)
![Back to Use Scenarios for Resources [page 391]
Back to Tasks [page 389]
1.2.2.5 Configuration REST APIs
You can use a set of APIs to perform the basic setup of the Cloud Connector.
Context
As of version 2.11, the Cloud Connector provides several REST APIs that let you configure a newly installed
Cloud Connector. The configuration options correspond to the following steps:
● Initial Configuration [page 312]
● Managing Subaccounts [page 328]
● Configure Access Control [page 369]
● Master and Shadow Administration [page 511]
All configuration APIs start with the following string: /api/v1/configuration.
Note
Use the same host and port for the REST APIs that you use to access the Cloud Connector.
394 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-394-320.jpg)
![alive, extract the CSRF token from the first response header, and include it in all request headers.
Otherwise, use Connection: close and always submit user and password through basic authentication.
An inactive session causes a timeout at some point, and will consequently be removed. A request using an
expired session receives a login page (Content-type: text/html). The status code of the response is 200
in this case. The only way to detect an expired session is to check the content type and status code. Content
type text/html in a connection with status code 200 indicates an expired session.
For security reasons, a session should be closed or invalidated once it is not needed anymore. You can achieve
this by including Connection: close in the header of the final call of the relevant session. As a result, the
Cloud Connector invalidates the session. Subsequent attempts to send a request in the context of that session
will respond with a login page as described above.
User Roles
As of Cloud Connector 2.12, the REST API supports different user roles. Depending on the role, an API grants or
denies access. In default configuration, the Cloud Connector uses local user storage and supports the single
user Administrator (administrator role). Using LDAP user storage, you can use various users (see also
Configure Named Cloud Connector Users [page 502]):
Role Technical Role Name Authorization
Administrator admin or sccadmin All CRUD operations.
Support sccsupport Edit log and trace configuration.
Display sccdisplay Read configuration.
Monitoring sccmonitoring Read monitoring information.
Return Codes
Successful requests return the code 200, or, if there is no content, 204. POST actions that create new entities
return 201, with the location link in the header.
The following general errors can be returned by each API:
400 – invalid request. For example, if parameters are invalid or the API is not supported anymore, an
unexpected state occurs and in case of other non-critical errors.
401 – authorization required.
403 – the current Cloud Connector instance does not allow changes. For example, the instance has been
assigned to the shadow role and therefore does not allow configuration changes, or the user role does not have
required permission.
405 – an entity does not support the requested operation.
396 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-396-320.jpg)
![409 – current state of the Cloud Connector does not allow changes. For example, the password has to be
changed first.
415 – unexpected mime type.
500 – operation failed.
The status line provides details explaining the reason.
Most APIs may also return specific error details, depending on the situation. Such errors are mentioned in the
corresponding API description.
Note
The error texts depend on the request locale.
Hypertext Application Language
Entities returned by the APIs contain links as suggested by the current draft JSON Hypertext Application
Language (see https:/
/tools.ietf.org/html/draft-kelly-json-hal-08 ).
Available APIs
API Name Use
Common Description [page 399] ● Read common description
● Edit common description
High Availability Settings [page 400] ● Get high availaility settings
● Set high availaility settings
Proxy Settings [page 411] ● Get proxy settings
● Set proxy settings
● Remove proxy settings
Authentication and UI Settings [page 414] ● Read authentication settings
● Edit authentication settings
● Edit LDAP authentication settings
SAP BTP Connectivity
Connectivity PUBLIC 397](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-397-320.jpg)
![API Name Use
Certificate Management for Backend Communication [page
422]
● Get description for CA certificate for principal propaga
tion
● Get binary content of CA certificate for principal propa
gation
● Create a self-signed CA certificate for principal propaga
tion
● Create a certificate signing request for CA certificate for
principal propagation
● Upload a signed certificate chain as CA certificate for
principal propagation
● Upload a PKCS#12 certificate as CA certificate for prin
cipal propagation
● Delete CA certificate for principal propagation
● Get description for system certificate
● Get binary content of system certificate
● Create a self-signed system certificate
● Create a certificate signing request for a system certifi-
cate
● Upload a signed certificate chain as system certificate
● Upload a PKCS#12 certificate as system certificate
● Delete system certificate
Solution Management Configuration [page 435] ● Get solution management configuration
● Set solution management configuration and turn on re
porting
● Turn off reporting
● Download current LMDB XML report
Backup [page 437] ● Create backup configuration
● Restore backup configuration
Subaccount [page 439] ● Get list of subaccounts
● Create subaccount
● Delete subaccount
● Edit subaccount
● Connect or disconnect subaccount
● Extend validity of subaccount
● Create or change recovery subaccount
● Delete recovery subaccount
● Extend validity of recovery subaccount
● Get subaccount configuration
System Mappings [page 448] ● Get system mappings
● Create system mapping
● Delete system mapping
● Delete all system mappings
● Edit system mapping
398 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-398-320.jpg)
![API Name Use
System Mapping Resources [page 453] ● Get system mapping resources
● Get system mapping resource
● Create system mapping resource
● Edit system mapping resource
● Delete system mapping resource
● Delete all system mapping resources
Domain Mappings [page 457] ● List domain mappings
● Create domain mappings
● Delete domain mappings
● Edit domain mappings
Subaccount Service Channels [page 460] ● Get service channels
● Create service channel
● Delete service channel
● Edit service channel
● Enable or disable service channel
Related Information
Examples [page 463]
1.2.2.5.1 Common Description
Read and edit the Cloud Connector's common description via API.
Read Common Description
URI /api/v1/configuration/connector
Method GET
Request
Response {role: <current high availability
role>, description: <description of
Cloud Connector instance>}
SAP BTP Connectivity
Connectivity PUBLIC 399](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-399-320.jpg)
![Errors
Roles Administrator, Display, Support
Edit Common Description
URI /api/v1/configuration/connector
Method PUT
Request {description}
Response {role: <current high availability
role>, description: <description of
Cloud Connector instance>}
Errors INVALID_REQUEST
Roles Administrator
● Request Properties:
description: a string; use an empty string to remove the description.
● Errors:
INVALID_REQUEST: if the value of description is not a JSON string.
Note
null is not a JSON string.
1.2.2.5.2 High Availability Settings
Read and edit the high availability settings of a Cloud Connector instance via API.
When installing a Cloud Connector instance, you usually define its high availability role (master or shadow
instance) during initial configuration, see Change your Password and Choose Installation Type [page 314].
If the high availability role was not defined before, you can set the master or shadow role via this API.
If a shadow instance is connected to the master, this API also lets you switch the roles: the master instance
requests the shadow instance to take over the master role, and then takes the shadow role itself.
400 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-400-320.jpg)
![Request "master" or "shadow"
Response
Errors ILLEGAL_STATE, INVALID_REQUEST
Roles Administrator
Errors:
● INVALID_REQUEST (400): If a high-availability role other than "master" or "shadow" is supplied.
● ILLEGAL_STATE (409): If changing the high-availability role is not possible; changing the role is only
possible if no role has been assigned, or if the current role is master and a shadow system is connected.
Example
curl -i -k -H 'Content-Type: application/json' -d '"shadow"' -u
Administrator:<password> -X POST https://localhost:8443/api/v1/configuration/
connector/haRole
Related Information
Master Instance Configuration [page 402]
Shadow Instance Configuration [page 406]
1.2.2.5.2.1 Master Instance Configuration
Read and edit the high availability settings for a Cloud Connector master instance via API.
Note
The APIs below are available as of Cloud Connector version 2.13.0.
Restriction
These APIs are only permitted on a Cloud Connector master instance. The shadow instance rejects the
requests with error code 400 – Invalid Request.
402 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-402-320.jpg)
![● INVALID_CONFIGURATION (409): LDAP server is not accessible (does not respond).
Note
In both error cases nothing is stored, and LDAP authentication is disabled.
Example
curl -i -k -H 'Content-Type: application/json' -u Administrator:<password> -X
PUT https://localhost:8443/api/v1/configuration/connector/authentication/ldap -d
'{"enable":true, "configuration":{"hosts":[{"host":"ldaphost", "port":"10389",
"isSecure":false}], "config":"roleBase="ou=groups,dc=scc" roleName="cn"
roleSearch="(uniqueMember={0})" userBase="ou=users,dc=scc" userSearch=
"(uid={0})"", "user":"ldapadmin", "password":"<ldapadminpassword>"}}'
Get Description for UI Certificate
This API returns a textual description for the system certificate.
Note
Available as of version 2.13.0.
URI /api/v1/configuration/connector/ui/
uiCertificate
Method GET
Response {subjectDN, issuer,
notBeforeTimeStamp,
notAfterTimeStamp, subjectAltNames}
Errors
Roles Administrator, Display, Support
Response Properties:
● subjectDN: The subject distinguished name (a string)
● issuer: The issuer (a string)
● notBeforeTimeStamp: Timestamp of the beginning of the validity period (a UTC long number)
● notAfterTimeStamp: Timestamp of the end of the validity period (a UTC long number)
SAP BTP Connectivity
Connectivity PUBLIC 417](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-417-320.jpg)
![Example
curl -i -k -u <user>:<password> https://<host>:<port>/api/v1/configuration/
connector/ui/uiCertificate -X PUT -F 'password=<p12Password>' -F
pkcs12=@<p12file>
Example
For test purposes, you can create an own self-signed pkcs#12 certificate with keytool.
keytool -genkeypair -alias key -keyalg RSA -keysize 2048 -validity 365 -keypass
test20 -keystore test.p12 -storepass test20 -storetype PKCS12 -dname 'CN=test'
1.2.2.5.5 Certificate Management for Backend
Communication
Manage a CA certificate for principal propagation or a system certificate via API.
Note
The APIs below are available as of Cloud Connector version 2.13.
There are two similar sets of APIs for system certificate and CA certificate for principal propagation.
Note
Some of the APIs list a parameter subjectAltNames (subject alternative names or SAN) for the request or
response object. This parameter is an array of objects with the following properties:
● type: one of the strings DNS, URI, IP, or RFC822.
● value: the value associated with the chosen type.
● CA Certificate for Principal Propagation: APIs [page 422]
● System Certificate: APIs [page 428]
1.2.2.5.5.1 CA Certificate for Principal Propagation: APIs
Manage a CA certificate for principal propagation via API.
422 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-422-320.jpg)
![ Note
The APIs below are available as of Cloud Connector version 2.13.0.
Get Description for a CA Certificate for Principal Propagation
URI /api/v1/configuration/connector/
onPremise/ppCaCertificate
Method GET
Header Accept: application/json
Response {subjectDN, issuer,
notBeforeTimeStamp,
notAfterTimeStamp, subjectAltNames}
Errors NOT_FOUND
Roles Administrator, Display, Support
Response Properties:
● subjectDN: the subject distinguished name (a string)
● issuer: the issuer (a string)
● notBeforeTimeStamp: timestamp of the beginning of the validity period (a UTC long number)
● notAfterTimeStamp: timestamp of the end of the validity period (a UTC long number)
● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication
[page 422] for details).
Errors:
● NOT_FOUND (404): there is no CA certificate for principal propagation.
Note
subjectAltNames is not present if there are no subject alternative names.
Example
curl -i -k -H "Accept: application/json" -u <user>:<password> -X GET https://
<host>:<port>/api/v1/configuration/connector/onPremise/ppCaCertificate
SAP BTP Connectivity
Connectivity PUBLIC 423](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-423-320.jpg)
![Method POST
Request {type, subjectDN, subjectAltNames}
Response 201 on success
Errors
Roles Administrator
Request Properties:
● type: the string selfsigned
● subjectDN: the subject distinguished name (a string)
● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication
[page 422] for details). This property is optional.
The certificate created this way has a validity of 1 year.
Example
curl -i -k -H "Accept: application/json" -H "Content-Type: application/json" -u
<user>:<password> -X POST --data '{"type":"selfsigned", "subjectDN":"CN=me"}'
https://<host>:<port>/api/v1/configuration/connector/onPremise/ppCaCertificate
Create a Certificate Signing Request for a CA Certificate for Principal
Propagation (Master Only)
URI /api/v1/configuration/connector/
onPremise/ppCaCertificate
Method POST
Request {type, subjectDN, subjectAltNames}
Response PEM-encoded certificate request
Errors
Roles Administrator
SAP BTP Connectivity
Connectivity PUBLIC 425](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-425-320.jpg)
![Request Properties:
● type: the string selfsigned
● subjectDN: the subject distinguished name (a string)
● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication
[page 422] for details). This property is optional.
Example
curl -k -u <user>:<password> -X POST -H "Content-Type: application/json" --data
'{"type":"csr", "subjectDN":"CN=me"}'
https://<host>:<port>/api/v1/configuration/connector/onPremise/ppCaCertificate -
o csr.pem
Upload a Signed Certificate Chain as CA Certificate for Principal Propagation
(Master Only)
URI /api/v1/configuration/connector/
onPremise/ppCaCertificate
Method PATCH
Request multipart/form-data with the following parameter:
signedCertificate.
Response 201 on success
Errors INVALID_REQUEST
Roles Administrator
Request Properties:
● signedCertificate: the signed certificate and CA certificate chain (PEM-encoded)
Errors:
● INVALID_REQUEST (400): the certificate chain provided does not match the most recent certificate
request, or it is not a certificate chain in the correct format (PEM-encoded).
426 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-426-320.jpg)
![ Note
The APIs below are available as of Cloud Connector version 2.13.0.
Get Description for a System Certificate
URI /api/v1/configuration/connector/
onPremise/systemCertificate
Method GET
Header Accept: application/json
Response {subjectDN, issuer,
notBeforeTimeStamp,
notAfterTimeStamp, subjectAltNames}
Errors NOT_FOUND
Roles Administrator, Display, Support
Response Properties:
● subjectDN: the subject distinguished name (a string)
● issuer: the issuer (a string)
● notBeforeTimeStamp: timestamp of the beginning of the validity period (a UTC long number)
● notAfterTimeStamp: timestamp of the end of the validity period (a UTC long number)
● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication
[page 422] for details).
Errors:
● NOT_FOUND (404): there is no system certificate.
Note
subjectAltNames is not present if there are no subject alternative names.
Example
curl -i -k -H "Accept: application/json" -u <user>:<password> -X GET https://
<host>:<port>/api/v1/configuration/connector/onPremise/systemCertificate
SAP BTP Connectivity
Connectivity PUBLIC 429](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-429-320.jpg)
![Request {type, subjectDN, subjectAltNames}
Response 201 on success
Errors
Roles Administrator
Request Properties:
● type: the string selfsigned
● subjectDN: the subject distinguished name (a string)
● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication
[page 422] for details). This property is optional.
The certificate created this way has a validity of 1 year.
Example
curl -i -k -H "Accept: application/json" -H "Content-Type: application/json" -u
<user>:<password> -X POST --data '{"type":"selfsigned", "subjectDN":"CN=me"}'
https://<host>:<port>/api/v1/configuration/connector/onPremise/systemCertificate
Create a Certificate Signing Request for a System Certificate (Master Only)
URI /api/v1/configuration/connector/
onPremise/systemCertificate
Method POST
Header CONTENT_TYPE: application/json
Request {type, subjectDN, subjectAltNames}
Response PEM-encoded certificate request
Errors
Roles Administrator
Request Properties:
● type: the string selfsigned
SAP BTP Connectivity
Connectivity PUBLIC 431](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-431-320.jpg)
![● subjectDN: the subject distinguished name (a string)
● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication
[page 422] for details). This property is optional.
Example
curl -k -u <user>:<password> -X POST -H "Content-Type: application/json" --data
'{"type":"csr", "subjectDN":"CN=me"}'
https://<host>:<port>/api/v1/configuration/connector/onPremise/
systemCertificate -o csr.pem
Upload a Signed Certificate Chain as System Certificate (Master Only)
URI /api/v1/configuration/connector/
onPremise/systemCertificate
Method PATCH
Request multipart/form-data with the following parameter:
signedCertificate.
Response 201 on success
Errors INVALID_REQUEST
Roles Administrator
Request Properties:
● signedCertificate: the signed certificate and CA certificate chain (PEM-encoded)
Errors:
● INVALID_REQUEST (400): the certificate chain provided does not match the most recent certificate
request, or it is not a certificate chain in the correct format (PEM-encoded).
Example
curl -i -k -u <user>:<password> -X PATCH -F signedCertificate=@<signedchain.pem>
https://<host>:<port>/api/v1/configuration/connector/onPremise/systemCertificate
432 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-432-320.jpg)
![1.2.2.5.8 Subaccount
Manage the Cloud Connector's subaccount settings via API.
Operations
Subaccount Get Subaccounts [page 439]
Create Subaccount (Master Only) [page 440]
Delete Subaccount (Master Only) [page 441]
Edit Subaccount (Master Only) [page 441]
Connect/Disconnect Subaccount (Master Only) [page 442]
Refresh Subaccount Certificate (Master Only) [page 443]
Get Subaccount Configuration [page 444]
Recovery Subaccount Create Recovery Subaccount (Master Only) [page 444]
Delete Recovery Subaccount (Master Only) [page 445]
Refresh Certificate of Recovery Subaccount (Master Only)
[page 446]
Activate/Deactivate Recovery Subaccount (Master Only)
[page 447]
Takeover (Master Only) [page 447]
Get Subaccounts
URI /api/v1/configuration/subaccounts
Method GET
Request
Response [{regionHost, subaccount, locationID}]
Errors
Roles Administrator, Display, Support
SAP BTP Connectivity
Connectivity PUBLIC 439](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-439-320.jpg)
![Response:
An array of objects with the following properties:
● regionHost: region hosts (a string).
● subaccount: subaccount name (a string).
● locationID: location identifier for the Cloud Connector instance (a string); this property is not available if
the default location ID is in use.
Back to Operations [page 439]
Create Subaccount (Master Only)
Creates and connects a subaccount.
URI /api/v1/configuration/subaccounts
Method POST
Request {regionHost, subaccount, cloudUser,
cloudPassword, locationID,
displayName, description}
Response 201, created subaccount entity:
{regionHost, subaccount, locationID,
displayName, description, tunnel}
Errors INVALID_REQUEST, INVALID_CONFIGURATION
Roles Administrator
Request Properties:
● regionHost: region host name (a string).
● subaccount: subaccount technical name (a string).
● cloudUser: user for the specified subaccount and region host.
● cloudPassword: password for the cloud user.
● locationID: location identifier for the Cloud Connector instance (a string; optional).
● displayName: display name of the subaccount (a string; optional).
● description: subaccount description (a string; optional).
Response Properties:
● regionHost: region host name (a string).
● subaccount: subaccount technical name (a string).
● locationID: location ID (a string); this property is not available if the default location ID is in use.
440 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-440-320.jpg)
![● displayName: display name of the subaccount (a string); this property is not available if there is no
specified display name.
● description: subaccount description (a string); this property is not available if there is no description.
● tunnel: object outlining the current state of the tunnel.
Errors:
● INVALID_REQUEST (400): one or more mandatory parameters are missing or invalid.
● INVALID_CONFIGURATION (409): the subaccount already exists as a regular subaccount or recovery
subaccount.
Back to Operations [page 439]
Delete Subaccount (Master Only)
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>
Method DELETE
Request
Response 204 on success
Errors NOT_FOUND, ILLEGAL_STATE
Roles Administrator
Errors:
● NOT_FOUND (404): subaccount does not exist (in the specified region).
● ILLEGAL_STATE (409): there is at least one session that has access to the subaccount.
Back to Operations [page 439]
Edit Subaccount (Master Only)
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>
Method PUT
SAP BTP Connectivity
Connectivity PUBLIC 441](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-441-320.jpg)
![Request {locationID, displayName, description}
Response {regionHost, subaccount, locationID,
displayName, description, tunnel,
recoveryAccountState}
Errors NOT_FOUND
Roles Administrator
Request Properties:
● locationID: location identifier for the Cloud Connector instance (a string; optional); if this parameter is
not supplied the location ID will not change. Revert to the default location ID by supplying the empty string.
● displayName: subaccount display name (a string; optional); if this parameter is not supplied the display
name will not change. Clear the display name by using an empty string.
● description: subaccount description (a string; optional); if this parameter is not supplied the description
will not change. Clear the description by using an empty string.
Response Properties:
● regionHost: region host name (a string).
● subaccount: subaccount technical name (a string).
● locationID: location identifier for the Cloud Connector instance (a string); this property is not available if
the default location ID is in use.
● displayName: display name of the subaccount (a string); this property is not available if there is no
specified display name.
● description: subaccount description (a string); this property is not available if there is no description.
● tunnel: object outlining the current state of the tunnel.
● recoveryAccountState: object detailing the current state of the recovery subaccount. This property is
supplied only if a recovery subaccount is configured.
Errors
● NOT_FOUND (404): subaccount does not exist (in the specified region).
Back to Operations [page 439]
Connect/Disconnect Subaccount (Master Only)
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/state
442 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-442-320.jpg)
![Method PUT
Request {connected}
Response 204 on success
Errors
Roles Administrator
Request Properties:
● connected: a Boolean value indicating whether the subaccount should be connected (true) or
disconnected (false).
Back to Operations [page 439]
Refresh Subaccount Certificate (Master Only)
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/validity
Method POST
Request {user, password}
Response {regionHost, subaccount, locationID,
displayName, description, tunnel,
recoveryAccountState}
Errors
Roles Administrator
Request Properties:
● user: user for the specified region host and subaccount.
● password: password for the (cloud) user.
Response Properties:
● regionHost: region host name (a string).
● subaccount: subaccount technical name (a string).
● locationID: location identifier for the Cloud Connector instance (a string); this property is not available if
the default location ID is in use.
SAP BTP Connectivity
Connectivity PUBLIC 443](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-443-320.jpg)
![● displayName: display name of the subaccount (a string); this property is not available if there is no
specified display name.
● description: subaccount description (a string); this property is not available if there is no description.
● tunnel: object outlining the current state of the tunnel.
● recoveryAccountState: object detailing the current state of the recovery subaccount. This property is
supplied only if a recovery subaccount is configured.
Back to Operations [page 439]
Get Subaccount Configuration
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>
Method GET
Request
Response {regionHost, subaccount, locationID,
displayName, description, tunnel:
{state, connections,
applicationConnections:[],
serviceChannels:[]}}
Errors
Roles Administrator, Display, Support
Response Properties:
● regionHost: region host name (a string).
● subaccount: subaccount technical name (a string).
● locationID: location ID (a string); this property is not available if the default location ID is in use.
● displayName: display name of the subaccount (a string); this property is not available if there is no
specified display name.
● description: description (a string); this property is not available if there is no description.
● tunnel: object outlining the current state of the tunnel.
Back to Operations [page 439]
Create Recovery Subaccount (Master Only)
444 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-444-320.jpg)
![URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/recovery
Method POST
Request {regionHost, cloudUser, cloudPassword}
Response 201 on success
Errors INVALID_REQUEST, ILLEGAL_STATE
Roles Administrator
Request Properties:
● regionHost: region host of the recovery subaccount.
● cloudUser: user for the specified region host and recovery subaccount.
● cloudPassword: password for the cloud user.
Errors:
● INVALID_REQUEST (400): invalid or missing request parameters.
● ILLEGAL_STATE (409): a recovery subaccount already exists.
Note
A recovery subaccount cannot be changed. Delete it and create a new one instead.
Back to Operations [page 439]
Delete Recovery Subaccount (Master Only)
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/recovery
Method DELETE
Request
Response
Errors NOT_FOUND
Roles Administrator
SAP BTP Connectivity
Connectivity PUBLIC 445](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-445-320.jpg)
![Errors:
● NOT_FOUND (404): there is no recovery subaccount.
Back to Operations [page 439]
Refresh Certificate of Recovery Subaccount (Master Only)
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/recovery/
validity
Method POST
Request {user, password}
Response {regionHost, subaccount, locationID,
displayName, description, tunnel,
recoveryAccountState}
Errors INVALID_REQUEST, NOT_FOUND
Roles Administrator
Request Properties:
● user: user for the specified region host and subaccount.
● password: password for the (cloud) user.
Response Properties:
● regionHost: region host name (a string).
● subaccount: subaccount technical name (a string).
● locationID: location identifier for the Cloud Connector instance (a string); this property is not available if
the default location ID is in use.
● displayName: display name of the subaccount (a string); this property is not available if there is no
specified display name.
● description: subaccount description (a string); this property is not available if there is no description.
● tunnel: object outlining the current state of the tunnel.
● recoveryAccountState: object detailing the current state of the recovery subaccount. This property is
supplied only if a recovery subaccount is configured.
Errors
● INVALID_REQUEST (400): user or password are missing.
446 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-446-320.jpg)
![● NOT_FOUND (404): there is no recovery subaccount.
Back to Operations [page 439]
Activate/Deactivate Recovery Subaccount (Master Only)
Note
Available as of Cloud Connector 2.13.1.
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/recovery/state
Method PUT
Request {active}
Response 204 on success
Errors NOT_FOUND
Roles Administrator
Request Properties:
● active: Boolean value indicating whether the recovery subaccount should be active (true) or inactive
(false).
Errors:
● NOT_FOUND (404): there is no recovery subaccount.
Back to Operations [page 439]
Takeover (Master Only)
Caution
When performing this operation, the recovery subaccount permanently takes over from the original
subaccount, and the original subaccount is deleted. The recovery subaccount must be active for takeover to
succeed, see Activate/Deactivate Recovery Subaccount (Master Only) [page 447].
SAP BTP Connectivity
Connectivity PUBLIC 447](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-447-320.jpg)
![ Note
Available as of Cloud Connector 2.13.1.
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/recovery/
takeover
Method POST
Request
Response 204 on success
Errors NOT_FOUND, ILLEGAL_STATE
Roles Administrator
Errors:
● NOT_FOUND (404): there is no recovery subaccount.
● ILLEGAL_STATE (409): recovery subaccount is not active.
Back to Operations [page 439]
1.2.2.5.9 System Mappings
Manage the Cloud Connector's system mappings via API.
Get All System Mappings
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/systemMappings
Method GET
Request
448 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-448-320.jpg)
![Response [{virtualHost, virtualPort,
localHost, localPort, protocol,
backendType, authenticationMode,
hostInHeader, description, ...}]
Errors
Roles Administrator, Display, Support
Response:
An array of objects with the following properties:
● virtualHost: Virtual host used on the cloud side (a string)
● virtualPort: Virtual port used on the cloud side (a string)
● localHost: Host on the on-premise side (a string)
● localPort: Port on the on-premise side (a string)
● protocol: Protocol used when sending requests and receiving responses (a string)
● backendType: Type of the backend (a string)
● authenticationMode: Authentication mode used on the backend side (a string).
● hostInHeader: Policy for setting the host in the response header. Available for HTTP(S) protocols only.
● totalResourcesCount: the total number of resources
● enabledResourcesCount: the number of enabled resources
● description: Description for the system mapping (a string).
● sncPartnerName: SNC name of an ABAP Server, required for RFCS communication only.
● sapRouter: SAP router route, required only if an SAP router is used.
● allowedClients: Array of strings, describing the SAP clients allowing to execute the calls in this system.
Valid clients are 3 letters long. If no clients are defined here, there is no restriction – every client is allowed.
Only applicable for RFC-based communication.
● blacklistedClientUsers: Array of {client, user}, describing users that are not allowed to execute
the call, even if the client is listed under allowed clients. Only applicable for RFC-based communication.
Get System Mapping
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/
systemMappings/
<virtualHost>:<virtualPort>
Method GET
Request
SAP BTP Connectivity
Connectivity PUBLIC 449](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-449-320.jpg)
![URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/
systemMappings/virtualHost:virtualPort/
resources
Method GET
Request
Response [{id, enabled, exactMatchOnly,
websocketUpgradeAllowed, description}]
Errors
Roles Administrator, Display, Support
Response:
An array of objects, each representing a resource through the following properties:
● id: The resource itself, which, depending on the owning system mapping, is either a URL path (or the
leading section of it), or a RFC function name (prefix)
● enabled: Boolean flag indicating whether the resource is enabled.
● exactMatchOnly: Boolean flag determining whether access is granted only if the requested resource is an
exact match.
● websocketUpgradeAllowed: Boolean flag indicating whether websocket upgrade is allowed; this
property is of relevance only if the owning system mapping employs protocol HTTP or HTTPS.
● description: Description (a string); this property is not available unless explicitly set.
Get System Mapping Resource
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/
systemMappings/virtualHost:virtualPort/
resources/<encodedResourceId>
Method GET
Request
Response {id, enabled, exactMatchOnly,
websocketUpgradeAllowed, description}
Errors
454 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-454-320.jpg)
![Get Domain Mappings
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/domainMappings
Method GET
Request
Response [{virtualDomain, internalDomai}]
Errors
Roles Administrator, Display, Support
Response:
An array of objects, each representing a domain mapping through the following properties:
● virtualDomain: Domain used on the cloud side
● internalDomain: Domain used on the on-premise side
Create Domain Mappings (Master Only)
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/domainMappings
Method POST
Request {virtualDomain, internalDomain}
Response 201
Errors
Roles Administrator
Edit Domain Mappings (Master Only)
458 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-458-320.jpg)
![Delete All Domain Mappings (Master Only)
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/domainMappings
Method DELETE
Request
Response 204 on success
Errors
Roles Administrator
1.2.2.5.12 Subaccount Service Channels
Manage Cloud Connector service channels via API.
Get Service Channels
URI /api/v1/configuration/subaccounts/
<regionHost>/<subaccount>/channels
Method GET
Request
Response [{typeDesc, details, port, enabled,
connected, connectionsCount,
availableConnectionsCount,
connectedSinceTimeStamp}]
Errors
Roles Administrator, Display, Support
Response:
An array of objects, each of which represents a service channel through the following properties:
● typeDesc: an object specifying the service channel type through the properties typeKey and typeName.
● details
460 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-460-320.jpg)
![Request {enabled:boolean}
Response
Errors 400 - if account or service channel Id are invalid:
{type: "INVALID_REQUEST", message:
<msg>}
500
{type:"RUNTIME_FAILURE","message":"Ser
vice channel could not be opened"}
Roles Administrator
1.2.2.5.13 Examples
Find examples on how to use the Cloud Connector's configuration REST APIs.
Concept
The sample code in this section (download zip file) demonstrates how to use the REST APIs provided by Cloud
Connector to perform various configuration tasks.
Starting with a freshly installed Cloud Connector, the samples include initial configuration of the Cloud
Connector instance, connectivity setup, high availability configuration, and common tasks like backup/restore
operations, as well as integration with solution management.
The examples are implemented in Kotlin, a simple Java VM-based language. However, even if you are using a
different language, they still show the basic use of the APIs and their parameters for specific configuration
purposes.
If you are not familiar with Kotlin, find a brief introduction and some typical statements below.
REST API Parameters [page 464]
REST API Invocation [page 464]
How To Use the Examples [page 465]
SAP BTP Connectivity
Connectivity PUBLIC 463](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-463-320.jpg)
![REST API Parameters
In almost all requests and responses, structures are encoded in JSON format. To describe the parameter
details, we use Kotlin data classes.
This class represents a structure that you can use as value in a request or response:
data class OnlyPropertiesNamesAreRelevant(
val user: String,
val password: String
)
The JSON representation for that class is
{"user":<userValue>, "password":<passwordValue>}
Encoded in Kotlin this string looks like
"""{"user":"$userValue", "password":"$passwordValue"}"""
or as an object:
val credentials = OnlyPropertiesNamesAreRelevant(userValue, passwordValue)
Back to Concept [page 463]
REST API Invocation
(a) Fuel.put(url)
(b) .header("Connection", "close")
(c) .authentication().basic(user, password)
(d) .jsonBody(credentials)
(e) .responseObject<OnlyPropertiesNamesAreRelevant> { _, _, result ->
when (result) {
(f) is Result.Failure -> processRequestError(result.error)
is Result.Success -> println("returned: ${result.get()}")
}
}
.join()
● (a) - Fuel is an HTTP framework used in the examples. Important is the verb after Fuel - it is the REST API
method.
● (b) - Adds a request header Connection: close, which forces a connection close after request. In the
examples, this header is defined on FuelManager for all calls.
● (c) - Basic authentication is used for the call with user and password.
464 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-464-320.jpg)
![● (d) - HTTP requests with parameters require mostly JSON. The jsonBody-method adds the header
Content-Type: application/json and serializes the provided object credentials to JSON. Requests
without body like DELETE or GET omit body methods.
● (e) - The responseObject<ClassType>-method adds the header Accept: application/json and
de-serializes the response to the specified class type. Some APIs do not have any response or non-JSON
response. In such cases, the method response is used instead of responseObject<ClassType>.
● (f) - The way, how Kotlin decides between success (2xx) and failed responses. For details on the possible
response status, see Configuration REST APIs [page 394].
Back to Concept [page 463]
How To Use the Examples
Some common details, used by different examples, were extracted to the scenario.json configuration file.
This lets you use meaningful names like config.master!!.user in the examples. The file is loaded by
val config = loadScenarioConfiguration()
Each example also invokes
disableTrustChecks()
This method disables all SSL-related checks.
Caution
disableTrustChecks() is only used for test purposes. Do not use it in a productive environment.
Both methods, as well as some common REST API parameter structures (data classes) are defined in the file
Scenario Configuration [page 467]. This is the only help class under sources/.
When using the examples, start with Initial Configuration [page 468].
Prerequisite is a freshly installed Cloud Connector.
After a mandatory password change and defining the high availability role of the Cloud Connector instance
(master or shadow), the example demonstrates how to provide a description for the instance and how to set up
the UI and system certificates.
Once the initial configuration is done, you can optionally proceed with these steps:
● Connect to your subaccount on BTP (Subaccount Configuration [page 470])
● Create or restore a configuration backup (Backup And Restore Configuration [page 477])
● Configure and connect high availability instances (High Availability Settings [page 475])
● Integrate the Cloud Connector with the solution management infrastructure (Solution Management
Integration [page 478])
SAP BTP Connectivity
Connectivity PUBLIC 465](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-465-320.jpg)
![Back to Concept [page 463]
Related Information
scenario.json [page 466]
Source Files [page 466]
1.2.2.5.13.1 scenario.json
Sample Code
{
"subaccount": {
"regionHost": "cf.eu10.hana.ondemand.com",
"subaccount": "11aabbcc-7821-448b-9ecf-a7d986effa7c",
"user": "xxx",
"password": "xxx"
},
"master": {
"url": "https://localhost:8443",
"user": "Administrator",
"password": "test"
},
"shadow": {
"url": "https://localhost:8444",
"user": "Administrator",
"password": "test"
}
}
1.2.2.5.13.2 Source Files
Scenario Configuration [page 467]
Initial Configuration [page 468]
Subaccount Configuration [page 470]
High Availability Settings [page 475]
Backup And Restore Configuration [page 477]
Solution Management Integration [page 478]
466 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-466-320.jpg)
![//If you don't like to use _links, you can easily compute the entity links
var subaccountLinks: Map<String, HalLink> = mapOf()
Fuel.post("${config.master!!.url}/api/v1/configuration/subaccounts")
.authentication().basic(config.master!!.user,
config.master!!.password)
.jsonBody(subaccountCreateData)
.responseObject<SubaccountInfo> { _, response, result ->
when (result) {
is Result.Success -> {
val subaccountLocation =
response.header("Location").first()
println("1.1. subaccount was created under:
$subaccountLocation")
println("subaccount: ${result.get()} ")
//GET details as SubaccountInfo every time possible by
invoking
//https://<SCC>/api/v1/configuration/subaccounts/
<regionHost>/<subaccountId>
subaccountLinks = result.get()._links
}
is Result.Failure -> processRequestError(result.error)
}
}
.join()
//1.2. From time to time it is necessary to extend the validity of the
subaccount - refresh subaccount
//Again some cloud landscapes require 2-Factor-Authentication
println("Enter MFA (aka 2FA) token for refresh, if required: ")
token = readLine() ?: ""
Fuel.post(subaccountLinks["validity"]!!.href)
.authentication().basic(config.master!!.user,
config.master!!.password)
.jsonBody(SubaccountRefreshCred(config.subaccount!!.user, "" +
config.subaccount!!.password + token))
.responseObject<SubaccountInfo> { _, _, result ->
when (result) {
is Result.Success -> println("1.2. validity of the subaccount
was extended")
is Result.Failure -> processRequestError(result.error)
}
}
.join()
//2.1. Create a system mapping (aka access control) for an HTTP service
val httpSystem = SystemMapping(
"virtual.host", "vport", "local", "lport",
CommunicationProtocol.HTTPS,
BackendType.abapSys, hostInHeader = HostInHeader.INTERNAL
)
var httpSystemLinks: Map<String, HalLink> = mapOf()
Fuel.post(subaccountLinks["systemMappings"]!!.href)
.authentication().basic(config.master!!.user,
config.master!!.password)
.jsonBody(httpSystem)
.responseString { _, response, result ->
when (result) {
is Result.Success -> {
val httpSystemMappingLocation =
response.header("Location").first()
println("2.1. system mapping was created under:
$httpSystemMappingLocation")
//GET the details about the system mapping by invoking
//https://<SCC>/api/v1/configuration/subaccounts/
<regionHost>/<subaccountId>/systemMappings/<vhost>:<vport>
Fuel.get(httpSystemMappingLocation)
.authentication().basic(config.master!!.user,
config.master!!.password)
.responseObject<SystemMapping> { _, _, result ->
when (result) {
SAP BTP Connectivity
Connectivity PUBLIC 471](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-471-320.jpg)
![is Result.Success -> {
println("system mapping: ${result.get()}")
httpSystemLinks = result.get()._links
}
is Result.Failure ->
processRequestError(result.error)
}
}
.join()
}
is Result.Failure -> processRequestError(result.error)
}
}
.join()
//2.2 Add an allowed resource to the system mapping. Since this system
mapping points to an HTTP service, use HTTP resource parameters
Fuel.post(httpSystemLinks["resources"]!!.href)
.authentication().basic(config.master!!.user,
config.master!!.password)
.jsonBody(HttpResource("/", exactMatchOnly = false))
.responseString { _, response, result ->
when (result) {
is Result.Success -> {
val httpResourceLocation =
response.header("Location").first()
println("2.2. http resource was created under:
$httpResourceLocation")
//GET the details about the resource by invoking
//https://<SCC>/api/v1/configuration/subaccounts/
<regionHost>/<subaccountId>/systemMappings/<vhost>:<vport>/<encoded-id>
//<encoded-id> -> replace '/' with '-'
Fuel.get(httpResourceLocation)
.authentication().basic(config.master!!.user,
config.master!!.password)
.responseObject<HttpResource> { _, _, result ->
when (result) {
is Result.Success -> println("http resource: $
{result.get()}")
is Result.Failure ->
processRequestError(result.error)
}
}
.join()
}
is Result.Failure -> processRequestError(result.error)
}
}
.join()
//3.1 Create a system mapping for an RFC service
var rfcSystemLinks: Map<String, HalLink> = mapOf()
Fuel.post(subaccountLinks["systemMappings"]!!.href)
.authentication().basic(config.master!!.user,
config.master!!.password)
.jsonBody(
SystemMapping(
"virtual.host",
"rfcport",
"local",
"rfcport",
CommunicationProtocol.RFCS,
BackendType.abapSys
)
)
.responseString { _, response, result ->
when (result) {
is Result.Success -> {
val rfcSystemMappingLocation =
response.header("Location").first()
472 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-472-320.jpg)
![println("3.1. system mapping was created under:
$rfcSystemMappingLocation")
//GET the details about the system mapping by invoking
//https://<SCC>/api/v1/configuration/subaccounts/
<regionHost>/<subaccountId>/systemMappings/<vhost>:<vport>
Fuel.get(rfcSystemMappingLocation)
.authentication().basic(config.master!!.user,
config.master!!.password)
.responseObject<SystemMapping> { _, _, result ->
when (result) {
is Result.Success -> {
println("system mapping: ${result.get()}")
rfcSystemLinks = result.get()._links
}
is Result.Failure ->
processRequestError(result.error)
}
}
.join()
}
is Result.Failure -> processRequestError(result.error)
}
}
.join()
//3.2 Now add the function module RFC_SYSTEM_INFO as an allowed resource
to the system mapping
val rfcResource = RfcResource("RFC_SYSTEM_INFO")
Fuel.post(rfcSystemLinks["resources"]!!.href)
.authentication().basic(config.master!!.user,
config.master!!.password)
.jsonBody(rfcResource)
.responseString { _, response, result ->
when (result) {
is Result.Success -> {
val resourceLocation = response.header("Location").first()
println("3.2. rfc resource was created under:
$resourceLocation")
//GET the details about the resource by invoking
//https://<SCC>/api/v1/configuration/subaccounts/
<regionHost>/<subaccountId>/systemMappings/<vhost>:<vport>/<encoded-id>
//<encoded-id> -> replace '/' with '-'
Fuel.get(resourceLocation)
.authentication().basic(config.master!!.user,
config.master!!.password)
.responseObject<RfcResource> { _, _, result ->
when (result) {
is Result.Success -> println("rfc resource: $
{result.get()}")
is Result.Failure ->
processRequestError(result.error)
}
}
.join()
}
is Result.Failure -> processRequestError(result.error)
}
}
.join()
}
//Data structures used by REST calls in this scenario
//Nullable properties are optional
data class SubaccountConfiguration(
var regionHost: String,
var subaccount: String,
var cloudUser: String,
var cloudPassword: String,
var displayName: String? = null,
var locationId: String? = null
SAP BTP Connectivity
Connectivity PUBLIC 473](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-473-320.jpg)
![○ Choose the Add icon to add a host.
Note
Multiple hosts are currently not supported.
○ Choose Edit to edit the selected host.
○ Choose Delete to delete the selected hosts.
5. Enter the user name and password for the service user that is used to contact the LDAP system.
Note
The user name must be fully qualified, including the AD domain suffix, for example,
john.smith@mycompany.com.
6. In User Path, specify the LDAP subtree that contains the users.
7. In Group Path, specify the LDAP subtree that contains the groups.
8. Choose Save.
Related Information
Using an SAP System as an On-Premise User Store
Use LDAP for Authentication [page 503]
Managing Destinations [page 38]
1.2.2.7 Using Service Channels
Configure Cloud Connector service channels to connect your on-premise network to specific services on SAP
BTP.
Context
Cloud Connector service channels provide access from an external network to certain services on SAP BTP.
The called services are not exposed to direct access from the Internet. The Cloud Connector ensures that the
connection is always available and communication is secured.
482 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-482-320.jpg)
![Service Channel Type Description
SAP HANA Database on SAP BTP The service channel for the SAP HANA Database lets you
access SAP HANA databases that run in the Cloud from da
tabase clients (for example, clients using ODBC/JDBC driv
ers). You can use the service channel to connect database,
analytical, BI, or replication tools to your SAP HANA data
base in your SAP BTP subaccount.
RFC Connection to SAP BTP ABAP environment The service channel for RFC supports calls from on-premise
systems to the SAP BTP ABAP environment using RFC.
Next Steps
Configure a Service Channel for an SAP HANA Database [page 483]
Connect DB Tools to SAP HANA via Service Channels [page 486]
Configure a Service Channel for RFC [page 487]
Related Information
Service Channels: Port Overview [page 489]
1.2.2.7.1 Configure a Service Channel for an SAP HANA
Database
Using Cloud Connector service channels, you can establish a connection to an SAP HANA database in SAP BTP
that is not directly exposed to external access.
Context
The service channel for SAP HANA Database allows accessing SAP HANA databases running in the cloud via
ODBC/JDBC. You can use the service channel to connect database, analytical, BI, or replication tools to an SAP
HANA database in your SAP BTP subaccount.
In the Cloud Foundry environment, this feature is only available in regions (data centers) that provide the SAP
HANA service (i.e., SAP data centers (openstack), Azure and AWS). In AWS regions, you can currently use the
service channel only for SAP HANA databases provisioned before June 4, 2018 (old version). Using the SAP
HANA service provisioned after June 4, 2018 (new version on AWS and GCP), you can access SAP HANA
SAP BTP Connectivity
Connectivity PUBLIC 483](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-483-320.jpg)
![Where
○ test: Cloud Foundry space name
○ testInstance: tenant database instance name
○ 3fcc976d-457a-474e-975b-e572600f474e:de19c262-a1fc-4096-bfce-1c41388e4b49: database ID
6. Specify the local instance number. This is a double-digit number which computes the local port used to
access the SAP HANA instance in the cloud. The local port is derived from the local instance number as
3<instance number>15. For example, if the instance number is 22, then the local port is 32215. The
local instance number must not be 00. This instance number might cause problems with some SAP HANA
clients.
7. Specify the number of physical connections to SAP BTP. The default value is 1. One physical connection
can open various virtual connections through multiplexing.
8. Leave Enabled selected to establish the channel immediately after clicking Finish, or unselect it if you don't
want to establish the channel immediately.
9. Choose Finish.
Next Steps
Once you have established an SAP HANA Database service channel, you can connect on-premise database or
BI tools to the selected SAP HANA database in the cloud. This may be done by using
<cloud_connector_host>:<local_HANA_port> in the JDBC/ODBC connect strings.
See Connect DB Tools to SAP HANA via Service Channels [page 486].
SAP BTP Connectivity
Connectivity PUBLIC 485](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-485-320.jpg)
![Procedure
1. To establish a highly available connection to one or multiple SAP HANA instances in the cloud, we
recommend that you make use of the failover support of the Cloud Connector. Set up a master and a
shadow instance. See Install a Failover Instance for High Availability [page 508].
2. In the master instance, configure a service channel to the SAP HANA database of the SAP BTP subaccount
to which you want to connect. If, for example, the chosen HANA instance is 01, the port of the service
channel is 30115. See also Configure a Service Channel for an SAP HANA Database [page 483].
3. Connect on-premise DB tools via JDBC to the SAP HANA database by using the following connection
string:
Example:
jdbc:sap://<cloud-connector-master-host>:30115;<cloud-connector-shadow-host>:
30115[/?<options>]
The SAP HANA JDBC driver supports failover out of the box. All you need is to configure the shadow
instance of the Cloud Connector as a failover server in the JDBC connection string. The different options
supported in the JDBC connection string are described in: Connect to SAP HANA via JDBC
4. You can also connect on-premise DB tools via ODBC to the SAP HANA database. Use the following
connection string:
"DRIVER=HDBODBC32;UID=<user>;PWD=<password>;SERVERNODE=<cloud-connector-
master-host>:30115;<cloud-connector-shadow-host>:30115;"
Related Information
Guides for earlier releases of SAP HANA
1.2.2.7.3 Configure a Service Channel for RFC
For scenarios that need to call from on-premise systems to SAP BTP ABAP environment using RFC, you can
establish a connection to an ABAP Cloud tenant host. To do this, select On-Premise to Cloud Service
Channels in the Cloud Connector.
Prerequisites
SAP BTP Connectivity
Connectivity PUBLIC 487](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-487-320.jpg)
![1.2.2.8 Configure Trust
Set up an allowlist for cloud applications and a trust store for on-premise systems in the Cloud Connector.
Tasks
Trust Cloud Applications in the Cloud Connector [page 490]
Configure the Trust Store [page 492]
Trust Cloud Applications in the Cloud Connector
Restriction
Currently, the complete implementation of this feature is available only for interaction with the Neo
environment.
By default, all applications within a subaccount are allowed to use the Cloud Connector associated with the
subaccount they run in. However, this behavior might not be desired in any scenario. For example, this may be
acceptable for some applications, as they must interact with on-premise resources, while other applications,
for which it is not transparent whether they try to receive on-premise data, might turn out to be malicious. For
such cases, you can use an application allowlist.
490 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-490-320.jpg)
![As long as there is no entry in this list, all applications are allowed to use the Cloud Connector. If one or more
entries appear in the allowlist, then only these applications are allowed to connect to the exposed systems in
the Cloud Connector.
You can add, edit, or delete entries as follows:
1. From your subaccount menu, choose Cloud to On-Premise and go to the Applications tab.
2. To add an application, choose the Add icon in section Trusted Applications.
3. Enter the <Application Name> in the Add Tunnel Application dialog.
Note
To add all applications that are listed in section Tunnel Connection Limits on the same screen, you can
also use the Upload button next to the Add button. The list Tunnel Connection Limits shows all
applications for which a specific maximal number of tunnel connections was specified. See also:
Configure Tunnel Connections [page 496].
4. (Optional) Enter the maximal number of <Tunnel Connections> only if you want to override the default
value.
5. Choose Save.
Note
The application name is visible in the SAP BTP cockpit under Applications Java Applications . To
allow a subscribed application, you must add it to the allowlist in the format
<providerSubaccount>:<applicationName>. In particular, when using HTML5 applications, an
implicit subscription to services:dispatcher is required.
To edit an existing entry:
1. Choose the Edit button.
2. When you are done, select Save.
To remove an application from the list:
1. Select the entry.
2. Choose Delete.
To delete all entries, choose Delete All.
SAP BTP Connectivity
Connectivity PUBLIC 491](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-491-320.jpg)
![To add all applications from section Tunnel Connection Limits to the allowlist, choose the button Add all
applications... from section Trusted Applications.
Back to Tasks [page 490]
Configure the Trust Store
By default, the Cloud Connector trusts every on-premise system when connecting to it via TLS. As this may be
an undesirable behavior from a security perspective, you can configure a trust store that acts as an allowlist of
trusted certificate authorities. Any TLS server certificate issued by one of those CAs will be considered trusted.
If the CA that has issued a concrete server certificate is not included in the trust store, the server is considered
untrusted and the connection will fail.
You can configure the trust store as follows:
1. From the main menu, choose Configuration .
2. Select the On Premise tab, section Trust Store.
An empty trust store does not impose any restrictions on the trusted on-premise systems. It becomes an
allowlist as soon as you add the first public key.
Note
You must provide the CA's X.509 certificates in .der or .cer format.
492 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-492-320.jpg)
![Back to Tasks [page 490]
1.2.2.9 Configure Domain Mappings for Cookies
Context
Some HTTP servers return cookies that contain a domain attribute. For subsequent requests, HTTP clients
should send these cookies to machines that have host names in the specified domain.
For example, if the client receives a cookie like the following:
Set-Cookie: cookie-field=some-value; domain=mycompany.corp; path=...; ...
It returns the cookie in follow-up requests to all hosts like ecc60.mycompany.corp,
crm40.mycompany.corp, and so on, if the other attributes like path and attribute require it.
However, in a Cloud Connector setup between a client and a Web server, this may lead to problems. For
example, assume that you have defined a virtual host sales-system.cloud and mapped it to the internal host
name ecc60.mycompany.corp. The client "thinks" it is sending an HTTP request to the host name sales-
system.cloud, while the Web server, unaware of the above host name mapping, sets a cookie for the domain
mycompany.corp. The client does not know this domain name and thus, for the next request to that Web
server, doesn't attach the cookie, which it should do. The procedure below prevents this problem.
Procedure
1. From your subaccount menu, choose Cloud To On-Premise, and go to the Cookie Domains tab.
2. Choose Add.
3. Enter cloud as the virtual domain, and your company name as the internal domain.
4. Choose Save.
SAP BTP Connectivity
Connectivity PUBLIC 493](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-493-320.jpg)
![The Cloud Connector checks the Web server's response for Set-Cookie headers. If it finds one with an
attribute domain=intranet.corp, it replaces it with domain=sales.cloud before returning the HTTP
response to the client. Then, the client recognizes the domain name, and for the next request against
www1.sales.cloud it attaches the cookie, which then successfully arrives at the server on
machine1.intranet.corp.
Note
Some Web servers use a syntax such as domain=.intranet.corp (RFC 2109), even though the
newer RFC 6265 recommends using the notation without a dot.
Note
The value of the domain attribute may be a simple host name, in which case no extra domain mapping
is necessary on the Cloud Connector. If the server sets a cookie with
domain=machine1.intranet.corp, the Cloud Connector automatically reverses the mapping
machine1.intranet.corp to www1.sales.cloud and replaces the cookie domain accordingly.
Related Information
Configure Access Control [page 369]
1.2.2.10 Configure Solution Management Integration
Activate Solution Management reporting in the Cloud Connector.
If you want to monitor the Cloud Connector with the SAP Solution Manager, you can install a host agent on the
machine of the Cloud Connector and register the Cloud Connector on your system.
Prerequisites
● You have installed the SAP Diagnostics Agent and SAP Host Agent on the Cloud Connector host and
connected them to the SAP Solution Manager. As of Cloud Connector version 2.11.2, the RPM on Linux
ensures that the host agent configuration is adjusted and that user groups are setup correctly.
For more details about the host agent and diagnostics agent, see SAP Host Agent and the SCN Wiki SAP
Solution Manager Setup/Managed System Checklist .
See also SAP notes 2607632 (SAP Solution Manager 7.2 - Managed System Configuration for SAP Cloud
Connector) and 1018839 (Registering in the System Landscape Directory using sldreg). For consulting,
contact your local SAP partner.
494 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-494-320.jpg)
![ Note
Linux OS: if you installed the host agent after installing the Cloud Connector, you can execute
enableSolMan.sh in the installation directory (available as of Cloud Connector version 2.11.2) to
adjust the host agent configuration and user group setup. This action requires root permission.
● The SAP Solution Manager must be of release 7.2 SP06 or higher.
Procedure
To enable the integration, do the following:
1. From the Cloud Connector main menu, choose Configuration Reporting . In section Solution
Management of the Reporting tab, select Edit.
2. Select the Active checkbox.
3. In the field <Host Agent>, specify the location of the host agent as filepath.
4. If you want to store the reporting results (Dynamic Statistical Records), select Write DSR To File.
5. Choose Save.
Note
To download the registration file lmdbModel.xml, choose the icon Download registration file from the
Reporting tab.
Related Information
Monitoring [page 516]
SAP BTP Connectivity
Connectivity PUBLIC 495](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-495-320.jpg)
![1.2.2.11 Configure Tunnel Connections
Adapt connectivity settings that control the throughput by choosing the appropriate limits (maximal values).
If required, you can adjust the following parameters for the communication tunnel by changing their default
values:
● Application Tunnel Connections (default: 1)
Note
This parameter specifies the default value for the maximal number of tunnel connections per
application. The value must be higher than 0.
● Tunnel Worker Threads (default: 10)
● Protocol Processor Worker Threads (default: 20)
For detailed information on connection configuration requirements, see Configuration Setup [page 290].
To change the parameter values, do the following:
1. From the Cloud Connector main menu, choose Configuration Advanced . In section Connectivity,
select Edit.
2. In the Edit Connectivity Settings dialog, change the parameter values as required.
3. Choose Save.
Additionally, you can specify the number of allowed tunnel connections for each application that you have
specified as a trusted application [page 343].
Note
If you don't change the value for a trusted application, it keeps the default setting specified above. If you
change the value, it may be higher or lower than the default and must be higher than 0.
To add a specific connection limit to a trusted application, do the following:
1. From your subaccount menu, choose Cloud To On-Premise Applications . In section Tunnel
Connection Limits, choose Add.
496 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-496-320.jpg)
![1.2.3 Operations
Learn more about operating the Cloud Connector, using its administration tools and optimizing its functions.
Topic Description
Configure Named Cloud Connector Users [page 502] If you operate an LDAP server in your system landscape, you
can configure the Cloud Connector to use the named users
who are available on the LDAP server instead of the default
Cloud Connector users.
High Availability Setup [page 507] The Cloud Connector lets you install a redundant (shadow)
instance, which monitors the main (master) instance.
Change the UI Port [page 513] Use the changeport tool (Cloud Connector version 2.6.0+) to
change the port for the Cloud Connector administration UI. .
Connect and Disconnect a Cloud Subaccount [page 514] As a Cloud Connector administrator, you can connect the
Cloud Connector to (and disconnect it from) the configured
cloud subaccount.
Secure the Activation of Traffic Traces [page 515] Tracing of network traffic data may contain business critical
information or security sensitive data. You can implement a
"four-eyes" (double check) principle to protect your traces
(Cloud Connector version 1.3.2+).
Monitoring [page 516] Use various views to monitor the activities and state of the
Cloud Connector.
Alerting [page 542] Configure the Cloud Connector to send email alerts when
ever critical situations occur that may prevent it from oper
ating.
Audit Logging [page 545] Use the auditor tool to view and manage audit log informa
tion (Cloud Connector version 2.2+).
Troubleshooting [page 548] Information about monitoring the state of open tunnel con
nections in the Cloud Connector. Display different types of
logs and traces that can help you troubleshoot connection
problems.
Process Guidelines for Hybrid Scenarios [page 553] How to manage a hybrid scenario, in which applications run
ning on SAP BTP require access to on-premise systems us
ing the Cloud Connector.
1.2.3.1 Configure Named Cloud Connector Users
Set up LDAP-based user management for the Cloud Connector.
502 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-502-320.jpg)
![LDAP-Based User Management
We recommend that you configure LDAP-based user management for the Cloud Connector to allow only
named administrator users to log on to the administration UI.
This guarantees traceability of the Cloud Connector configuration changes via the Cloud Connector audit log. If
you use the default and built-in Administrator user, you cannot identify the actual person or persons who
perform configuration changes. Also, you will not be able to use different types of user groups.
Configuration
If you have an LDAP server in your landscape, you can configure the Cloud Connector to authenticate Cloud
Connector users against the LDAP server.
Valid users or user groups must be assigned to one of the following roles:
● Administrator users: admin or sccadmin
● Display users: sccdisplay or sccmonitoring
Note
The role sccmonitoring provides access to the monitoring APIs, and is particularly used by the SAP
Solution Manager infrastructure, see Monitoring APIs [page 524]. It cannot be used to access the
Cloud Connector administation UI.
● Support users: sccsupport
Alternatively, you can define custom role names for each of these user groups, see: Use LDAP for
Authentication [page 503].
Once configured, the default Cloud Connector Administrator user becomes inactive and can no longer be
used to log on to the Cloud Connector.
1.2.3.1.1 Use LDAP for Authentication
You can use LDAP (Lightweight Directory Access Protocol) to configure Cloud Connector authentication.
After installation, the Cloud Connector uses file-based user management by default. Alternatively, the Cloud
Connector also supports LDAP-based user management. If you operate an LDAP server in your landscape, you
can configure the Cloud Connector to use the LDAP user base.
If LDAP authentication is active, you can assign users or user groups to the following default roles:
Default Role Authorization
sccadmin or admin Administrate the Cloud Connector (all CRUD operations).
SAP BTP Connectivity
Connectivity PUBLIC 503](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-503-320.jpg)
![Default Role Authorization
sccdisplay Access the Cloud Connector administration UI in read-only
mode.
sccsupport ● Access the Cloud Connector administration UI in read-
only mode.
● Perform support-related tasks like setting trace levels or
creating a thread dump.
sccmonitoring Provides access to the monitoring APIs, and is particularly
used by the SAP Solution Manager infrastructure, see Moni
toring APIs [page 524].
Note
This role cannot be used to access the Cloud Connector
administation UI.
Group membership is checked by the Cloud Connector.
Setting LDAP Authentication
1. From the main menu, choose Configuration and go to the User Interface tab.
2. From the Authentication section, choose Switch to LDAP.
3. (Optional) To save intermediate adoptions of the LDAP configuration, choose Save Draft. This lets you
store the changes in the Cloud Connector without activation.
504 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-504-320.jpg)
![● Mac OS X: /opt/sap/scc/config_master/org.eclipse.gemini.web.tomcat/default-
server.xml
1. Replace the Realm section with the following:
<Realm className="org.apache.catalina.realm.LockOutRealm">
<Realm className="org.apache.catalina.realm.CombinedRealm">
<Realm
X509UsernameRetrieverClassName="com.sap.scc.tomcat.utils.SccX509SubjectDnRetri
ever" className="org.apache.catalina.realm.UserDatabaseRealm"
digest="SHA-256" resourceName="UserDatabase"/>
<Realm
X509UsernameRetrieverClassName="com.sap.scc.tomcat.utils.SccX509SubjectDnRetri
ever" className="org.apache.catalina.realm.UserDatabaseRealm" digest="SHA-1"
resourceName="UserDatabase"/>
</Realm>
</Realm>
2. Restart the Cloud Connector service:
○ Microsoft Windows OS: Open the Windows Services console and restart the cloud connector
service.
○ Linux OS: Execute
○ System V init distributions: service scc_daemon restart
○ Systemd distributions: systemctl restart scc_daemon
○ Mac OS X: Not applicable because no daemon exists (for Mac OS X, only a portable variant is
available).
1.2.3.2 High Availability Setup
You can operate the Cloud Connector in a high availability mode, in which a master and a shadow instance are
installed.
Task Description
Install a Failover Instance for High Availability [page 508] Install a redundant Cloud Connector instance (shadow) that
monitors the main instance (master).
Master and Shadow Administration [page 511] Learn how to operate master and shadow instances.
Related Information
Connect DB Tools to SAP HANA via Service Channels [page 486]
SAP BTP Connectivity
Connectivity PUBLIC 507](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-507-320.jpg)
![1.2.3.2.1 Install a Failover Instance for High Availability
The Cloud Connector lets you install a redundant instance that monitors the main instance.
Context
In a failover setup, when the main instance should go down for some reason, a redundant one can take over its
role. The main instance of the Cloud Connector is called master and the redundant instance is called the
shadow. The shadow has to be installed and connected to its master. During the setup of high availability, the
master pushes the entire configuration to the shadow. Later on, during normal operation, the master also
pushes configuration updates to the shadow. Thus, the shadow instance is kept synchronized with the master
instance. The shadow pings the master regularly. If the master is not reachable for a while, the shadow tries to
take over the master role and to establish the tunnel to SAP BTP.
Note
For detailed information about sizing of the master and the shadow instance, see also Sizing
Recommendations [page 286].
Procedure
Preparing the Master Instance for High Availability
1. Open the Cloud Connector UI and go to the master instance.
2. From the main menu, choose High Availability.
3. Choose Enable.
If this flag is not activated, no shadow instance can connect to this Cloud Connector. Additionally, when
providing a concrete Shadow Host, you can ensure that only from this host a shadow instance can be
connected.
508 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-508-320.jpg)
![Related Information
Initial Configuration [page 312]
Master and Shadow Administration [page 511]
1.2.3.2.2 Master and Shadow Administration
Administration of Shadow Instances
There are several administration activities you can perform on the shadow instance. All configuration of tunnel
connections, host mappings, access rules, and so on, must be maintained on the master instance; however,
you can replicate them to the shadow instance for display purposes. You may want to modify the check
interval (time between checks of whether the master is still alive) and the takeover delay (time the shadow
waits to see whether the master would come back online, before taking over the master role itself).
As of Cloud Connector version 2.11.2, you can configure the timeout for the connection check, by pressing the
gear icon in the section Connection To Master of the shadow connector main page.
SAP BTP Connectivity
Connectivity PUBLIC 511](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-511-320.jpg)
![○ Linux OS, Mac OS X:
./changeport.sh <desired_port>
2. When you see a message stating that the port has been successfully modified, restart the Cloud Connector
to activate the new port.
1.2.3.4 Connect and Disconnect a Cloud Subaccount
The major principle for the connectivity established by the Cloud Connector is that the Cloud Connector
administrator should have full control over the connection to the cloud, that is, deciding if and when the Cloud
Connector should be connected to the cloud, the accounts to which it should be connected, and which on-
premise systems and resources should be accessible to applications of the connected subaccount.
Using the administration UI, the Cloud Connector administrator can connect and disconnect the Cloud
Connector to and from the configured cloud subaccount. Once disconnected, no communication is possible,
either between the cloud subaccount and the Cloud Connector, or to the internal systems. The connection
state can be verified and changed by the Cloud Connector administrator on the Subaccount Dashboard tab of
the UI.
Note
Once the Cloud Connector is freshly installed and connected to a cloud subaccount, none of the systems in
the customer network are yet accessible to the applications of the related cloud subaccount. Accessible
systems and resouurces must be configured explicitly in the Cloud Connector one by one, see Configure
Access Control [page 369].
A Cloud Connector instance can be connected to multiple subaccounts in the cloud. This is useful especially if
you need multiple subaccounts to structure your development or to stage your cloud landscape into
development, test, and production. In this case, you can use a single Cloud Connector instance for multiple
subaccounts. However, we recommend that you do not use subaccounts running in productive scenarios and
subaccounts used for development or test purposes within the same Cloud Connector. You can add or a delete
a cloud account to or from a Cloud Connector using the Add and Delete buttons on the Subaccount Dashboard
(see screenshot above).
514 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-514-320.jpg)
![Related Information
Managing Subaccounts [page 328]
1.2.3.5 Secure the Activation of Traffic Traces
For support purposes, you can trace HTTP and RFC network traffic that passes through the Cloud Connector.
Context
Traffic data may include business-critical information or security-sensitive data, such as user names,
passwords, address data, credit card numbers, and so on. Thus, by activating the corresponding trace level, a
Cloud Connector administrator might see data that he or she is not meant to. To prevent this behavior,
implement the four-eyes principle, which is supported by the Cloud Connector release 1.3.2 and higher.
Once the four-eyes principle is applied, activating a trace level that dumps traffic data will require two separate
users:
● An operating system user on the machine where the Cloud Connector is installed;
● An Administrator user of the Cloud Connector user interface.
By assigning these roles to two different people, you can ensure that both persons are needed to activate a
traffic dump.
Four-Eyes Principle for Microsoft Windows OS
1. Create a file named writeHexDump in <scc_install_dir>scc_config. The owner of this file must be
a user other than the operating system user who runs the cloud connector process.
Note
Usually, this file owner is the user which is specified in the Log On tab in the properties of the cloud
connector service (in the Windows Services console). We recommend that you use a dedicated OS
user for the cloud connector service.
○ Only the file owner should have write permission for the file.
○ The OS user who runs the cloud connector process needs read-only permissions for this file.
○ Initially, the file should contain a line like allowed=false.
○ In the security properties of the file scc_config.ini (same directory), make sure that only the OS
user who runs the cloud connector process has write/modify permissions for this file. The most
efficient way to do this is simply by removing all other users from the list.
2. Once you've created this file, the Cloud Connector refuses any attempt to activate the Payload Trace flag.
SAP BTP Connectivity
Connectivity PUBLIC 515](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-515-320.jpg)
![● On Linux operating systems, the Cloud Connector is registered as a daemon process and restarts
automatically each time the cloud connector process is down, for example, following a system restart.
You can check the daemon state with the following command:
service scc_daemon status
To verify if a Cloud Connector is connected to a certain cloud subaccount, log on to the Cloud Connector
administration UI and go to the Subaccount Dashboard, where the connection state of the connected
subaccounts is visible, as described in section Connect and Disconnect a Cloud Subaccount [page 514].
Monitoring from the Cockpit
The cockpit includes a Connectivity section, where users can check the status of the Cloud Connector(s)
attached in the current subaccount, if any, as well as information about the Cloud Connector ID, version, used
Java runtime, high availability setup (master and shadow instance), and so on (choose Connectivity Cloud
Connectors ). Access to this view is, by default, granted to administrators, developers, and support users.
Monitoring from the Cloud Connector Aministration UI
The Cloud Connector offers various views for monitoring its activities and state.
You can check the overall state of the Cloud Connector through its Hardware Metrics [page 518], whereas
subaccount-specific performance and usage data is available via Subaccount-Specific Monitoring [page 519].
To provide external monitoring tools, you can use the Monitoring APIs [page 524].
Related Information
Configure Solution Management Integration [page 494]
SAP BTP Connectivity
Connectivity PUBLIC 517](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-517-320.jpg)
![High Availability Setup [page 507]
1.2.3.6.1 Hardware Metrics
Check the current state of critical system resources in the Cloud Connector.
You can check the current state of critical system resources (disc space, Java heap, physical memory, virtual
memory) using pie charts.
To access the monitor, choose Hardware Metrics Monitor from the main menu.
In addition, the history of CPU and memory usage (physical memory, Java heap) is shown in history graphs
below the pie charts (recorded in intervals of 15 seconds).
You can view the usage data for a selected time period in each history graph:
● Double-click inside the main graph area to set the start (or end) point, and drag to the left or to the right to
zoom in.
○ The entire timeline is always visible in the smaller bottom area right below the main graph.
○ A frame in the bottom area shows the position of the selected section in the overall timeline.
● Choose Undo zooming in... to reset the main graph area to the full range of available data.
518 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-518-320.jpg)
![1.2.3.6.2 Subaccount-Specific Monitoring
Use different monitoring views in the Cloud Connector administration UI to check subaccount-specific activites
and data.
Content
Performance Overview [page 519]
Most Recent Requests [page 520]
Resource Filter Settings [page 521]
Top Time Consumers [page 522]
Usage Statistics [page 522]
Backend Connections [page 523]
Performance Overview
All requests that travel through the Cloud Connector to a backend system, as specified through access control,
take a certain amount of time. You can check the duration of requests in a bar chart. The requests are not
shown individually, but are assigned to buckets, each of which represents a time range.
SAP BTP Connectivity
Connectivity PUBLIC 519](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-519-320.jpg)
![For example, the first bucket contains all requests that took 10ms or less, the second one the requests that
took longer than 10ms, but not longer than 20ms. The last bucket contains all requests that took longer than
5000ms.
In case of latency gaps, you may try to adjust the influencing parameters: number of connections, tunnel
worker threads, and protocol processor worker threads. For more information, see Configuration Setup [page
290].
The collection of duration statistics starts as soon as the Cloud Connector is operational. You can delete all of
these statistical records by selecting the button Delete All. After that, the collection of duration statistics starts
over.
Note
Delete All deletes not only the list of most recent requests, but it also clears the top time consumers.
Back to Content [page 519]
Most Recent Requests
This option shows the most recent requests:
The number of requests that are shown is limited to 50. You can either view all requests or only the ones
destined for a certain virtual host, which you can select.You can select a row to see more detail.
520 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-520-320.jpg)
![A horizontal stacked bar chart breaks down the duration of the request into several parts: external (backend),
open connection, internal (SCC), SSO handling, and latency effects. The numbers in each part represent
milliseconds.
Note
Parts with a duration of less than 1ms are not included.
In the above example, the selected request took 34ms, to which the Cloud Connector contributed 1ms.
Opening a connection took 18ms. Backend processing consumed 7ms. Latency effects accounted for the
remaining 8ms, while there was no SSO handling necessary and hence it took no time at all.
Back to Content [page 519]
Resource Filter Settings
To further restrict the selection of the listed 50 most recent requests, you can edit the resource filter settings
for each virtual host:
In the Edit dialog, select the virtual host for which you want to specify the resource filter and choose one or
more of the listed accessible resources. This list includes all resources that have been exposed during access
SAP BTP Connectivity
Connectivity PUBLIC 521](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-521-320.jpg)
![control configuration (see also: Configure Access Control [page 369]). If the access policy for an accessible
resource is set to Path and all sub-paths, you can further narrow the selection by adding one or more
sub-paths to the resource as a suffix .
Each selected resource/sub-path is listed separately in the resource filter list.
Note
If you specify sub-paths for a resource, the request URL must match exactly one of these entries to be
recorded. Without specified sub-paths (and the value Path and all sub-paths set for a resource), all
sub-paths of a specified resource are recorded.
Back to Content [page 519]
Top Time Consumers
This option is similar to Most Recent Requests; however, requests are not shown in order of appearance, but
rather sorted by their duration (in descending order). Furthermore, you can delete top time consumers, which
has no effect on most recent requests or the performance overview.
Back to Content [page 519]
Usage Statistics
To view the statistical data regarding the traffic handled by each virtual host, you can select a virtual host from
the table. The detail view shows the traffic handled by each resource, as well as a 24 hour overview of the
throughput as a bar chart that aggregates the throughput (bytes received and bytes sent by a virtual host,
respectively) on an hourly basis.
Note
Currently, this feature is only available for the protocols HTTP(S) and RFC (SNC). Virtual hosts using other
protocols are not listed.
522 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-522-320.jpg)
![The data that is collected includes the number of bytes received from cloud applications and the number of
bytes sent back to cloud applications. The time of the most recent access is shown for the virtual hosts, and in
the detail view also for the resources. If no access has taken place yet, the most recent access is shown as
n.a. (not available). Similarly, the number of bytes received and sent of a virtual host is the sum of bytes
received and sent of its resources.
The tables listing usage statistics of virtual hosts and their resources let you delete unused virtual hosts or
unused resources. Use action Delete to delete such a virtual host or resource.
Caution
● Usage statistics are collected during runtime only and are not stored when stopping the Cloud
Connector. That is, these statistics are lost when the Cloud Connector is stopped or restarted.
● Use care when taking the decision to delete a resource or virtual host based on its usage statistics.
For both virtual hosts and resources, you can use a classic filter button to reduce the virtual hosts or resources
to those that have never been used (since the Cloud Connector started). For the virtual hosts, a second filter
type is available that selects only those virtual hosts that have been used, but include resources never used.
This feature facilitates locating obsolete resources of otherwise active virtual hosts.
Back to Content [page 519]
Backend Connections
This option shows a tabular overview of all active and idle connections, aggregated for each virtual host. By
selecting a row (each of which represents a virtual host) you can view the details of all active connections as
SAP BTP Connectivity
Connectivity PUBLIC 523](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-523-320.jpg)
![well as a graphical summary of all idle connections. The graphical summary is an accumulative view of
connections based on the time the connections have been idle.
The maximum idle time appears on the rightmost side of the horizontal axis. For any point t on that axis
(representing a time value ranging between 0ms and the maximal idle time), the ordinate is the number of
connections that have been idle for no longer than t. You can click inside the graph area to view the respective
abscissa t and ordinate.
Back to Content [page 519]
1.2.3.6.3 Monitoring APIs
Use the Cloud Connector monitoring APIs to include monitoring information in your own monitoring tool.
Context
You might want to integrate some monitoring information in the monitoring tool you use.
For this purpose, the Cloud Connector includes a collection of APIs that allow you to read various types of
monitoring data.
Note
This API set is designed particularly for monitoring the Cloud Connector via the SAP Solution Manager, see
Configure Solution Management Integration [page 494].
Prerequisites
You must use Basic Authentication or form field authentication to read the monitoring data via API.
Users must be assigned to the roles sccmonitoring or sccadmin. The role sccmonitoring is restricted to
managing the monitoring APIs.
Note
The Health Check API does not require a specified user. Separate users are available through LDAP only.
524 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-524-320.jpg)
![URL Parameters
The API URLs adhere to the following pattern:
https://<scchost>:<sccport>/xxx
● Only HTTPS is supported
● <scchost>:<sccport> = cloud connector address
● xxx= path of the calling method
Available APIs
The following APIs are currently available.
● Health Check [page 525] (available as of version 2.6.0)
● Subaccount data [page 525] (as of 2.10.0)
● Connection data [page 527] (as of 2.10.0)
● Performance data [page 529] (as of 2.10.0)
● Top Time Consumers [page 531] (as of 2.11.0)
● Memory Status [page 533] (as of 2.13.0)
● Certificate Status [page 535] (as of 2.13.0)
● Usage Statistics [page 537] (as of 2.13.0)
Health Check (available as of version 2.6.0)
Note
This API is relevant for the master instance as well as for the shadow instance.
Using the health check API, it is possible to recognize that the Cloud Connector is up and running. The purpose
of this health check is only to verify that the Cloud Connector is not down. It does not check any internal state
or tunnel connection states. Thus, it is a quick check that you can execute frequently:
URL https://<scc_host>:<scc_port>/exposed?action=ping
Expected Return Code 200
Back to Available APIs [page 525]
Back to Context [page 524]
List of Subaccounts (available as of version 2.10.0)
Note
This API is relevant for the master instance only.
SAP BTP Connectivity
Connectivity PUBLIC 525](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-525-320.jpg)
![Back to Available APIs [page 525]
Back to Context [page 524]
List of Open Connections (available as of version 2.10.0)
Note
This API is relevant for the master instance only.
SAP BTP Connectivity
Connectivity PUBLIC 527](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-527-320.jpg)
![Back to Available APIs [page 525]
Back to Context [page 524]
Performance Monitor Data (available as of version 2.10.0)
Note
This API is relevant for the master instance only.
Using this API, you can read the data provided by the Cloud Connector performance monitor:
URL https://<scchost>:<sccport>/api/monitoring/
performance/backends
SAP BTP Connectivity
Connectivity PUBLIC 529](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-529-320.jpg)
![Back to Available APIs [page 525]
Back to Context [page 524]
Top Time Consumers (available as of version 2.11.0)
Note
This API is relevant for the master instance only.
Using this API, you can read the data of top time consumers provided by the Cloud Connector performance
monitor:
SAP BTP Connectivity
Connectivity PUBLIC 531](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-531-320.jpg)
![Back to Available APIs [page 525]
Back to Context [page 524]
Memory Status (available as of version 2.13.0)
Note
This API is relevant for the master instance only.
This API provides a snapshot of the current memory status of the machine where the Cloud Connector is
running:
URL https://<scchost>:<sccport>/api/monitoring/
memory
Input None
SAP BTP Connectivity
Connectivity PUBLIC 533](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-533-320.jpg)
![Output JSON document with memory data:
● physicalKB: usage of the physical memory, split into four cate
gories (all sizes in KB):
○ total: total size of the physical memory
○ CloudConnector: size of the physical memory used by the
Cloud Connector
○ others: size of the physical memory used by all other proc
esses
○ free: size of the free physical memory
● virtualKB : usage of the virtual memory, split into four catego
ries (all sizes in KB)
○ total: total size of the virtual memory
○ CloudConnector: size of the virtual memory used by the
Cloud Connector
○ others: size of the virtual memory used by all other proc
esses
○ free: size of the free virtual memory
● cloudConnectorHeapKB : usage of the Java heap, split into
three categories (all sizes in KB):
○ total: total size of the Java heap
○ used: size of the Java heap used by the Cloud Connector
○ free: size of the free Java heap
Example:
Back to Available APIs [page 525]
534 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-534-320.jpg)
![Back to Context [page 524]
Certificate Status (available as of version 2.13.0)
Note
This API is relevant for the master instance only.
Using this API, you can get an overview of the certificates currently employed by the Cloud Connector:
URL https://<scchost>:<sccport>/api/monitoring/
certificates
Input None
SAP BTP Connectivity
Connectivity PUBLIC 535](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-535-320.jpg)
![Output JSON document (an array) holding the list of all certificates that will ex
pire in less than N days, where
N is the number of days specified in the alerting setup regarding certifi-
cates that are close to their expiration date.
URL https://<scchost>:<sccport>/api/monitoring/
certificates/ok
Input None
Output JSON document (array) holding the list of all certificates that continue
to be valid for N days or more, where N is the number of days specified
in the alerting setup regarding certificates that are close to their expira
tion date.
Example:
Back to Available APIs [page 525]
Back to Context [page 524]
Usage Statistics (available as of version 2.13.0)
Note
This API is relevant for the master instance only.
SAP BTP Connectivity
Connectivity PUBLIC 537](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-537-320.jpg)
![Back to Available APIs [page 525]
Back to Context [page 524]
1.2.3.7 Alerting
Configure the Cloud Connector to send e-mail messages when situations occur that may prevent it from
operating correctly.
To configure alert e-mails, choose Alerting from the top-left navigation menu.
You must specify the receivers of the alert e-mails (E-mail Configuration) as well as the Cloud Connector
resources and components that you want to monitor (Observation Configuration). The corresponding Alert
Messages are also shown in the Cloud Connector administration UI.
E-mail Configuration
1. Select E-mail Configuration to specify the list of em-ail addresses to which alerts should be sent (Send To).
Note
The addresses you enter here can use either of the following formats: john.doe@company.com or John
Doe <j.doe@company.com>.
2. Enter the sender's e-mail address (<Sent From>).
3. In <SMTP Server> provide the host of the mail server.
4. You can specify an <SMTP port>, if the server is not using the default ports. For details, contact your e-
mail administrator or provider.
5. Mark the TLS Enabled check box if you want to establish a TLS-encrypted connection.
6. If the SMTP server requires authentication, provide <User> and <Password>.
7. In the Additional Properties section you can provide any property supported by the Java Mail library . All
specified properties will be passed to the SMTP client.
8. Select Save to change the current configuration.
542 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-542-320.jpg)
![1.2.3.8 Audit Logging
Audit log data can alert Cloud Connector administrators to unusual or suspicious network and system
behavior.
Additionally, the audit log data can provide auditors with information required to validate security policy
enforcement and proper segregation of duties. IT staff can use the audit log data for root-cause analysis
following a security incident.
The Cloud Connector includes an auditor tool for viewing and managing audit log information about access
between the cloud and the Cloud Connector, as well as for tracking of configuration changes done in the Cloud
Connector. The written audit log files are digitally signed by the Cloud Connector so that their integrity can be
checked, see Manage Audit Logs [page 545].
Note
We recommend that you permanently switch on Cloud Connector audit logging in productive scenarios.
● Under normal circumstances, set the logging level to Security (the default configuration value).
● If legal requirements or company policies dictate it, set the logging level to All. This lets you use the
log files to, for example, detect attacks of a malicious cloud application that tries to access on-premise
services without permission, or in a forensic analysis of a security incident.
We also recommend that you regularly copy the audit log files of the Cloud Connector to an external persistent
storage according to your local regulations. The audit log files can be found in the Cloud Connector root
directory /log/audit/<subaccount-name>/audit-log_<timestamp>.csv.
1.2.3.8.1 Manage Audit Logs
Configure audit log settings and verify the integrity of audit logs.
Configure Audit Logs in the Cloud Connector
Choose Audit from your subaccount menu and go to Settings to specify the type of audit events the Cloud
Connector should log at runtime. You can currently select between the following Audit Levels (for either
<subaccount> and <cross-subaccount> scope):
● Security: Default value. The Cloud Connector writes an audit entry (Access Denied) for each request
that was blocked. It also writes audit entries, whenever an administrator changes one of the critical
configuration settings, such as exposed back-end systems, allowed resources, and so on.
● All: The Cloud Connector writes one audit entry for each received request, regardless of whether it was
allowed to pass or not (Access Allowed and Access Denied). It also writes audit entries that are
relevant to the Security mode.
● Off: No audit entries are written.
SAP BTP Connectivity
Connectivity PUBLIC 545](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-545-320.jpg)
![Example
In the following example, the Audit Viewer displays Any audit entries, at Security level, for the time frame
between December 18 2020, 00:00:00 and December 19, 00:00:00:
1.2.3.9 Troubleshooting
To troubleshoot connection problems, monitor the state of your open tunnel connections in the Cloud
Connector, and view different types of logs and traces.
Note
For information about a specific problem or an error you have encountered, see Connectivity Support
[page 581].
Monitoring
To view a list of all currently connected applications, choose your Subaccount from the left menu and go to
section Cloud Connections:
548 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-548-320.jpg)
![dump the network traffic into a trace file. This principle requires two users to activate a trace level that
records traffic data. See Secure the Activation of Traffic Traces [page 515].
● SSL Trace: When the SSL trace is activated, the ljs_trace.log file includes information for SSL-
protected communication. To activate a change of this setting, a restart is required. Activate this trace only
when requested by SAP support. It has a high impact on performance as it produces a large amount of
traces.
● Automatic Cleanup lets you remove old trace files that have not been changed for a period of time
exceeding the configured interval. You can choose from a list of predefined periods. The default is Never.
Log and Trace Files
View all existing trace files and delete the ones that are no longer needed.
550 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-550-320.jpg)
![1.2.3.10 Process Guidelines for Hybrid Scenarios
A hybrid scenario is one, in which applications running on SAP BTP require access to on-premise systems.
Define and document your scenario to get an overview of the required process steps.
Tasks
Document the Landscape of a Hybrid Solution [page 553]
Document Administrator Roles [page 554]
Document Communication Channels [page 554]
Define Project and Development Guidelines [page 555]
Define How to Set a Cloud Application Live [page 555]
Document the Landscape of a Hybrid Solution
To gain an overview of the cloud and on-premise landscape that is relevant for your hybrid scenario, we
recommend that you diagrammatically document your cloud subaccounts, their connected Cloud Connectors
and any on-premise back-end systems. Include the subaccount names, the purpose of the subaccounts (dev,
test, prod), information about the Cloud Connector machines (host, domains), the URLs of the Cloud
Connectors in the landscape overview document, and any other details you might find useful to include.
An example of landscape overview documentation could look like this:
SAP BTP Connectivity
Connectivity PUBLIC 553](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-553-320.jpg)
![Back to Tasks [page 553]
Document Administrator Roles
Document the users who have administrator access to the cloud subaccounts, to the Cloud Connector
operating system, and to the Cloud Connector administration UI.
Such an administrator role documentation could look like following sample table:
Resource john@acme.com marry@acme.com pete@acme.com greg@acme.com
Cloud Subaccount
(CA) Dev1
X
CA Dev2 X
CA Test X X
CA Prod X
Cloud Connector Dev1
+ Dev2
X X
Cloud Connector Test X X
Cloud Connector Prod X
Cloud Connector Dev1
+ Dev2 file system
X X
Cloud Connector Test
file system
X
Cloud Connector Prod
file system
Back to Tasks [page 553]
Document Communication Channels
Create and document separate email distribution lists for both the cloud subaccount administrators and the
Cloud Connector administrators.
An example of the documented communication channels could look like this:
Landscape Distribution List
Cloud Subaccount Administrators DL ACME HCP Subaccount Admins
Cloud Connector Administrators DL ACME Cloud Connector Admins
554 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-554-320.jpg)
![Back to Tasks [page 553]
Define Project and Development Guidelines
Define and document mandatory project and development guidelines for your SAP BTP projects. An example
of such a guideline could be similar to the following.
Every SAP BTP project in this organization requires the following:
● Use Maven, Nexus, Git-&-Gerrit for the application development.
● Align with accountable manager in projects (including the names).
● Align with accountable security officer in projects (including the names).
● For externally developed source code, an official handover to the organization.
● Fulfill connection restrictions in a three-system landscape, that is, use a staged landscape for dev, test and
prod, and, for example, the dev landscape connects only to dev systems, and so on.
● Productive subaccounts cannot use the same Cloud Connector as a dev or test subaccount.
Back to Tasks [page 553]
Define How to Set a Cloud Application Live
Define and document how to set a cloud application live and how to configure needed connectivity for such an
application.
For example, the following processes could be seen as relevant and should be defined and document in more
detail:
1. Transferring application to production: Steps for transferring an application to the productive status on the
SAP BTP.
2. Application connectivity: The steps for adding a connectivity destination to a deployed application for
connections to other resources in the test or productive landscape.
3. Cloud Connector Connectivity: Steps for adding an on-premise resource to the Cloud Connector in the test
or productive landscapes to make it available for the connected cloud subaccounts.
4. On-premise system connectivity: The steps for setting up a trusted relationship between an on-premise
system and the Cloud Connector, and to configure user authentication and authorization in the on-premise
system in the test or productive landscapes.
5. Application authorization: The steps for requesting and assigning an authorization that is available inside
the SAP BTP application to a user in the test or productive landscapes.
6. Administrator permissions: Steps for requesting and assigning the administrator permissions in a cloud
subaccount to a user in the test or productive landscape.
Back to Tasks [page 553]
SAP BTP Connectivity
Connectivity PUBLIC 555](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-555-320.jpg)
![1.2.4 Security
Learn how Cloud Connector features help you manage security.
Features
Security is a crucial concern for any cloud-based solution. It has a major impact on the business decision of
enterprises whether to make use of such solutions. SAP BTP is a platform-as-a-service offering designed to run
business-critical applications and processes for enterprises, with security considered on all levels of the on-
demand platform:
Level Features
Application Layer [page 557] ● Frontend security
● Security standard-based application development
Service Layer [page 557] ● Identity and access management
● Data protection
● Regulatory compliance management
Cloud Infrastructure Layer [page 562] ● Network infrastructure and communication
● Sandboxing
● Intrusion detection and prevention
Physical and Environmental Layer [page 563] ● Strict physical access control
● High availability and disaster recovery capabilities
The Cloud Connector enables integration of cloud applications with services and systems running in customer
networks, and supports database connections from the customer network to SAP HANA databases running on
SAP BTP. As these are security-sensitive topics, this section gives an overview on how the Cloud Connector
helps maintain security standards for the mentioned scenarios.
Target Audience
The content of this section concerns:
● System and IT administrators
● Technology consultants
● Solution architects
556 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-556-320.jpg)
![Related Information
Security Guidelines [page 563]
1.2.4.1 Application Layer
On application level, the main tasks to ensure secure Cloud Connector operations are to provide appropriate
frontend security (for example, validation of entries) and a secure application development.
Product Security Standard
Basically, you should follow the rules given in the product security standard, for example, protection against
cross-site scripting (XSS) and cross-site request forgery (XSRF).
Scope and Design
The scope and design of security measures on application level strongly depend on the specific needs of your
application.
1.2.4.2 Service Layer
You can use SAP BTP Connectivity to securely integrate cloud applications with systems running in isolated
customer networks.
Overview
After installing the Cloud Connector as integration agent in your on-premise network, you can use it to
establish a persistent TLS tunnel to SAP BTP subaccounts.
To establish this tunnel, the Cloud Connector administrator must authenticate himself or herself against the
related SAP BTP subaccount of which he or she must be a member. Once estabilshed, the tunnel can be used
by applications of the connected subaccount to remotely call systems in your network.
SAP BTP Connectivity
Connectivity PUBLIC 557](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-557-320.jpg)
![Architecture
The figure below shows a system landscape in which the Cloud Connector is used for secure connectivity
between SAP BTP applications and on-premise systems.
● A single Cloud Connector instance can connect to multiple SAP BTP subaccounts, each connection
requiring separate authentication and defining an own set of configuration.
● You can connect an arbitrary number of SAP and non-SAP systems to a single Cloud Connector instance.
● The on-premise system does not need to be touched when used with the Cloud Connector, unless you
configure trust between the Cloud Connector and your on-premise system. A trust configuration is
required, for example, for principal propagation (single sign-on), see Configuring Principal Propagation
[page 340].
● You can operate the Cloud Connector in a high availability mode. To achieve this, you must install a second
(redundant) Cloud Connector (shadow instance), which takes over from the master instance in case of a
downtime.
● The Cloud Connector also supports the communication direction from the on-premise network to the SAP
BTP subaccount, using a database tunnel that lets you connect common ODBC/JDBC database tools to
SAP HANA as well as other available databases in SAP BTP.
.
Related Information
Network Zones [page 559]
Inbound Connectivity [page 559]
Outbound Connectivity [page 561]
558 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-558-320.jpg)
![Audit Log [page 561]
1.2.4.2.1 Network Zones
Choosing a network zone for the Cloud Connector installation.
A company network is usually divided into multiple network zones according to the security level of the
contained systems. The DMZ network zone contains and exposes the external-facing services of an
organization to an untrusted network, typically the Internet. Besides this, there can be one or multiple other
network zones which contain the components and services provided in the company’s intranet.
You can set up the Cloud Connector either in the DMZ or in an inner network zone. Technical prerequisites for
the Cloud Connector to work properly are:
● The Cloud Connector must have access to the SAP BTP landscape host, either directly or via HTTPS proxy
(see also: Prerequisites [page 274]).
● The Cloud Connector must have direct access to the internal systems it shall provide access to. I.e. there
must be transparent connectivity between the Cloud Connector and the internal system.
It’s a company’s decision, whether the Cloud Connector is set up in the DMZ and operated centrally by an IT
department or set up in the intranet and operated by the line of business.
Related Information
Network Zones [page 285]
1.2.4.2.2 Inbound Connectivity
For inbound connections into the on-premise network, the Cloud Connector acts as a reverse invoke proxy
between SAP BTP and the internal systems.
Exposing Resources
Once installed, none of the internal systems are accessible by default through the Cloud Connector: you must
configure explicitly each system and each service and resource on every system to be exposed to SAP BTP in
the Cloud Connector.
You can also specify a virtual host name and port for a configured on-premise system, which is then used in the
cloud. Doing this, you can avoid that information on physical hosts is exposed to the cloud.
SAP BTP Connectivity
Connectivity PUBLIC 559](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-559-320.jpg)
![mandatory to be configured and trust with the respective on-premise system must be established. Trust
configuration, in particular for principal propagation, is the only reason to configure and touch an on-premise
system when using it with the Cloud Connector.
Related Information
Configuring Principal Propagation [page 340]
1.2.4.2.3 Outbound Connectivity
The Cloud Connector supports the communication direction from the on-premise network to SAP BTP, using a
database tunnel.
The database tunnel is used to connect local database tools via JDBC or ODBC to the SAP HANA DB or other
databases onSAP BTP, for example, SAP Business Objects tools like Lumira, BOE or Data Services.
● The database tunnel only allows JDBC and ODBC connections from the Cloud Connector into the cloud. A
reuse for other protocols is not possible.
● The tunnel uses the same security mechanisms as for the inbound connectivity:
○ TLS-encryption and mutual authentication
○ Audit logging
To use the database tunnel, two different SAP BTP users are required:
● A platform user (member of the SAP BTP subaccount) establishes the database tunnel to the HANA DB.
● A HANA DB user is needed for the ODBC/JDBC connection to the database itself. For the HANA DB user,
the role and privilege management of HANA can be used to control which actions he or she can perform on
the database.
Related Information
Using Service Channels [page 482]
1.2.4.2.4 Audit Log
As audit logging is a critical element of an organization’s risk management strategy, the Cloud Connector
provides audit logging for the complete record of access between cloud and Cloud Connector as well as of
configuration changes done in the Cloud Connector.
SAP BTP Connectivity
Connectivity PUBLIC 561](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-561-320.jpg)
![Integrity Check
The written audit log files are digitally signed by the Cloud Connector so that they can be checked for integrity
(see also: Manage Audit Logs [page 545]).
Alerting
The audit log data of the Cloud Connector can be used to alert Cloud Connector administrators regarding
unusual or suspicious network and system behavior.
Additional Use Cases
● The audit log data can provide auditors with information required to validate security policy enforcement
and proper segregation of duties.
● IT staff can use the audit log data for root-cause analysis following a security incident.
Related Information
Audit Logging [page 545]
1.2.4.3 Cloud Infrastructure Layer
Infrastructure and network facilities of the SAP BTP ensure security on network layer by limiting access to
authorized persons and specific business purposes.
Isolated Network
The SAP BTP landscape runs in an isolated network, which is protected from the outside by firewalls, DMZ, and
communication proxies for all inbound and outbound communications to and from the network.
562 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-562-320.jpg)
![Sandboxed Environments
The SAP BTP infrastructure layer also ensures that platform services, like the SAP BTP Connectivity, and
applications are running isolated, in sandboxed environments. An interaction between them is only possible
over a secure remote communication channel.
1.2.4.4 Physical and Environmental Layer
Learn about data center security provided for SAP BTP Connectivity.
SAP BTP runs in SAP-hosted data centers which are compliant with regulatory requirements. The security
measures include, for example:
● strict physical access control mechanisms using biometrics, video surveillance, and sensors
● high availability and disaster recoverability with redundant power supply and own power generation
1.2.4.5 Security Guidelines
Find a checklist of recommended security measures for the Cloud Connector.
Topics
Hover over the elements for a description. Click an element to find the recommended actions in the table
below.
● #unique_158/unique_158_Connect_42_network [page 564]
● #unique_158/unique_158_Connect_42_ui [page 564]
● #unique_158/unique_158_Connect_42_availability [page 566]
SAP BTP Connectivity
Connectivity PUBLIC 563](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-563-320.jpg)
![● #unique_158/unique_158_Connect_42_protocols [page 566]
● #unique_158/unique_158_Connect_42_os [page 564]
● #unique_158/unique_158_Connect_42_oP [page 566]
● #unique_158/unique_158_Connect_42_instances [page 567]
● #unique_158/unique_158_Connect_42_audit [page 565]
Recommended Actions
Topic Description Recommended Action
Network Zone
Back to Topics [page 563]
Depending on the needs of the project,
the Cloud Connector can be either set
up in the DMZ and operated centrally
by the IT department or set up in the in
tranet and operated by the line-of-busi
ness.
To access highly secure on-premise
systems, operate the Cloud Connector
centrally by the IT department and in
stall it in the DMZ of the company net
work.
Set up trust between the on-premise
system and the Cloud Connector, and
only accept requests from trusted
Cloud Connectors in the system.
OS-Level Protection
Back to Topics [page 563]
The Cloud Connector is a security-criti
cal component that handles the in
bound access from SAP BTP applica
tions to systems of an on-premise net
work.
Methods to secure the operating sys
tem, on which the Cloud Connector is
running, should be applied.
Restrict access to the operating system
on which the Cloud Connector is instal
led to the minimal set of users who
should administrate the Cloud
Connector.
Use the machine which runs the Cloud
Connector only for this purpose and
don’t reuse it for other scenarios.
Use hard-drive encryption for the ma
chine that runs the Cloud Connector.
This ensures that the Cloud Connector
configuration data cannot be read or
modified by unauthorized users, even if
they obtain access to the hard drive.
Turn on the audit log on operating sys
tem level to monitor the file operations.
Administration UI
Back to Topics [page 563]
After installation, the Cloud Connector
provides an initial user name and pass
word and forces the user
(Administrator) to change the
password upon initial logon.
Change the password of the
Administrator user immediately after in
stallation. Choose a strong password
for the user (see also Recommenda
tions for Secure Setup [page 299]).
564 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-564-320.jpg)
![Topic Description Recommended Action
Configure a corporate LDAP system for
the user management of the Cloud
Connector administrator users. This
guarantees that users of the Cloud
Connector administration UI are named
users and can be traced via the Cloud
Connector audit log (see Use LDAP for
Authentication [page 503]).
You can access the Cloud Connector
administration UI remotely via HTTPS.
After installation, it uses a self-signed X.
509 certificate as SSL server certifi-
cate, which is not trusted by default by
Web browsers.
Exchange the self-signed X.509 certifi-
cate of the Cloud Connector adminis
tration UI by a certificate that is trusted
by your company and the company’s
approved Web browser settings (see
[Deprecated] Replace the Default SSL
Certificate [page 306]).
For high-security scenarios, limit the
access to the Cloud Connector admin
istration UI to localhost (see also Rec
ommendations for Secure Setup [page
299]).
Use a JVM that allows to limit the ci
phers to a set considered safe (see Rec
ommendations for Secure Setup [page
299]). A list of cipher suites, which are
currently considered safe, is available in
Use Secure Cipher Suites .
Audit Logging
Back to Topics [page 563]
For end-to-end traceability of configura-
tion changes in the Cloud Connector, as
well as communication delivered by the
Cloud Connector, switch on audit log
ging for productive scenarios.
Switch on audit logging in the Cloud
Connector: set audit level to “All” (see
Recommendations for Secure Setup
[page 299] and Manage Audit Logs
[page 545])
Cloud Connector administrators must
ensure that the audit log files are prop
erly archived and are not lost, to con
form to the local regulations.
To gain end-to-end traceability, you
should switch on audit logging also in
the connected on-premise systems.
SAP BTP Connectivity
Connectivity PUBLIC 565](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-565-320.jpg)
![Topic Description Recommended Action
High Availability
Back to Topics [page 563]
To guarantee high availability of the
connectivity for cloud integration sce
narios, run productive instances of the
Cloud Connector in high availability
mode, that is, with a second (redun
dant) Cloud Connector in place.
Use the high availability feature of the
Cloud Connector for productive scenar
ios (see Install a Failover Instance for
High Availability [page 508]).
Supported Protocols
Back to Topics [page 563]
HTTP, HTTPS, RFC and RFC over SNC
are currently supported as protocols for
the communication direction from the
cloud to on-premise.
The route from the application VM in
the cloud to the Cloud Connector is al
ways encrypted.
You can configure the route from the
Cloud Connector to the on-premise
system to be encrypted or unen
crypted.
The route from the Cloud Connector to
the on-premise system should be en
crypted using TLS (for HTTPS) or SNC
(for RFC).
Trust between the Cloud Connector and
the connected on-premise systems
should be established (see Set Up Trust
for Principal Propagation [page 341]).
Configuration of On-Premise Systems
Back to Topics [page 563]
When configuring the access to an in
ternal system in the Cloud Connector,
map physical host names to virtual host
names to prevent exposure of infor
mation on physical systems to the
cloud.
Use hostname mapping of exposed on-
premise systems in the access control
of the Cloud Connector (see Configure
Access Control (HTTP) [page 370] and
Configure Access Control (RFC) [page
377]).
When configuring the access to an in
ternal system, restrict access to those
resources which are actually required
by the cloud applications. Do not ex
pose the complete system.
Narrow access to on-premise systems
to resources required by the relevant
cloud applications in the access control
of the Cloud Connector (see Configure
Access Control (HTTP) [page 370] and
Configure Access Control (RFC) [page
377]).
To allow access only for trusted appli
cations of your SAP BTP subaccount to
on-premise systems, configure the list
of trusted applications in the Cloud
Connector.
Narrow the list of cloud applications
which are allowed to use the on-prem
ise tunnel to the ones that need on-
premise connectivity (see Set Up Trust
for Principal Propagation [page 341]).
566 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-566-320.jpg)
![Topic Description Recommended Action
Cloud Connector Instances
Back to Topics [page 563]
You can connect a single Cloud
Connector instance to multiple SAP
BTP subaccounts.
Subaccounts can be created by SAP
BTP users as a self service. Different
subaccounts are often used to sepa
rate development, test and produc
tion.
Do not mix productive Cloud Connector
usages with development or test sce
narios.
Use different Cloud Connector instan
ces to separate productive and non-
productive scenarios.
Related Information
Recommendations for Secure Setup [page 299]
Secure the Activation of Traffic Traces [page 515]
1.2.5 Upgrade
Upgrade your Cloud Connector and avoid connectivity downtime during the update.
The steps for upgrading your Cloud Connector are specific to the operating system that you use. Previous
settings and configurations are automatically preserved.
Caution
Upgrade is supported only for installer versions, not for portable versions, see Installation [page 273].
Before upgrading, please check the Prerequisites [page 274] and make sure your environment fits the new
version. We recommend that you create a Configuration Backup [page 498] before starting an upgrade.
Avoid Connectivity Downtime
If you have a single-machine Cloud Connector installation, a short downtime is unavoidable during the upgrade
process. However, if you have set up a master and a shadow instance, you can perform the upgrade without
downtime by executing the following procedure:
1. Shut down the shadow instance.
SAP BTP Connectivity
Connectivity PUBLIC 567](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-567-320.jpg)
![2. Perform the upgrade on the shadow instance. (Follow the relevant procedure below.)
3. Restart the shadow instance and connect to the master instance.
4. Perform a Switch Roles operation by pressing the corresponding button in the master administration UI.
The master instance has now changed into a shadow instance.
5. Shut down the new shadow instance and perform the upgrade procedure on it as well.
Caution
When upgrading from a version prior to 2.13, reset the high availability settings in both instances after
upgrading the first instance. Re-establish the master-shadow connection directly after the upgrade of
the second one.
6. Restart the new shadow instance, connect it to the new master, and then perform again the Switch Roles
operation.
Result: Both instances have now been upgraded without connectivity downtime and without configuration
loss.
For more information, see Install a Failover Instance for High Availability [page 508].
Microsoft Windows OS
1. Uninstall the Cloud Connector as described in Uninstallation [page 570] and make sure to retain the
existing configuration.
2. Reinstall the Cloud Connector within the same directory. For more information, see Installation on
Microsoft Windows OS [page 292].
3. Before accessing the administration UI, clear your browser cache to avoid any unpredictable behavior due
to the upgraded UI.
Linux OS
1. Execute the following command: :
rpm -U com.sap.scc-ui-<version>.rpm
Note
Daemon extensions (as of Cloud Connector version 2.12.3)
All extensions to the daemon provided via scc_daemon_extension.sh mechanism will survive a
version update. An upgrade to version 2.12.3 will already consider an existing file, even though previous
versions were not supporting that feature.
2. Before accessing the administration UI, clear your browser cache to avoid any unpredictable behavior due
to the upgraded UI.
568 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-568-320.jpg)
![ Caution
This command also removes the configuration files.
Mac OS X
There is no installer variant for Mac OS X, only a portable one.
Portable Variants
(Microsoft Windows OS, Linux OS, Mac OS X) If you have installed a portable version (zip or tgz archive) of the
Cloud Connector, simply remove the directory in which you have extracted the Cloud Connector archive.
Related Information
Installation [page 273]
1.2.8 Frequently Asked Questions
Answers to the most common questions about the Cloud Connector.
Technical Issues
Does the Cloud Connector send data from on-premise systems to SAP BTP or the other way
around?
The connection is opened from the on-premise system to the cloud, but is then used in the other direction.
An on-premise system is, in contrast to a cloud system, normally located behind a restrictive firewall and its
services aren’t accessible thru the Internet. This concept follows a widely used pattern often referred to as
reverse invoke proxy.
Is the connection between the SAP BTP and the Cloud Connector encrypted?
Yes, by default, TLS encryption is used for the tunnel between SAP BTP and the Cloud Connector.
SAP BTP Connectivity
Connectivity PUBLIC 571](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-571-320.jpg)
![If used properly, TLS is a highly secure protocol. It is the industry standard for encrypted communication and
also, for example, as a secure channel in HTTPS.
Keep your Cloud Connector installation updated and we will make sure that no weak or deprecated ciphers are
used for TLS.
Can I use a TLS-terminating firewall between Cloud Connector and SAP BTP?
This is not possible. Basically, this is a desired man-in-the-middle attack, which does not allow the Cloud
Connector to establish a mutual trust to the SAP BTP side.
What is the oldest version of SAP Business Suite that's compatible with the Cloud Connector?
The Cloud Connector can connect an SAP Business Suite system version 4.6C and newer.
Which JRE versions are supported to run the Cloud Connector?
Supported JRE Version
6 7 8
Cloud Connector Ver
sion
< 2.7.2 Yes Yes No
= 2.7.2 Yes Yes Yes
>= 2.8 No Yes Yes
>=2.12.3 No No Yes
Restriction
Support for Java 7 has been discontinued. For more information, see Prerequisites [page 276].
Tip
We recommend that you always use the latest supported JRE version.
Caution
Version 2.8 and later of theCloud Connector may have problems with ciphers in Google Chrome, if you use
the JVM 7. For more information read this SCN Article .
Which configuration in the SAP BTP destinations do I need to handle the user management
access to the Cloud User Store of the Cloud Connector?
See Configure an On-Premise User Store [page 480].
572 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-572-320.jpg)
![Is the Cloud Connector sufficient to connect the SAP BTP to an SAP ABAP back end or is SAP
BTP Integration needed?
It depends on the scenario: For pure point-to-point connectivity to call on-premise functionality like BAPIs,
RFCs, OData services, and so on, that are exposed via on-premise systems, the Cloud Connector might suffice.
However, if you require advanced functionality, for example, n-to-n connectivity as an integration hub, SAP BTP
Integration – Process Integration is a more suitable solution. SAP BTP Integration can use the Cloud Connector
as a communication channel.
How much bandwidth does the Cloud Connector consume?
The amount of bandwidth depends greatly on the application that is using the Cloud Connector tunnel. If the
tunnel isn’t currently used, but still connected, a few bytes per minute is used simply to keep the connection
alive.
What happens to a response if there's a connection failure while a request is being processed?
The response is lost. The Cloud Connector only provides tunneling, it does not store and forward data when
there are network issues.
Where should I install the Cloud Connector?
For productive instances, we recommend installing the Cloud Connector on a single purpose machine. This is
relevant for Security [page 556]. For more details on which network zones to choose for the Cloud Connector
setup, see Network Zones [page 285].
How many servers do I need to deploy the Cloud Connector?
We recommend that you use at least three servers, with the following purposes:
● Development
● Production master
● Production shadow
Note
Do not run the production master and the production shadow as VMs inside the same physical machine.
Doing so removes the redundancy, which is needed to guarantee high availability. A QA (Quality Assurance)
instance is a useful extension. For disaster recovery, you will also need two additional instances; another
master instance, and another shadow instance.
What are the hardware requirements to deploy the Cloud Connector?
See: Prerequisites [page 274].
SAP BTP Connectivity
Connectivity PUBLIC 573](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-573-320.jpg)
![Can I send push messages from an on-premise system to the SAP BTP through the Cloud
Connector?
No, this is not supported by the Cloud Connector.
Is NTLM supported for authorization against the proxy server?
No, the Cloud Connector currently supports only basic authentication.
What operating systems are supported by the Cloud Connector?
See Prerequisites [page 274].
What processor architectures are supported by the Cloud Connector?
We currently support 64-bit operating systems running only on an x86-64 processor (also known as x64,
x86_64 or AMD64).
See: Prerequisites [page 274].
Can I use the Cloud Connector without an ABAP back end?
Yes, you should be able to connect almost any system that supports the HTTP Protocol, to the SAP BTP, for
example, Apache HTTP Server, Apache Tomcat, Microsoft IIS, or Nginx.
Can I authenticate with client certificates configured in SAP BTP destinations at HTTP services
that are exposed via the Cloud Connector?
No, this is not possible. For client certificate authentication, an end-2-end TLS communication is required. This
is not the case, because the Cloud Connector needs to inspect incoming requests in order to perform access
control checks.
Administration
Are there Audit Logs for changes in the Cloud Connector?
Yes, find more details here: Manage Audit Logs [page 545].
Is it possible to split authorization?
574 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-574-320.jpg)
![No, currently there is only one role that allows complete administration of the Cloud Connector.
Can I configure multiple administrative subaccounts?
Yes, to enable this, you must configure an LDAP server. See: Use LDAP for Authentication [page 503].
How can I reset the Cloud Connector's administrator password when not using LDAP for
authentication?
Visit https:/
/tools.hana.ondemand.com/#cloud to download the portable version of the Cloud Connector.
Extract the users.xml file in the config directory to the config directory of your Cloud Connector installation,
then restart the Cloud Connector.
This resets the password and user name to their default values.
You can manually edit the file; however, we strongly recommend that you use the users.xml file.
How do I create a backup of the Cloud Connector configuration?
Package the following three folders, located in your Cloud Connector installation directory, into an archive file:
● config
● config_master
● scc_config
These folders contain all the relevant configuration information.
As the layout of the configuration files may change between versions, we recommend that you don't restore a
configuration backup of a Cloud Connector 2.x installation into a 2.y installation.
Can I create a backup of the complete installation?
Yes, you can create an archive file of the installation directory to create a full backup. Before you restore from a
backup, note the following:
● If you restore the backup on a different host, the UI certificate will be invalidated.
● Before you restore the backup, you should perform a “normal” installation and then replace the files. This
registers the Cloud Connector at your operating systems package manager.
Why do I need a user ID during configuration?
This user opens the tunnel and generates the certificates that are used for mutual trust later on.
The user is not part of the certificate that identifies the Cloud Connector.
In both the Cloud Connector UI and in the SAP BTP cockpit, this user ID appears as the one who performed the
initial configuration (even though the user may have left the company).
SAP BTP Connectivity
Connectivity PUBLIC 575](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-575-320.jpg)
![Features
Does the Cloud Connector work with the SAP BTP Cloud Foundry environment?
As of version 2.10, the Cloud Connector can establish a connection to regions based on the SAP BTP Cloud
Foundry environment. Newer regions, however, require a Cloud Connector version 2.11 or higher.
Does the Cloud Connector work with SAP S/4HANA Cloud?
As of version 2.10, the Cloud Connector offers a Service Channel to S/4HANA Cloud instances, given that they
are associated with the respective SAP BTP subaccount. For more information, see Using Service Channels
[page 482].
Also supported as of version 2.10: S/4HANA Cloud communication scenarios invoking HTTP services or
remote-enabled function modules (RFMs) in on-premise ABAP systems.
Does the Cloud Connector work with the SAP BTP ABAP environment?
As of version 2.11, the Cloud Connector supports communication from and to the SAP BTP ABAP environment,
when using the Neo Connectivity service. Using the Cloud Foundry Connectivity service requires a Cloud
Connector version 2.12.3 or higher.
How do I bind multiple Cloud Connectors to one SAP BTP subaccount?
SAP BTP Connectivity
Connectivity PUBLIC 577](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-577-320.jpg)
![1.4 Connectivity Support
Support information for SAP BTP Connectivity and the Cloud Connector.
Troubleshooting
Locate the problem or error you have encountered and follow the recommended steps:
● Frequently Asked Questions [page 571] (Cloud Connector)
● Operations [page 502] (Cloud Connector)
● Cloud Connectivity: Guided Answers
● Getting Support (SAP Support Portal, SAP BTP community)
SAP Support Information
If you cannot find a solution to your issue, collect and provide the following specific, issue-relevant information
to SAP Support:
● The Java EE code that throws an error (if any)
● A screenshot of the error message for the failed operation or the error message from the HttpResponse
body
● Access credentials for your cloud or on-premise location
You can submit this information by creating a customer ticket in the SAP CSS system using the following
components:
Component Purpose
Connectivity Service
BC-CP-CON For cloud-side issues with cloud to on-premise connectivity,
where:
● The environment is unknown or
● The issue is not related to a specific environment
BC-CP-CON-CF For cloud-side issues with cloud to on-premise connectivity
in the SAP BTP Cloud Foundry environment.
BC-CP-CON-S4HC For cloud-side issues with cloud to on-premise connectivity
in an S/4HANA Cloud system.
BC-CP-CON-ABAP For cloud-side issues with cloud to on-premise connectivity
in the SAP BTP ABAP environment.
BC-NEO-CON For cloud-side issues with cloud to on-premise connectivity
in the SAP BTP Neo environment.
SAP BTP Connectivity
Connectivity PUBLIC 581](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-581-320.jpg)
![Component Purpose
Destinations
BC-CP-DEST For issues with destination configurations, where:
● The environment is unknown or
● The issue is not related to a specific environment
BC-CP-DEST-CF For general issues with the Destination service in the SAP
BTP Cloud Foundry environment, like:
● REST API
● Instance creation, etc.
BC-CP-DEST-CF-CLIBS For client library issues with the Destination service in the
SAP BTP Cloud Foundry environment.
BC-CP-DEST-CF-TOOLS For issues with the management of destination configura-
tions via tools like the SAP BTP cockpit (Cloud Foundry en
vironment).
BC-CP-DEST-NEO For issues with destination configurations or:
● Management tools
● Client libraries, etc.
related to destinations in the SAP BTP Neo environment.
Cloud Connector
BC-MID-SCC For connectivity issues related to installing and configuring
the Cloud Connector, configuring tunnels, connections, and
so on.
If you experience a more serious issue that cannot be resolved using only traces and logs, SAP Support may
request access to the Cloud Connector. Follow the instructions in these SAP notes:
● To provide access to the Administration UI via a browser, see 592085 .
● To provide SSH access to the operating system of the Linux machine on which the connector is installed,
see 1275351 .
Related Information
Release and Maintenance Strategy [page 582]
1.4.1 Release and Maintenance Strategy
Find information about SAP BTP Connectivity releases, versioning and upgrades.
582 PUBLIC
SAP BTP Connectivity
Connectivity](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-582-320.jpg)
![Release Cycles
Updates of the Connectivity service are published as required, within the regular, bi-weekly SAP BTP release
cycle.
New releases of the Cloud Connector are published when new features or important bug fixes are delivered,
available on the Cloud Tools page.
Cloud Connector Versions
Cloud Connector versions follow the <major>.<minor>.<micro> versioning schema. The Cloud Connector
stays fully compatible within a major version. Within a minor version, the Cloud Connector will stay with the
same feature set. Higher minor versions usually support additional features compared to lower minor versions.
Micro versions generally consist of patches to a <master>.<minor> version to deliver bug fixes.
For each supported major version of the Cloud Connector, only one <major>.<minor>.<micro> version will
be provided and supported on the Cloud Tools page. This means that users must upgrade their existing Cloud
Connectors to get a patch for a bug or to make use of new features.
Cloud Connector Upgrade
New versions of the Cloud Connector are announced in the Release Notes of SAP BTP. We recommend that
Cloud Connector administrators regularly check the release notes for Cloud Connector updates. New versions
of the Cloud Connector can be applied by using the Cloud Connector upgrade capabilities. For more
information, see Upgrade [page 567].
Note
We recommend that you first apply upgrades in a test landscape to validate that the running applications
are working.
There are no manual user actions required in the Cloud Connector when the SAP BTP is updated.
SAP BTP Connectivity
Connectivity PUBLIC 583](https://image.slidesharecdn.com/connectivityservice-231026154548-025b11a1/85/connectivity_service-pdf-583-320.jpg)
Ad
More Related Content
Similar to connectivity_service.pdf (20)
Recently uploaded (10)
Ad
connectivity_service.pdf
- 1. PUBLIC 2021-05-20 SAP BTP Connectivity © 2021 SAP SE or an SAP affiliate company. All rights reserved. THE BEST RUN
- 2. Content 1 Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 1.1 Connectivity in the Cloud Foundry Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 What Is SAP BTP Connectivity?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 What's New for Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Initial Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Developing Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Monitoring and Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 1.2 Cloud Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267 Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502 Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 Update the Java VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 Uninstallation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570 Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 1.3 Connectivity via Reverse Proxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 1.4 Connectivity Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .581 Release and Maintenance Strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 2 PUBLIC SAP BTP Connectivity Content
- 3. 1 Connectivity SAP BTP Connectivity: overview, features, restrictions. Note This documentation refers to SAP BTP, Cloud Foundry environment. If you are looking for information about the Neo environment, see Connectivity for the Neo Environment. Content In this Topic Hover over the elements for a description. Click an element for more information. ● Overview [page 4] ● Features [page 4] ● Restrictions [page 5] In this Guide Hover over the elements for a description. Click an element for more information. ● Connectivity in the Cloud Foundry Environment [page 7] ● Cloud Connector [page 267] ● Connectivity Support [page 581] SAP BTP Connectivity Connectivity PUBLIC 3
- 4. Overview SAP BTP Connectivity allows SAP BTP applications to securely access remote services that run on the Internet or on-premise. This component: ● Allows subaccount-specific configuration of application connections via destinations. ● Provides a Java API that application developers can use to consume remote services. ● Allows you to make connections to on-premise systems, using the Cloud Connector. ● Lets you establish a secure tunnel from your on-premise network to applications on SAP BTP, while you keep full control and auditability of what is exposed to the cloud. ● Supports both the Neo and the Cloud Foundry environment for application development on SAP BTP. A typical scenario for connectivity from your on-premise network to SAP BTP looks like this: ● Your company owns a global account on SAP BTP and one or more subaccounts that are assigned to this global account. ● Using SAP BTP, you subscribe to or deploy your own applications. ● To connect to these applications from your on-premise network, the Cloud Connector administrator sets up a secure tunnel to your company's subaccount on SAP BTP. ● The platform ensures that the tunnel can only be used by applications that are assigned to your subaccount. ● Applications assigned to other (sub)accounts cannot access the tunnel. It is encrypted via transport layer security (TLS), which guarantees connection privacy. Back to Content [page 3] Features 4 PUBLIC SAP BTP Connectivity Connectivity
- 5. SAP BTP Connectivity supports the following protocols and scenarios: Protocol Scenario HTTP(S) Exchange data between your cloud application and Internet services or on-premise systems. ● Create and configure HTTP destinations to make Web connections. ● Connect to on-premise systems via HTTP, using the Cloud Connector. RFC Invoke on-premise ABAP function modules via RFC. ● Create and configure RFC destinations. ● Make connections to back-end systems via RFC, using the Cloud Connector. TCP Access on-premise systems via TCP-based protocols using a SOCKS5 proxy. Back to Content [page 3] Restrictions General [page 5] Protocols [page 6] Cloud Foundry Environment [page 6] Cloud Connector [page 7] Note For information about general SAP BTP restrictions, see Prerequisites and Restrictions. General SAP BTP Connectivity Connectivity PUBLIC 5
- 6. Topic Restriction Java Connector To develop a Java Connector (JCo) application for RFC com munication, your SDK local runtime must be hosted by a 64- bit JVM, on a x86_64 operating system (Microsoft Windows OS, Linux OS, or Mac OS X). On Windows platforms, you must install the Microsoft Vis ual Studio C++ 2013 runtime libraries (vcredist_x64.exe), see Visual C++ Redistributable Packages for Visual Studio 2013 . Ports For Internet connections, you are allowed to use any port >1024. For cloud to on-premise solutions there are no port limitations. Destination Configuration ● You can use destination configuration files with exten sion .props, .properties, .jks, and .txt, as well as files with no extension. ● If a destination configuration consists of a keystore or truststore, it must be stored in JKS files with a stand ard .jks extension. Back to Restrictions [page 5] Protocols For the cloud to on-premise connectivity scenario, the following protocols are currently supported: Protocol Info HTTP HTTPS is not needed, since the tunnel used by the Cloud Connector is TLS-encrypted. RFC You can communicate with SAP systems down to SAP R/3 release 4.6C. Supported runtime environment is SAP Java Buildpack with a minimal version of 1.8.0. TCP You can use TCP-based communication for any client that supports SOCKS5 proxies. Back to Restrictions [page 5] Cloud Foundry Environment Topic Restriction Service Channels Service channels are supported only for SAP HANA data base, see Using Service Channels [page 482]. E-Mail E-mail functions are not supported. Back to Restrictions [page 5] 6 PUBLIC SAP BTP Connectivity Connectivity
- 7. Cloud Connector Topic Restriction Scenarios To learn in which system landscapes you can set up the Cloud Connector, see Extended Scenarios [page 271]. Installation To check all software and hardware restrictions for working with the Cloud Connector, see Prerequisites [page 274]. Back to Restrictions [page 5] Back to Content [page 3] Related Information Connectivity in the Cloud Foundry Environment [page 7] Cloud Connector [page 267] Connectivity via Reverse Proxy [page 579] Connectivity Support [page 581] 1.1 Connectivity in the Cloud Foundry Environment Consuming SAP BTP Connectivity for your application in the Cloud Foundry environment: Overview. Note This documentation refers to SAP BTP, Cloud Foundry environment. If you are looking for information about the Neo environment, see Connectivity for the Neo Environment. Hover over the elements for a description. Click an element for more information. SAP BTP Connectivity Connectivity PUBLIC 7
- 8. ● What Is SAP BTP Connectivity? [page 8] ● What's New for Connectivity [page 14] ● Initial Setup [page 38] ● Monitoring and Troubleshooting [page 266] ● Security [page 266] ● Developing Applications [page 164] 1.1.1 What Is SAP BTP Connectivity? Use SAP BTP Connectivity for your application in the Cloud Foundry environment: available services, connectivity scenarios, user roles. Content Hover over the elements for a description. Click an element for more information. ● Services [page 8] ● Scenarios [page 9] ● User Roles [page 9] Services SAP BTP Connectivity provides two services for the Cloud Foundry environment, the Connectivity service and the Destination service. The Destination service and the Connectivity service together provide virtually the same functionality that is included in the Connectivity service of the Neo environment. In the Cloud Foundry environment however, this functionality is split into two separate services: ● The Connectivity service provides a connectivity proxy that you can use to access on-premise resources. ● Using the Destination service, you can retrieve and store the technical information about the target resource (destination) that you need to connect your application to a remote service or system. You can use both services together as well as separately, depending on the needs of your specific scenario. Back to Content [page 8] 8 PUBLIC SAP BTP Connectivity Connectivity
- 9. Scenarios ● Use the Connectivity service to connect your application or an SAP HANA database to on-premise systems: ○ Set up on-premise communication via HTTP or RFC for your cloud application. ○ Use a service channel to connect to an SAP HANA database on SAP BTP from your on-premise system, see Configure a Service Channel for an SAP HANA Database [page 483]. ● Use the Destination service: ○ To retrieve technical information about destinations that are required to consume the Connectivity service (optional), or ○ To provide destination information for connecting your Cloud Foundry application to any other Web application (remote service). This scenario does not require the Connectivity service. Back to Content [page 8] User Roles In this document, we refer to different types of user roles – responsibility roles and technical roles. Responsibility roles describe the required user groups and their general tasks in the end-to-end setup process. Configuring technical roles, you can control access to the dedicated cloud management tools by assigning specific permissions to users. Responsibility Roles [page 9] Technical Roles [page 10] Responsibility Roles The end-to-end use of the Connectivity service and the Destination service requires these user groups: ● Application operators - are responsible for productive deployment and operation of an application on SAP BTP. Application operators are also responsible for configuring the remote connections (destination and trust management) that an application might need, see Initial Setup [page 38]. ● Application developers - develop a connectivity-enabled SAP BTP application by consuming the Connectivity service and/or the Destination service, see Developing Applications [page 164]. ● IT administrators - set up the connectivity to SAP BTP in your on-premise network, using the Cloud Connector [page 267]. Some procedures on the SAP BTP can be done by developers as well as by application operators. Others may include a mix of development and operation tasks. These procedures are labeled using icons for the respective task type. SAP BTP Connectivity Connectivity PUBLIC 9
- 10. Task Types Operator Developer Operator and/or Devel oper Technical Roles To perform connectivity tasks in the Cloud Foundry environment, the following technical roles apply: Technical Roles [Feature Set A] [page 10] Technical Roles [Feature Set B] [page 11] Note To apply the correct technical roles, you must know on which cloud management tools feature set (A or B) your account is running. For more information on feature sets, see Cloud Management Tools — Feature Set Overview. Technical Roles [Feature Set A] Technical Connectivity Roles and Operations [Feature Set A] Level Operation (SAP BTP Cockpit or Cloud Connector) Role Subaccount Connect a Cloud Connector to a sub account (Cloud Connector) One of these roles: ● Global Account member See Add Members to Your Global Account. ● Security Administrator (must be Global Account member or Cloud Foundry Org/Space member) See Managing Security Adminis trators in Your Subaccount [Fea ture Set A]. Disconnect a Cloud Connector (cock pit) View Cloud Connectors connected to a subaccount (cockpit) Manage destinations (all CRUD opera tions) on subaccount level (cockpit) View destinations (read operations) on subaccount level (cockpit) Manage certificates (all CRUD opera tions) on subaccount level (cockpit) View certificates (read operations) on subaccount level (cockpit) Generate or renew the subaccount key pair for trust management (cock pit) Download the subaccount key pair for trust management (cockpit) 10 PUBLIC SAP BTP Connectivity Connectivity
- 11. Level Operation (SAP BTP Cockpit or Cloud Connector) Role Service instance Manage destinations (all CRUD opera tions) on service instance level (cock pit) One of these roles: ● Org Manager ● Space Manager ● Space Developer See User and Member Management. View destinations (read operations) on service instance level (cockpit) Manage certificates (all CRUD opera tions) on service instance level (cock pit) View certificates (read operations) on service instance level (cockpit) Back to Technical Roles [page 10] Back to User Roles [page 9] Technical Roles [Feature Set B] Feature set B provides dedicated roles for specific operations. They can be assigned to custom role collections, but some of them are also available in default role collections. Technical Connectivity Roles and Operations [Feature Set B] [page 11] Default Role Collections [Feature Set B] [page 13] Note To see the Destination editor, you must have at least the Destination Viewer role or both the Destination Configuration Viewer and the Destination Certificate Viewer roles. Technical Connectivity Roles and Operations [Feature Set B] Level Operation (SAP BTP Cockpit or Cloud Connector) Role Subaccount Connect a Cloud Connector to a sub account (Cloud Connector) Cloud Connector Administrator Manage destinations (all CRUD opera tions) on subaccount level (cockpit) One of these roles: ● Destination Administrator ● Destination Configuration Adminis trator View destinations (read operations) on subaccount level (cockpit) One of these roles: ● Destination Viewer ● Destination Configuration Viewer SAP BTP Connectivity Connectivity PUBLIC 11
- 12. Level Operation (SAP BTP Cockpit or Cloud Connector) Role Manage certificates (all CRUD opera tions) on subaccount level (cockpit) One of these roles: ● Destination Administrator ● Destination Certificate Administra tor View certificates (read operations) on subaccount level (cockpit) One of these roles: ● Destination Viewer ● Destination Certificate Viewer Generate or renew the subaccount key pair for trust management (cock pit) One of these roles: ● Destination Administrator ● Destination Subaccount Trust Ad ministrator Download the subaccount key pair for trust management (cockpit) One of these roles: ● Destination Viewer ● Destination Subaccount Trust Viewer Service instance Manage destinations (all CRUD opera tions) on service instance level (cock pit) One of these roles: ● Destination Administrator ● Destination Configuration Adminis trator plus one of these roles: ● Org Manager ● Space Manager ● Space Developer See User and Member Management. View destinations (read operations) on service instance level (cockpit) One of these roles: ● Destination Viewer ● Destination Configuration Viewer plus one of these roles: ● Org Manager ● Space Manager ● Space Developer See User and Member Management. 12 PUBLIC SAP BTP Connectivity Connectivity
- 13. Level Operation (SAP BTP Cockpit or Cloud Connector) Role Manage certificates (all CRUD opera tions) on service instance level (cock pit) One of these roles: ● Destination Administrator ● Destination Certificate Administra tor plus one of these roles: ● Org Manager ● Space Manager ● Space Developer See User and Member Management. View certificates (read operations) on service instance level (cockpit) One of these roles: ● Destination Viewer ● Destination Certificate Viewer plus one of these roles: ● Org Manager ● Space Manager ● Space Developer See User and Member Management. Back to Technical Roles [Feature Set B] [page 11] Default Role Collections [Feature Set B] Default Role Collection Connectivity Roles Included Subaccount Administrator ● Cloud Connector Administrator ● Destination Administrator Subaccount Viewer ● Cloud Connector Auditor ● Destination Viewer Cloud Connector Administrator Cloud Connector Administrator Destination Administrator Destination Administrator Connectivity and Destination Administrator ● Cloud Connector Administrator ● Destination Administrator Back to Technical Roles [Feature Set B] [page 11] Back to Technical Roles [page 10] Back to User Roles [page 9] Back to Content [page 8] SAP BTP Connectivity Connectivity PUBLIC 13
- 14. Related Information What's New for Connectivity [page 14] Initial Setup [page 38] Developing Applications [page 164] Security [page 266] Monitoring and Troubleshooting [page 266] Security Administration: Managing Authentication and Authorization 1.1.2 What's New for Connectivity Find the latest features, enhancements and bug fixes for SAP BTP Connectivity . What's New for Connectivity Related Information 2020 Connectivity (Archive) [page 14] 2019 Connectivity (Archive) [page 23] 2018 Connectivity (Archive) [page 30] 2017 Connectivity (Archive) [page 34] 1.1.2.1 2020 Connectivity (Archive) 14 PUBLIC SAP BTP Connectivity Connectivity
- 15. 2020 Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Cloud Foun dry Java Connec tor (JCo) - Client Certifi- cates JCo provides the new property jco.client.tls_client_certificate_logon to support the usage of a TLS client certificate for logging on to an ABAP system via WebSocket RFC. For more information, see: User Logon Properties (Cloud Foundry environment) User Logon Properties (Neo environment) For more information on WebSocket RFC, see also: WebSocket RFC New 2020-1 2-17 Con nectiv ity Inte gration Suite Cloud Foun dry HTTP Destina tions - Authenti cation Types Authentication type SAP Assertion SSO is deprecated. It will soon be removed as a feature from the Destination service. Use Principal Propagation SSO Authentication instead, which is the recommended mechanism for establishing single sign-on (SSO). Depre cated 2020-1 2-17 Con nectiv ity Inte gration Suite Neo HTTP Destina tions - Authenti cation Types Authentication type SAP Assertion SSO is deprecated. Use Principal Propagation SSO Authentication instead, which is the recommended mechanism for establishing single sign-on (SSO). Depre cated 2020-1 2-17 Con nectiv ity Inte gration Suite Cloud Foun dry HTTP Destina tions - Destina tion Proper ties The destination property SystemUser for the authentication types: ● OAuth SAML Bearer Assertion Authentication ● SAP Assertion SSO Authentication will be removed soon. More information on timelines and re quired actions will be published in the release notes at a later stage. See also: OAuth SAML Bearer Assertion Authentication SAP Assertion SSO Authentication An nounce ment 2020-1 2-03 SAP BTP Connectivity Connectivity PUBLIC 15
- 16. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Cloud Foun dry JCo Run time - Enhance ment JCo Runtime 3.1.3.0 introduces the following enhancement: If the backend is known to be new enough, JCo does not check for the existence of RFC_METADATA_GET, thus avoiding the need to provide additional authorizations for the repository user. New 2020-1 1-05 Con nectiv ity Inte gration Suite Neo Cloud Foun dry JCo Run time - Bug Fix JCo Runtime 3.1.3.0 provides the following bug fix: Up to JCo 3.1.2, the initial value for fields of type STRING and XSTRING was null. Since the initial value check in ABAP is differ- ent, JCo now behaves the same way and uses an emtpy string and an empty byte array, respectively. Chang ed 2020-1 1-05 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Auto matic To ken Re trieval The Destination service offers a new feature related to the auto matic token retrieval functionality, which lets the destination ad ministrator define HTTP headers and query parameters as addi tional configuration properties, used at runtime when requesting the token service to obtain an access token. See HTTP Destinations. New 2020-1 1-05 Con nectiv ity Inte gration Suite Cloud Foun dry Docu menta tion - Principal Propaga tion Sce narios The documentation of principal propagation (user propagation) scenarios provides improved information on the basic concept and guidance on how to set up different scenarios. See Principal Propagation. Chang ed 2020-1 0-22 Con nectiv ity Inte gration Suite Cloud Foun dry Cloud Connec tor 2.12.5 - En hance ments Release of Cloud Connector version 2.12.5 introduces the follow ing improvements: ● For principal propagation scenarios, custom attributes stored in xs.user.attributes of the JWT (JSON Web token) are now accessible for the subject pattern. See Con figure a Subject Pattern for Principal Propagation. ● Improved resolving for DNS names with multiple IP ad dresses by adding randomness to the choice of the IP to use. This is relevant for many connectivity endpoints in SAP Cloud Platform, Cloud Foundry environment. New 2020-1 0-22 16 PUBLIC SAP BTP Connectivity Connectivity
- 17. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12.5 - Fixes Release of Cloud Connector version 2.12.5 provides the following bug fixes: ● After actively performing a master-shadow switch for a dis aster recovery subaccount, a zombie connection could cause a timeout of all application requests to on-premise systems. This issue has been fixed. ● When refreshing the subaccount certificate in an high avail ability setup, transferring the changed certificate to the shadow was not immediately triggered, and the updated certificate could get lost. This issue has been fixed. ● If many RFC connections were canceled at the same time, the Cloud Connector could crash in the native layer, causing the process to die. This issue has been fixed. ● The LDAP configuration test now supports all possible con figuration parameters. Chang ed 2020-1 0-22 Con nectiv ity Inte gration Suite Cloud Foun dry Connec tivity Service - Service Instan ces - Quota Manage ment When using service plan “lite” , quota management is no longer required for this service. From any subaccount you can consume the service using service instances without restrictions on the in stance count. Previously, access to service plan “lite” has been granted via en titlement and quota management of the application runtime. It has now become an integral service offering of SAP Cloud Plat form to simplify its usage. See also Create and Bind a Connectivity Service Instance. Chang ed 2020-1 0-08 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Service Instan ces - Quota Manage ment When using service plan “lite” , quota management is no longer required for this service. From any subaccount you can consume the service using service instances without restrictions on the in stance count. Previously, access to service plan “lite” has been granted via en titlement and quota management of the application runtime. It has now become an integral service offering of SAP Cloud Plat form to simplify its usage. See also Create and Bind a Destination Service Instance. Chang ed 2020-1 0-08 SAP BTP Connectivity Connectivity PUBLIC 17
- 18. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Cloud Foun dry SAP Java Build pack - Java Connec tor (JCo) The SAP Java Buildpack has been updated from 1.27.3. to 1.28.0. ● TomEE Tomcat has been updated from 7.0.104 to 7.0.105. ● SAPJVM has been updated to 81.65.65. ● The com.sap.cloud.security.xsuaa API has been updated from 2.7.5 to 2.7.6. ● The SAP HANA driver has been updated from 2.5.49 to 2.5.52. ● JCo-corresponding libraries have been updated: connec tivity to 3.3.3, connectivity apiext to 0.1.37. ● The activation process for the JCo component in the SAP Java Buildpack has been changed. Starting with this re lease, it is activated by setting the following environment variable: <USE_JCO=true>. Note The previous activation process for the JCo compo nent is deprecated and will expire after a transition period. Chang ed 2020-0 9-24 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Error Handling Error handling has been improved for updating service instances via the Cloud Foundry CLI and the cloud cockpit when providing the configuration JSON data. Chang ed 2020-0 9-10 Con nectiv ity Inte gration Suite Neo Connec tivity Service - Bug Fix A synchronization issue has been fixed on cloud side that in very rare cases could lead to a zombie tunnel from the Cloud Connec tor to SAP Cloud Platform, which required to reconnect the Cloud Connector. Chang ed 2020-0 9-10 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Bug Fix During Check Connection processing of a destination with basic authentication, the Destination service now uses the user cre dentials for both the HTTP HEAD and HTTP GET requests to ver ify the connection on HTTP level. Chang ed 2020-0 9-10 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Bug Fix Using authentication type OAuth2SAMLBearerAssertion, an issue could occur when adding the user's SAML group attrib utes into the resulting SAML assertion that is sent to the target token service. This issue has been fixed. Chang ed 2020-0 8-13 18 PUBLIC SAP BTP Connectivity Connectivity
- 19. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service REST API - Pagina tion Fea ture The REST API pagination feature provides improved error han dling in case of issues with the pagination, for example, if an in valid page number is provided. Chang ed 2020-0 8-13 Con nectiv ity Inte gration Suite Neo HttpDes tination Library - New Ver sion The HttpDestination v2 library has been officially released in the Maven Central Repository . It enables the usage in Tom cat and TomEE-based runtimes the same way as in the depre cated JavaWeb and Java EE 6 Web Profile runtimes. See also HttpDestination Library. New 2020-0 7-30 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Bug Fix An error handling issue has been fixed in the Destination service, which is related to the recently introduced SAP Assertion SSO authentication type. If a wrong input was provided, you can now see the error properly, and recover it. Chang ed 2020-0 7-30 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tions - Authenti cation Types You can use authentication type OAuth2JWTBearer when configuring a Destination. It is a simplified version of the authen tication type OAuth2UserTokenExchange and represents the official OAuth grant type for exchanging OAuth tokens. See HTTP Destinations. New 2020-0 7-02 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - HTTP Header The Destination service provides a prepared HTTP header that simplifies application and service development. See HTTP Desti nations (code samples). New 2020-0 7-02 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Bug Fix A concurrency issue in the Destination service, related to parallel auth token retrieval in the token cache functionality, could result in partial request failures. This issue has been fixed. Chang ed 2020-0 7-02 Con nectiv ity Inte gration Suite Cloud Foun dry HTTP Destina tions - Authenti cation Types The Cloud Foundry environment supports SAP Assertion SSO as authentication type for configuring destinations in the Destination service. See HTTP Destinations. New 2020-0 6-18 SAP BTP Connectivity Connectivity PUBLIC 19
- 20. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service REST API The "Find Destination" REST API now includes the scopes of the automatically retrieved access token in the response that is re turned to the caller. See "Find Destination" Response Structure. New 2020-0 6-04 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tions for Service Instan ces For subscription-based scenarios, you can use an automated procedure to create a destination that points to your service in stance. See Managing Destinations. New 2020-0 6-04 Con nectiv ity Inte gration Suite Neo Cloud Foun dry Connec tivity Service - Bug Fix In rare cases, establishing a secure tunnel between Cloud Con nector (version 2.12.3 or older) and the Connectivity service could cause an issue that requires to manually disconnect and connect the Cloud Connector. This issue has been fixed. The fix requires Cloud Connector ver sion 2.12.4 or higher. Chang ed 2020-0 5-21 Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12.4 - Fea tures Release of Cloud Connector version 2.12.4 introduces the follow ing features and enhancements: ● You can activate the SSL trace in the Cloud Connector ad ministration UI also for the shadow instance. New 2020-0 5-07 Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12.4 - Fixes Release of Cloud Connector version 2.12.4 provides the following bug fixes: ● You can edit and delete domain mappings in the Cloud Con nector administration UI correctly. ● The REST API does no longer return an empty configura- tion. ● REST API DELETE operations do not require setting a con tent-type application/json to function properly. ● If more than 2000 audit log entries match a selection, rede fining the search and getting a shorter list now works as ex pected. ● A potential leak of HTTP backend connections has been closed. Chang ed 2020-0 5-07 Con nectiv ity Inte gration Suite Cloud Foun dry Connec tivity Service - Bug Fix A fix has been applied in the Connectivity service internal load balancers, enabling the sending of TCP keep-alive packets on cli ent and server side. This change mainly affects SOCKS5-based communication scenarios. Chang ed 2020-0 3-26 20 PUBLIC SAP BTP Connectivity Connectivity
- 21. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Service Instan ces You can create a service instance specifying an update policy. This allows you to avoid name conflicts with existing destina tions. See Create and Bind a Destination Service Instance. New 2020-0 3-26 Con nectiv ity Inte gration Suite Cloud Foun dry Cockpit - Destina tion Manage ment The Destinations editor in the cockpit is available for accounts running on the cloud management tools feature set B. See Man aging Destinations. New 2020-0 3-12 Con nectiv ity Inte gration Suite Neo Connec tivity Service - Bug Fix When creating or editing a destination with authentication type OAuth2ClientCredentials in the cockpit, the parameter Audience could not be added as additional property. This is sue has been fixed. Chang ed 2020-0 3-12 Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12.3 - Fea tures Release of Cloud Connector version 2.12.3 introduces the follow ing features and enhancements: ● When using the SAP JVM as runtime, the thread dump in cludes additional information about currently executed RFC function modules. ● The hardware monitor includes a Java Heap history, show ing the usage in the last 24 hours. ● If you are using the file scc_daemon_extension.sh to extend the daemon in a Linux installation, the content is in cluded in the initialization section of the daemon. This lets you make custom extensions to the daemon that survive an upgrade. See Installation on Linux OS, section Installer Sce nario. New 2020-0 2-27 SAP BTP Connectivity Connectivity PUBLIC 21
- 22. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12.3 - Fixes Release of Cloud Connector version 2.12.3 provides the following bug fixes: ● When switching roles between master and shadow instance in a high availability setup, the switch is no longer blocked by active RFC function module invocations. ● A fix in the backend HTTP connection handling prevents is sues when the backend tries to send the HTTP response be fore completely reading the HTTP request. ● When sending large amounts of data to an on-premise sys tem, and using RFC with a network that provides large band width, the Cloud Connector could fail with the error mes sage Received invalid block with negative size. This issue has been fixed. ● The Cloud Connector admin UI now shows the correct user information for installed Cloud Connector instances in the About window. ● Fixes in the context of disaster recovery: ○ The location ID is now handled properly when setting it after adding the recovery subaccount. ○ Application trust settings and application-specific con nections are applied in the disaster case. ○ Principal propagation settings are applied in the disas ter case Chang ed 2020-0 2-27 Con nectiv ity Inte gration Suite Neo Cloud Foun dry JCo Run time - Web Socket RFC The JCo runtime in SAP Cloud Platform lets you use WebSocket RFC (RFC over Internet) with ABAP servers as of S/4HANA (on- premise) version 1909. In the RFC destination configuration, this is reflected by new configuration properties and by the option to choose between different proxy types. See Target System Configuration (Cloud Foundry environment), or Target System Configuration (Neo environment). New 2020-0 2-13 Con nectiv ity Inte gration Suite Cloud Foun dry Connec tivity Service for Trial Accounts - Bug Fix The Connectivity service is operational again for trial accounts. A change in the Cloud Foundry Core component caused the serv ice not be accessible by applications hosted in DiegoCell that are dedicated for trial usage in a separate VPC (virtual private cloud) account. This issue has been fixed. Chang ed 2020-0 1-30 22 PUBLIC SAP BTP Connectivity Connectivity
- 23. 1.1.2.2 2019 Connectivity (Archive) 2019 Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12.2 - Fea tures Release of Cloud Connector version 2.12.2 introduces the follow ing features and enhancements: ● You can turn on the TLS trace from the Cloud Connector ad ministration UI instead of modifying the props.ini file on OS level. See Troubleshooting. ● The status of the used subaccount certificate is shown on the Subaccount overview page of the Cloud Connector ad ministration UI, in addition to expiring certificates shown in the Alerting view. See Establish Connections to SAP Cloud Platform. New 2019-1 2-05 Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12.2 - Fixes Release of Cloud Connector version 2.12.2 provides the following bug fixes: ● Subject values for certificates requiring escaping are treated correctly. ● Establishing a connection to the master is now possible when being logged on to the shadow with a user that has a space in its name. ● Performance statistics could show too long total execution times. This issue has been fixed. ● IP address changes for the connectivity service hosts are recognized properly. ● The Cloud Connector could crash on Windows, when trying to enable the payload trace with 4-eyes-principle without the required user permissions. This issue has been fixed. Chang ed 2019-1 2-05 Con nectiv ity Inte gration Suite Cloud Foun dry Connec tivity Service - Bug Fix Applications sending a significant amount of data payload during OAuth authorization processing could cause an out-of-memory error on the Connectivity service side. This issue has been fixed. Chang ed 2019-11 -21 SAP BTP Connectivity Connectivity PUBLIC 23
- 24. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Region Europe (Frank furt) - Change of Con nectivity Service Hosts The following IP addresses of the Connectivity service hosts for region Europe/Frankfurt (eu2.hana.ondemand.com) will change on 26 October 2019: ● connectivitynotification.eu2.hana.ondema nd.com: from 157.133.70.140 (current) to 157.133.206.143 (new) ● connectivitycertsigning.eu2.hana.ondeman d.com: from 157.133.70.132 (current) to 157.133.205.174 (new) ● connectivitytunnel.eu2.hana.ondemand.com: from 157.133.70.141 (current) to 157.133.205.233 (new) If you have allowed the current addresses or IP ranges in your firewall rules, make sure you also include the new values before 26 October 2019. See also: Prerequisites: Network. An nounce ment 2019-1 0-03 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Connec tion Check Using the Destinations editor in the cockpit, you can check con nections also for on-premise destinations. See Check the Availability of a Destination. Chang ed 2019-0 9-26 Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor - Java Runtime The support for using Cloud Connector with Java runtime ver sion 7 will end on December 31, 2019. Any Cloud Connector ver sion released after that date may contain Java byte code requir ing at least a JVM 8. We therefore strongly recommend that you perform fresh instal lations only with Java 8, and update existing installations run ning with Java 7, to Java 8 as of now. See SAP Cloud Connector – Java 7 support will phase out and Update the Java VM. An nounce ment 2019-0 9-13 24 PUBLIC SAP BTP Connectivity Connectivity
- 25. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12.1 - Fea tures Release of Cloud Connector version 2.12.1 introduces the follow ing features and enhancements: ● Subject Alternative Names are separated from the subject definition and provide enhanced configuration options. You can configure complex values easily when creating a certifi- cate signing request. See Exchange UI Certificates in the Administration UI. ● In a high availability setup, the master instance detection no longer switches automatically if the configuration between the two instances is inconsistent. ● Disaster recovery switch back to main subaccount is period ically checked (if not successful) every 6 hours. ● Communication to on-premise systems supports SNI (Server Name Indication). New 2019-0 8-15 Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12.1 - Fixes Release of Cloud Connector version 2.12.1 provides the following bug fixes: ● The communication between master and shadow instance no longer ends up in unusable clients that show 403 results due to CSRF (Cross-Site Request Forgery) failures, which could cause undesired role switches. ● When restoring a backup, the administrator password check works with all LDAP servers. ● The LDAP configuration test utility properly supports secure communication. ● The Refresh Subaccount Certificate dialog is no longer hanging when the refresh action fails due to some authenti cation or authorization issue. Chang ed 2019-0 8-15 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Scope Attribute for OAuth- based Authenti cation Types You can use the scope destination attribute for the OAuth- based authentication types OAuth2ClientCredentials, OAuth2UserTokenExchange and OAuth2SAMLBearerAssertion. This additional attribute provides flexibility on destination configuration level, letting you specify what scopes are selected when the OAuth access token is automatically retrieved by the service. See HTTP Destinations. New 2019-0 8-15 SAP BTP Connectivity Connectivity PUBLIC 25
- 26. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo JCo Run time for SAP Cloud Platform - Fea tures ● Additional APIs have been added to JCoBackgroundUnitAttributes. See API documen tation for details. ● If a structure or table contains only char-like fields, new APIs let you read or modify all of them at once for the struc ture or the current table row. See API documentation of JCoTable and JCoStructure. New 2019-0 7-18 Con nectiv ity Inte gration Suite Neo JCo Run time for SAP Cloud Platform - Fixes ● qRFC and tRFC requests sent to an ABAP system by JCo can be monitored again by AIF. ● Structure fields of type STRING are no longer truncated if there is a white space at the end of the field. Chang ed 2019-0 7-18 Con nectiv ity Inte gration Suite Cloud Foun dry Connec tivity Service - JCo Mul titenancy The Connectivity service supports multitenancy for JCo applica tions. This feature requires a runtime environment with SAP Java Buildpack version 1.9.0 or higher. See Scenario: Multitenancy for JCo Applications (Advanced). New 2019-0 6-20 Con nectiv ity Inte gration Suite Cloud Foun dry Cloud Cockpit - Cloud Connec tor View The Cloud Connector view is available also for Cloud Foundry re gions. It lets you see which Cloud Connectors are connected to a subaccount. New 2019-0 4-25 26 PUBLIC SAP BTP Connectivity Connectivity
- 27. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12 - Features Release of Cloud Connector version 2.12 introduces the following features and enhancements: ● The administration UI is now accessible not only with an ad ministrator role, but also with a display and a support role. See Configure Named Cloud Connector Users and Use LDAP for Authentication. ● For HTTP access control entries, you can ○ allow a protocol upgrade, e.g. to WebSockets, for ex posed resources. See Limit the Accessible Services for HTTP(S). ○ define which host (virtual or internal) is sent in the host header. See Expose Intranet Systems, Step 8. ● A disaster recovery subaccount in disaster recovery mode can be converted into a standard subaccount, if a disaster recovery region replaces the original region permanently. See Convert a Disaster Recovery Subaccount into a Stand ard Subaccount. ● A service channel overview lets you check at a glance, which server ports are used by a Cloud Connector installation. See Service Channels: Port Overview. ● Important subaccount configuration can be exported, and imported into another subaccount. See Copy a Subaccount Configuration. ● An LDAP authentication configuration check lets you ana lyze and fix configuration issues before activating the LDAP authentication. See Use LDAP for Authentication. ● You can use different user roles to access the Cloud Con nector configuration REST APIs. See Configuration REST APIs. ● REST APIs for shadow instance configuration have been added. See Shadow Instance Configuration. ● You can define scenarios for resources. Such a scenario can be exported, and imported into other hosts. See Configure Accessible Resources. New 2019-0 4-25 SAP BTP Connectivity Connectivity PUBLIC 27
- 28. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.12 - Fixes Release of Cloud Connector version 2.12 provides the following bug fixes: ● The SAN (subjectAlternativeName) usage in certificates can be defined in a better way and is stored correctly in the cer tificate. See Exchange UI Certificates in the Administration UI. ● IllegalArgumentException does not occur any more in HTTP processing, if the backend closes a connec tion and data are streamed. ● DNS caching is now recognized in reconnect situations if the IP of a DNS entry has changed. ● SNC with load balancing now works correctly for RFC SNC- based access control entries. ● A master-master situation is also recognized if, at startup of the former master instance, the new master (the former shadow instance) is not reachable. ● Solution management model generation works correctly for a shadow instance. ● The daemon is started properly on SLES 12 standard instal lations at system startup. Chang ed 2019-0 4-25 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Authenti cation Types Authentication type OAuth2SAMLBearerAssertion pro vides two different types of Token Service URL: ● Dedicated: used in the context of a single tenant, or ● Common: used in the context of multiple tenants. For type Common, the tenant subdomain is automatically set to the target Token Service URL. In addition, cloud applications can use the x-user-token HTTP header to propagate the user access token to the external target service at runtime. By default, the user principal is proc essed via the authorization HTTP header. See SAML Bearer Assertion Authentication. New 2019-0 4-11 Con nectiv ity Inte gration Suite Neo Cloud Foun dry Connec tivity Service - Fix When an on-premise system closed a connection that uses an RFC or SOCKS5 proxy, the Connectivity service kept the connec tion to the cloud application alive. This issue has been fixed. The connection is now always closed right after sending the response. Chang ed 2019-0 4-11 28 PUBLIC SAP BTP Connectivity Connectivity
- 29. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Cloud Foun dry Connec tivity Service - Proto cols The Connectivity service supports TCP connections to on-prem ise systems, exposing a SOCKS5 proxy to cloud applications. This feature follows the concept of binding the credentials of a Connectivity service instance. See Using the TCP Protocol for Cloud Applications. New 2019-0 3-14 Con nectiv ity Inte gration Suite Neo Connec tivity Service - Fix After receiving an on-premise system response with HTTP header Connection: close, the Connectivity service kept the HTTP connection to the cloud application alive. This issue has been fixed. The connection is now always closed right after sending the response. Chang ed 2019-0 3-14 Con nectiv ity Inte gration Suite Neo Cloud Connec tor - Cer tificate Update For the Connectivity service (Neo environment), a new, region- specific certificate authority (X.509 certificate) is being intro duced. If you use the Cloud Connector for on-premise connections to the Neo environment, you must import the new certificate au thority into your trust configuration. ● After the next month (concrete notification will be rolled out), the current certificate authority will no longer be used to issue client certificates for Cloud Connector deploy ments, and only the new one will be used. The Connectivity service will still trust client certificates of Cloud Connector deployments that were already issued. ● After a three-month period (concrete notification will be rolled out), that trust will be removed and your Cloud Con nector deployment must be configured to use the new client certificates. See Update the Certificate for a Subaccount. An nounce ment 2019-0 2-28 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tion Service - Authenti cation Types The new authentication type OAuth2UserTokenExchange lets your applications use an automated exchange of user access tokens when accessing other applications or services. The fea ture supports single-tenant and multi-tenant scenarios. See OAuth User Token Exchange Authentication. New 2019-0 2-14 Con nectiv ity Inte gration Suite Neo RFC - Stateful Sequen ces You can make a stateful sequence of function module invoca tions work across several request/response cycles. See Invoking ABAP Function Modules via RFC. Chang ed 2019-0 1-31 SAP BTP Connectivity Connectivity PUBLIC 29
- 30. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Inte gration Suite Neo Cloud Foun dry Cloud Connec tor 2.11.3 A security note for Cloud Connector version 2.11.3 has been is sued. See SAP note 2696233 . Chang ed 2019-0 1-15 Con nectiv ity Inte gration Suite Cloud Foun dry Proto cols - RFC Commu nication You can use the RFC protocol to set up communication with on- premise ABAP systems for applications in the Cloud Foundry en vironment. This feature requires a runtime environment with SAP Java Buildpack version 1.8.0 or higher. See Invoking ABAP Function Modules via RFC. New 2019-0 1-17 Con nectiv ity Inte gration Suite Cloud Foun dry Destina tions - Renew Certifi- cates A button in the Destinations editor lets you update the validity period of an X.509 certificate. See Set up Trust Between Sys tems. New 2019-0 1-17 1.1.2.3 2018 Connectivity (Archive) 2018 Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Integra tion Neo Con nectiv ity Service - Per for mance A change in the SAP Cloud Platform Connectivity service im proves performance of data upload (on-premise to cloud) and data download (cloud to on-premise) up to 4 times and 15-30 times respectively. Chang ed 2018-1 2-20 30 PUBLIC SAP BTP Connectivity Connectivity
- 31. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Integra tion Neo Con nectiv ity Service - Resil ience The Connectivity service has a better protection against zombie connections, which improves resilience and overall availability for the cloud applications consuming it. Chang ed 2018-1 2-20 Con nectiv ity Integra tion Neo Pass word Stor age Service A Password Storage REST API is available in the SAP API Business Hub, see Password Storage (Neo Environment) . New 2018-1 2-06 Con nectiv ity Integra tion Neo Desti nation Config- uration Service A Destination Configuration service REST API is available in the SAP API Business Hub. New 2018-1 2-06 Con nectiv ity Integra tion Cloud Foun dry Desti nation Service A Destination service REST API is available in the SAP API Business Hub. New 2018-1 2-06 Con nectiv ity Integra tion Neo JCo Run time for SAP Cloud Plat form - Fixes ● When using JCoRecord.fromJSON() for a structure pa rameter, the data is now always sent to the backend system. Also, you do not need to append the number of provided rows for table parameters before parsing the JSON document any more. ● Depending on the configuration of certain JCo properties, an internally managed connection pool could throw a JCoException (error group JCO_ERROR_RESOURCE). In a thread waiting for a free connection from this pool, an er ror message then erroneously reported that the pool was ex hausted . This error situation could occur if the used destination was not configured with the property jco.destination.max_get_client_time set to 0 and the destination's jco.destination.peak_limit value was set higher than the jco.destination.pool_capacity. This issue has been fixed. Chang ed 2018-1 2-06 SAP BTP Connectivity Connectivity PUBLIC 31
- 32. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Integra tion Neo JCo Run time for SAP Cloud Plat form - Fea tures Support of the RFC fast serialization. Depending on the exchanged parameter and data types, the performance improvements for RFC communication can reach multiple factors. See SAP note 2372888 (prerequisites) and Parameters Influ- encing Communication Behavior (JCo configuration in SAP Cloud Platform). Chang ed 2018-1 2-06 Con nectiv ity Integra tion Neo JCo Run time for SAP Cloud Plat form - Infor mation Local runtimes on Windows must install the VS 2013 redistributa bles for x64, instead of VS 2010. Chang ed 2018-1 2-06 Con nectiv ity Integra tion Neo Cloud Foun dry Cloud Con nector Fixes Release of Cloud Connector 2.11.3: ● An issue in RFC communication could cause the trace entry com.sap.scc.jni.CpicCommunicationException: no SAP ErrInfo available when the network is slow. This issue has been fixed. ● The Windows service no longer runs in error 1067 when stop ped by an administrator. ● In previous releases, the connection between a shadow and a master instance occasionally failed at startup and produced an empty error message. This issue has been fixed. ● The Cloud Connector does not cache Kerberos tokens in the protocol handler any more, as they are one-time tokens and cannot be reused. ● For HTTP access control entries, you can configure resources containing a # character. Chang ed 2018-1 2-06 32 PUBLIC SAP BTP Connectivity Connectivity
- 33. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Integra tion Neo Cloud Foun dry Cloud Con nector En hance ments Release of Cloud Connector 2.11.3: ● If the user sapadm exists on a system, the installation on Li nux assigns it to the sccgroup, which is a prerequisite for sol ution management integration to work properly, see Config- ure Solution Management Integration [page 494]. ● Restoring a backup has been improved. See Configuration Backup [page 498]. ● The HTTP session store size has been reduced. You can han dle higher loads with a given heap size. ● Cipher suite configuration has been improved. Also, there is a new security status entry for cipher suites, see Recommen dations for Secure Setup [page 299]. Chang ed 2018-1 2-06 Con nectiv ity Integra tion Neo HTTP Desti nations The OAuth2 Client Credentials grant type is supported by the Destinations editor in the SAP Cloud Platform cockpit as well as by the client Java APIs ConnectivityConfiguration, AuthenticationHeaderProvider and HttpDestination, available in SAP Cloud Platform Neo run times. See OAuth Client Credentials Authentication. Chang ed 2018-1 0-11 Con nectiv ity Integra tion Cloud Foun dry User Propa gation The connectivity service supports the SaaS application subscrip tion flow and can be declared as a dependency in the get depend encies subscription callback, also via MTA (multi-target)-bundled applications. See Consuming the Connectivity Service (Cloud Foundry Environ ment) and Configure Principal Propagation via User Exchange To ken (Cloud Foundry Environment). Chang ed 2018-0 9-27 Con nectiv ity Integra tion Neo Cloud Foun dry Cloud Con nector 2.11.2 Release of Cloud Connector 2.11.2 ● SNC configuration now provides the value of the environment variable SECUDIR, which you need for the usage of the SAP Cryptographic Library (SAPCRYPTOLIB). See Initial Configu- ration (RFC). ● On Linux, the RPM (Red Hat Package Manager) now ensures that the configuration of the interaction with the SAP Host Agent (used for the Solution Manager integration) is ad justed. See Configure Solution Management Integration. ● The Cloud Connector shadow instance now provides a config- uration option for the connection and request timeout that may occur during health check against the master instance. See Master and Shadow Administration. Chang ed 2018-0 8-16 SAP BTP Connectivity Connectivity PUBLIC 33
- 34. Techni cal Com ponent Capa bility Envi ron ment Title Description Type Availa ble as of Con nectiv ity Integra tion Neo Cloud Foun dry Cloud Con nector 2.11.2 Fixes of Cloud Connector 2.11.2 ● In a high availability setup, the switch from the master in stance to the shadow instance occasionally caused commu nication errors towards on-premise systems. This issue has now been fixed. ● You can now import multiple certificates with the same sub ject to the trust store. Details about expiration date and is suer are displayed in the tool tip. See Set Up Trust, section Trust Store. ● You can now configure also the MOC (Multiple Origin Compo sition) OData service paths as resources. ● The Location header is now adjusted correctly according to your access control settings in case of a redirect. ● Principal propagation now also works with SAML assertions that contain an empty attribute element. ● SAP Cloud Platform applications occasionally got an HTTP 500 (internal server error) response when an HTTP connec tion was closed. The applications are now always informed properly. Chang ed 2018-0 8-16 Con nectiv ity Integra tion Neo HttpDe stina tion Li brary The SAP HttpDestination library (available in the SDK and cloud runtime "Java EE 6 Web Profile") now creates Apache HttpClient instances which work with strict SNI (Server Name Indication) servers. Use cases with strict SNI configuration on the server side will no longer get the error message Failure reason: "peer not authenti cated", that was raised either at runtime or while performing a connection test via the SAP Cloud Platform cockpit Destinations editor (Check Connection function). Chang ed 2018-0 8-16 1.1.2.4 2017 Connectivity (Archive) Archived release notes for 2017 and older. 34 PUBLIC SAP BTP Connectivity Connectivity
- 35. 28 September 2017 - Connectivity New The destination service (Beta) is available in the Cloud Foundry environment. See Consuming the Destination Service [page 189]. 3 August 2017 - Connectivity Enhancement Cloud Connector Release of SAP Cloud Platform Cloud Connector 2.10.1. ● The URLs of HTTP requests can now be longer than 4096 bytes. ● SAP Solution Manager can be integrated with one click of a button if the host agent is installed on a Cloud Connec tor machine. See the Solution Management section in Monitoring [page 516]. ● The limitation that only 100 subaccounts could be managed with the administration UI has been removed. See Man aging Subaccounts [page 328]. Fix Cloud Connector ● The regression of 2.10.0 has been fixed, as principal propagation now works for RFC. ● The cloud user store works with group names that contain a backslash () or a slash (/). ● Proxy challenges for NT LAN Manager (NTLM) authentication are ignored in favor of Basic authentication. ● The back-end connection monitor works when using a JVM 7 as a runtime of Cloud Connector. SAP BTP Connectivity Connectivity PUBLIC 35
- 36. 25 May 2017 - Connectivity Enhancement Cloud Connector Release of SAP HANA Cloud connector 2.10.0.1 ● Support of connectivity to an SAP Cloud Platform Cloud Foundry environment. ● Support of direct connectivity with S/4HANA Cloud systems. You can open a Service Channel to an S/4HANA Cloud system in order to use Communication Scenarios requiring RFC communication to S/4HANA Cloud. See Configure a Service Channel for RFC [page 487]. ● Support of arbitrary protocols via the possibility to configure a TCP access control entry. SAP Cloud Platform Con nectivity is offering a SOCKS5 proxy, with which you can address such exposed hosts. See Using the TCP Protocol for Cloud Applications. ● Support for disaster recovery events of SAP Cloud Platform regions. For each subaccount you can configure a dis aster recovery subaccount for a disaster region. In case of a disaster, the disaster recovery account can be switched active immediately using the exact same configuration. See Configure a Disaster Recovery Subaccount [page 336]. ● In the access control settings you can add further constraints for RFC based communication to ABAP systems: an administrator can configure, which clients shall be exposed and can define which users should not be able to access the system via Cloud Connector. See Configure Access Control (RFC) [page 377]. ● You can generate self-signed certificates for CA and system certificate so that you can setup demo scenarios with principal propagation without the need of using lengthy openSSL or keytool command sequences. See Configure a CA Certificate for Principal Propagation [page 344] and Initial Configuration (HTTP) [page 319]. ● A first set of monitoring HTTP APIs have been introduced: The state of all subaccount connections, a back-end con nection monitor and a performance overview monitor. See Monitoring APIs [page 524]. ● On Windows platforms, Cloud Connector 2.10 now requires Visual Studio 2013 runtime libraries. Fix Cloud Connector ● The is no longer a bottleneck that could lengthen the processing times of requests to exposed back-end systems, after many hours under high load when using principal propagation, connection pooling, and many concurrent ses sions. ● Session management is no longer terminating early active sessions in principal propagation scenarios. ● On Windows 10 hardware metering in virtualized environments shows hard disk and CPU data. 11 May 2017 - Connectivity New In case the remote server supports only TLS 1.2, use this property to ensure that your scenario will work. As TLS 1.2 is more secure than TLS 1.1, the default version used by HTTP destinations, consider switching to TLS 1.2. 36 PUBLIC SAP BTP Connectivity Connectivity
- 37. 30 March 2017 - Connectivity Enhancement The release of SAP Cloud Platform Cloud Connector 2.9.1 includes the following improvements: ● UI renovations based on collected customer feedback. The changes include rounding offs, fixes of wrong/odd be haviors, and adjustments of controls. For example, in some places tables were replaced by sap.ui.table.Table for bet ter experience with many entries. ● You can trigger the creation of a thread dump from the Log and Trace Files view. ● The connection monitor graphic for idle connections was made easier to understand. Fix ● When configuring authentication for LDAP, the alternate host settings are no longer ignored. ● The email configuration for alerts is processing correctly the user and password for access to the email server. ● Some servers used to fail to process HTTP requests when using the HTTP proxy approach (HTTP Proxy for On- Premise Connectivity) on the SAP Cloud Platform side. ● A bottleneck was removed that could lengthen the processing times of requests to exposed back-end systems un der high load when using principal propagation. ● The Cloud Connector accepts passwords that contain the '§' character when using authentication-mode password. 16 March 2017 - Connectivity Enhancement Update of JCo runtime for SAP Cloud Platform. See Connectivity [page 3]. Fix A java.lang.NullPointerException might have occurred when using a JCoRepository instance in roundtrip optimization mode (will be used if the JCo property jco.use_repository_roundtrip_optimization was set to 1 at its creation time). The NullPointerException was either thrown when trying to execute a JCoFunction object, which has been created by such a repository instance, or even earlier when querying the meta data for a JCoFunction, JCoFunctionTemplate or a JCoRecordMetaData object from an AS ABAP back-end system. Only certain complex data structures and table parameter definitions were affected by this bug. Older Release Notes ● 2016 ● 2015 ● 2014 SAP BTP Connectivity Connectivity PUBLIC 37
- 38. ● 2013 1.1.3 Initial Setup Manage destinations and authentication for applications in the Cloud Foundry environment. Task Description Managing Destinations [page 38] Manage HTTP destinations for Cloud Foundry applications in the SAP BTP cockpit. HTTP Destinations [page 64] You can choose from a broad range of authentication types for HTTP destinations, to meet the requirements of your specific communication scenario. RFC Destinations [page 110] Use RFC destinations to communicate with an on-premise ABAP system via the RFC protocol. Principal Propagation [page 121] Use principal propagation (user propagation) to securely for ward cloud users to a back-end system (single sign-on). Set up Trust Between Systems [page 124] Download and configure X.509 certificates as a prerequisite for user propagation from the Cloud Foundry environment to the Neo environment or to a remote system outside SAP BTP, like S/4HANA Cloud, C4C, Success Factors, and oth ers. Multitenancy in the Connectivity Service [page 156] Manage destinations for multitenancy-enabled applications that require a connection to a remote service or on-premise application. Create and Bind a Connectivity Service Instance [page 159] To use the Connectivity service in your application, you must first create and bind an instance of the service. Create and Bind a Destination Service Instance [page 161] To use the Destination service in your application, you must first create and bind an instance of the service. 1.1.3.1 Managing Destinations To manage destinations for your application, choose a procedure that fits best your requirements. There are various ways to manage destinations. Each method is characterized by different prerequisites and limitations. Before choosing a method, you should evaluate them and decide which one is the most appropriate for your particular scenario. The following table compares the available methods: 38 PUBLIC SAP BTP Connectivity Connectivity
- 39. Method Create from Scratch Create from Tem plate Create from File (Import) Save to File (Export) Update Delete Clone Check Con nection Using the Destina tions Editor in the Cock pit [page 39] Yes Yes Yes Yes Yes Yes Yes Yes Destination Service REST API [page 59] Yes No Yes Yes Yes Yes No No Create Des tinations Using the MTA De scriptor [page 59] Yes Limited No No Yes No No No Create Des tinations on Service In stance Cre ation [page 63] Yes No No No Yes No No No 1.1.3.1.1 Using the Destinations Editor in the Cockpit Use the Destinations editor in the SAP BTP cockpit to configure HTTP, RFC or mail destinations in the Cloud Foundry environment. The Destinations editor lets you manage destinations on subaccount or service instance level. You can use a destination to: ● Connect your Cloud Foundry application to the Internet (via HTTP), as well as to an on-premise system (via HTTP or RFC). ● Send and retrieve e-mails, configuring a mail destination. ● Create a destination for subscription-based scenarios, pointing to your service instance. For more information, see Destinations Pointing to Service Instances [page 51]. Prerequisites 1. You are logged into the SAP BTP cockpit. 2. You have the required authorizations. See User Roles [page 9]. SAP BTP Connectivity Connectivity PUBLIC 39
- 40. 3. Make sure the following is fulfilled: ○ Service instance level – you must have created a Destination service instance, see Create and Bind a Destination Service Instance [page 161]. ○ Subaccount level – no specific prerequisites. For more information, see Access the Destinations Editor [page 40]. Restrictions ● A destination name must be unique for the current application. It must contain only alphanumeric characters, underscores, and dashes. The maximum length is 200 characters. ● The currently supported destination types are HTTP, RFC and MAIL. ○ HTTP Destinations [page 64] - provide data communication via the HTTP protocol and are used for both Internet and on-premise connections. ○ RFC Destinations [page 110] - make connections to ABAP on-premise systems via RFC protocol using the Java Connector (JCo) as API. ○ Mail destinations - specify an e-mail provider for sending and retrieving e-mails. Tasks ● Create Destinations from Scratch [page 42] ● Create Destinations from a Template [page 51] ● Check the Availability of a Destination [page 53] ● Clone Destinations [page 54] ● Edit and Delete Destinations [page 55] ● Use Destination Certificates [page 56] ● Import Destinations [page 57] ● Export Destinations [page 58] Related Information Destination Examples [page 48] 1.1.3.1.1.1 Access the Destinations Editor Access the Destinations Editor in the SAP BTP cockpit to create and manage destinations in the Cloud Foundry environment. 40 PUBLIC SAP BTP Connectivity Connectivity
- 41. You can edit destinations at two different levels: ● Subaccount level ● Service instance level On subaccount level, you can specifiy a destination for the entire subaccount, defining the used communication protocol and more properties, like authentication method, proxy type and URL. On service instance level, you can reuse this destination for a specific space and adjust the URL if required. You can also create a new destination only on service instance level that is specific to the selected service instance and its assigned applications. Prerequisites ● You are logged into the SAP BTP cockpit. ● You have the required authorizations. See User Roles [page 9]. Procedure Access on Subaccount Level 1. In the cockpit, select your Global Account and your subaccount name from the Subaccount menu in the breadcrumbs. 2. From the left-side panel, choose Connectivity Destinations . Access on Service Instance Level Note To perform these steps, you must have created a Destination service instance in your space, see Create and Bind a Destination Service Instance [page 161]. On service instance level, you can set destinations only for Destination service instances. 1. In the cockpit, choose your Global Account from the Region Overview and select a Subaccount. Note The Cloud Foundry Organization must be enabled. 2. From the Spaces section, select a space name. 3. From the left-side menu, choose Services Service Instances . 4. Choose the Actions icon for a Destination service instance and select View Dashboard. SAP BTP Connectivity Connectivity PUBLIC 41
- 42. 5. On the Destinations screen, you can create new destinations or edit existing ones. See also section Create and Bind a Service Instance from the Cockpit in Create and Bind a Destination Service Instance [page 161]. Related Information Create Destinations from Scratch [page 42] Create Destinations from a Template [page 51] Check the Availability of a Destination [page 53] Clone Destinations [page 54] Edit and Delete Destinations [page 55] Use Destination Certificates [page 56] Import Destinations [page 57] Export Destinations [page 58] 1.1.3.1.1.2 Create Destinations from Scratch Use the Destinations editor in the SAP BTP cockpit to configure destinations from scratch. Configuring destinations from scratch provides the complete set of editing functions. While this requires deeper technical knowledge of the scenario and the required connection configuration, it is the most flexible procedure and lets you create any type of supported destination. 42 PUBLIC SAP BTP Connectivity Connectivity
- 43. To Create Destinations from a Template [page 51], in contrast, you do not need this deeper knowledge for configuration, but edting options are limited by the available templates. Related Information Create HTTP Destinations [page 43] Create RFC Destinations [page 44] Create Mail Destinations [page 46] Destination Examples [page 48] 1.1.3.1.1.2.1 Create HTTP Destinations Create HTTP destinations in the Destinations editor (SAP BTP cockpit). Prerequisites You have logged into the cockpit and opened the Destinations editor. Procedure 1. Choose New Destination. Note In section Destination Configuration, do not change the default tab Blank Template, unless you want to create a destination for a specific service instance in a subscription-based scenario. For more information, see Destinations Pointing to Service Instances [page 51]. 2. Enter a destination name. 3. From the <Type> dropdown menu, choose HTTP. 4. The <Description> field is optional. 5. Specify the destination URL. 6. From the <Proxy Type> dropdown box, select Internet or OnPremise, depending on the connection you need to provide for your application. Note For more information, see also HTTP Destinations [page 64]. SAP BTP Connectivity Connectivity PUBLIC 43
- 44. 7. From the <Authentication> dropdown box, select the authentication type you need for the connection. For details, see HTTP Destinations [page 64]. Note If you set an HTTPS destination, you need to also add a Trust Store. For more information, see Use Destination Certificates [page 56]. 8. (Optional) If you are using more than one Cloud Connector for your subaccount, you must enter the <Location ID> of the target Cloud Connector. See also Managing Subaccounts [page 328] (section Procedure, step 4). 9. (Optional) You can enter additional properties. a. In the Additional Properties panel, choose New Property. b. Enter a key (name) or choose one from the dropdown menu and specify a value for the property. You can add as many properties as you need. c. To delete a property, choose the button next to it. Note For a detailed description of specific properties for SAP Business Application Studio (formerly known as SAP Web IDE), see Connecting to External Systems. 10. When you are ready, choose the Save button. Related Information Edit and Delete Destinations [page 55] Destination Examples [page 48] 1.1.3.1.1.2.2 Create RFC Destinations How to create RFC destinations in the Destinations editor (SAP BTP cockpit). Prerequisites You have logged into the cockpit and opened the Destinations editor. 44 PUBLIC SAP BTP Connectivity Connectivity
- 45. Procedure 1. Choose New Destination. Note In section Destination Configuration, do not change the default tab Blank Template. Tab Service Instance only applies for HTTP destinations. 2. Enter a destination name. 3. From the <Type> dropdown menu, choose RFC. 4. The <Description> field is optional. 5. From the <Proxy Type> dropdown box, select Internet or OnPremise, depending on the connection you need to provide for your application. Note Using <Proxy Type> Internet , you can connect your application to any target service that is exposed to the Internet. <Proxy Type> OnPremise requires the Cloud Connector to access resources within your on-premise network. 6. Enter credentials for <User> and <Password>. 7. (Optional) Enter an <Alias User> name. See also User Logon Properties [page 111]. 8. (Optional) Enter credentials for <Repository User> and <Repository Password>, if you want to use a different user for repository lookups. See also Repository Configuration [page 115]. 9. (Optional) If you are using more than one Cloud Connector for your subaccount, you must enter the <Location ID> of the target Cloud Connector. See also Managing Subaccounts [page 328] (section Procedure, step 4). 10. Depending on the proxy type of your RFC destination, specify at least the following JCo properties in section Additional Properties. a. In the Additional Properties panel, choose New Property. b. Add each required property from the dropdown menu and specify its value: Proxy Type Property Description OnPremise Load Balancing Connections jco.client.r3name Three-letter system ID of your back end ABAP system (as configured in the Cloud Connector). jco.client.mshost Message server host (as configured in the Cloud Connector). jco.client.group (Optional) The group of application servers that is used (logon group). If not specified, the group PUBLIC is used. SAP BTP Connectivity Connectivity PUBLIC 45
- 46. Proxy Type Property Description jco.client.client Three-digit ABAP client number (de fines the client of the target ABAP sys tem). Direct Connections jco.client.ashost Application server name of your tar get ABAP system (as configured in the Cloud Connector). jco.client.sysnr Instance number of the application server (as configured in the Cloud Connector). jco.client.client Three-digit ABAP client number (de fines the client of the target ABAP sys tem). Internet jco.client.wshost WebSocket RFC server host on which the target ABAP system is running. The system must be exposed to the Internet. jco.client.wsport WebSocket RFC server port on which the target ABAP system is listening. jco.client.client Three-digit ABAP client number (de fines the client of the target ABAP sys tem). For a detailed description of RFC-specific properties (JCo properties), see RFC Destinations [page 110]. 11. Press Save. Related Information Edit and Delete Destinations [page 55] Destination Examples [page 48] Cloud Connector [page 267] 1.1.3.1.1.2.3 Create Mail Destinations Create mail destinations in the Destinations editor (SAP BTP cockpit). Prerequisites You have logged into the cockpit and opened the Destinations editor. 46 PUBLIC SAP BTP Connectivity Connectivity
- 47. Procedure 1. Choose New Destination. Note In section Destination Configuration, do not change the default tab Blank Template. Tab Service Instance only applies for HTTP destinations. 2. Enter a destination name. 3. From the Type dropdown menu, choose MAIL. 4. The Description field is optional. 5. Specify the destination URL. 6. From the Proxy Type dropdown box, select Internet or OnPremise, depending on the connection you need to provide for your application. Note To access a mail server located in your own network (via Cloud Connector), choose OnPremise. To access an external mail server, choose Internet. 7. Optional: You can enter additional properties. a. In the Additional Properties panel, choose New Property. b. Enter a key (name) or choose one from the dropdown menu and specify a value for the property. You can add as many properties as you need. Each key of an additional property must start with "mail.". c. To delete a property, choose the button next to it. 8. When you are ready, choose the Save button. Related Information Edit and Delete Destinations [page 55] Destination Examples [page 48] Cloud Connector [page 267] SAP BTP Connectivity Connectivity PUBLIC 47
- 48. 1.1.3.1.1.2.4 Destination Examples Find configuration examples for HTTP and RFC destinations in the Cloud Foundry environment, using different authentication types. Content HTTP Destination (Internet, Client Certificate Authentication) [page 48] HTTP Destination (Internet, OAuth2SAMLBearerAssertion) [page 49] HTTP Destination (On-Premise) [page 49] RFC Destination [page 50] Mail Destination (Internet) [page 50] Mail Destination (On-Premise) [page 50] Example: HTTP Destination (Internet, Client Certificate Authentication) Back to Content [page 48] 48 PUBLIC SAP BTP Connectivity Connectivity
- 49. Example: HTTP Destination (Internet, OAuth2SAMLBearerAssertion) Back to Content [page 48] Example: HTTP Destination (On-Premise) Back to Content [page 48] SAP BTP Connectivity Connectivity PUBLIC 49
- 50. Example: RFC Destination The following main properties correspond to the relevant additional properties: User → jco.client.user Password → jco.client.passwd Repository password → jco.destination.repository.passwd Note For security reasons, do not use these additional properties but use the corresponding main properties' fields. Back to Content [page 48] Example: Mail Destination (Internet) Back to Content [page 48] Example: Mail Destination (On-Premise) 50 PUBLIC SAP BTP Connectivity Connectivity
- 51. Back to Content [page 48] Related Information HTTP Destinations [page 64] RFC Destinations [page 110] 1.1.3.1.1.3 Create Destinations from a Template Use a template to configure destinations with scenario-specific input data in the SAP BTP cockpit. If you want to create several destinations for a common scenario, you can use a template that provides the scenario-specific input data. The Destination service uses the template to configure the destinations accordingly. Currently, the following template ist available for destination configuration: Destinations Pointing to Service Instances [page 51] 1.1.3.1.1.3.1 Destinations Pointing to Service Instances Create a destination for subscription-based scenarios that points to your service instance. Note This feature is applicable for a selected set of the most commonly used services (from a Destination service perspective). If you would like to use this feature for a service which is not yet supported, let us know by opening a support ticket, see Connectivity Support [page 581]. In the meantime, you can follow the steps described in Create Destinations from Scratch [page 42]. Usually, in the Cloud Foundry environment, you consume service instances by binding them to your applications. However, in subscription-based scenarios this is not always possible. If you have purchased a subscription to an SaaS application that runs in a provider's subaccount, you cannot bind your service instance to this application. SAP BTP Connectivity Connectivity PUBLIC 51
- 52. In this case, you must create a destination that points to your service instance. Applications can consume this destination through a subscription to gain access to your service instance. If you create such a destination from scratch, you must provide a service key for your instance, look up the credentials, and enter these values in the newly created destination. Using the Destinations Pointing to Service Instances template, you only have to select the corresponding service instance. Note This procedure only applies for HTTP destinations on subaccount level. Prerequisites ● You have a service instance which you want to make accessible to applications you are subscribed to. ● You have the Space Developer role in the space where this service instance resides. ● You have logged in to the cockpit and opened the Destinations editor on subaccount level. See Access the Destinations Editor [page 40]. Procedure 1. Choose New Destination. 2. Select the tab Service Instance in the Destination Configuration section. 3. In the <Service Instance> dropdown list, you find all the service instances, grouped by space, where you have the role Space Developer. 4. Select a service instance. 5. Give the destination configuration a name and, optionally, a description. 6. (Optional) You can specify additional properties. 7. Choose Next. A service key for that service instance is automatically generated, using the naming convention <service_instance_name>-service-key. If the key name already exists, it is reused. A new destination with pre-filled fields is previewed, using the given service instance data. Do not change the values of these fields. 8. If you want to create a destination with these values, choose Save. Otherwise, choose Cancel. Result You have a destination pointing to your service instance. If you delete this service instance or its service key, the destination stops working. 52 PUBLIC SAP BTP Connectivity Connectivity
- 53. Caution If you delete this service instance or its service key, the destination will stop working. 1.1.3.1.1.4 Check the Availability of a Destination How to check the availability of a destination in the Destinations editor (SAP BTP cockpit). Prerequisites You have logged into the cockpit and opened the Destinations editor. Context You can use the Check Connection button in the Destinations editor of the cockpit to verify if the URL configured for an HTTP Destination is reachable and if the connection to the specified system is possible. Note This check is available with Cloud Connector version 2.7.1 or higher. For each destination, the check button is available in the destination detail view and in the destination overview list (icon Check availability of destination connection in section Actions). Note The check does not guarantee that the target system or service is operational. It only verifies if a connection is possible. This check is supported for destinations with <Proxy Type> Internet and OnPremise: ● For Internet destinations: ○ If the check receives an HTTP status code above or equal to 500 from the targeted URL, the check is considered failed. ○ Every HTTP status code below 500 is treated as successful. ● For OnPremise destinations: ○ If the targeted backend is reached and returns an HTTP status code below 500 the check is considered successful. SAP BTP Connectivity Connectivity PUBLIC 53
- 54. Error Messages for OnPremise Destinations Error Message Reason Action Backend status could not be deter mined. ● The Cloud Connector version is less than 2.7.1. ● The Cloud Connector is not con nected to the subaccount. ● The backend returns an HTTP sta tus code above or equal to 500 (server error). ● The Cloud Connector is not config- ured properly. ● Upgrade the Cloud Connector to version 2.7.1 or higher. ● Connect the Cloud Connector to the corresponding subaccount. ● Check the server status (availabil ity) of the backend system. ● Check the basic Cloud Connector configuration steps: Initial Configuration [page 312] Backend is not available in the list of de fined system mappings in Cloud Connector. The Cloud Connector is not configured properly. Check the basic Cloud Connector con figuration steps: Initial Configuration [page 312] Resource is not accessible in Cloud Connector or backend is not reachable. The Cloud Connector is not configured properly. Check the basic Cloud Connector con figuration steps: Initial Configuration [page 312] Backend is not reachable from Cloud Connector. Cloud connector configuration is ok but the backend is not reachable. Check the backend (server) availability. 1.1.3.1.1.5 Clone Destinations How to clone destinations in the Destinations editor (SAP BTP cockpit). Prerequisites You have previously created or imported an HTTP destination in the Destinations editor of the cockpit. Procedure 1. In the Destinations editor, go to the existing destination which you want to clone. 2. Choose the icon. 54 PUBLIC SAP BTP Connectivity Connectivity
- 55. 3. The editor automatically creates and opens a new destination that contains all the properties of the selected one. 4. You can modify some parameters if you need. 5. When you are ready, choose the Save button. Related Information Export Destinations [page 58] Destination Examples [page 48] 1.1.3.1.1.6 Edit and Delete Destinations How to edit and delete destinations in the Destinations editor (SAP BTP cockpit). Prerequisites You have previously created or imported an HTTP destination in the Destinations editor of the cockpit. Procedure ● Edit a destination: 1. To edit a created or imported destination, choose the button. 2. You can edit the main parameters as well as the additional properties of a destination. 3. Choose the Save button. The changes will take effect in up to five minutes. Tip For complete consistency, we recommend that you first stop your application, then apply your destination changes, and then start again the application. Also, bear in mind that these steps will cause application downtime. ● Delete a destination: To remove an existing destination, choose the button. The changes will take effect in up to five minutes. Related Information Export Destinations [page 58] SAP BTP Connectivity Connectivity PUBLIC 55
- 56. Destination Examples [page 48] 1.1.3.1.1.7 Use Destination Certificates Maintain truststore and keystore certificates in the Destinations editor (SAP BTP cockpit). Prerequisites You have logged into the cockpit and opened the Destinations editor. For more information, see Access the Destinations Editor [page 40]. Context You can upload, add and delete certificates for your connectivity destinations. Bear in mind that: ● You can only use JKS, PFX and P12 files for destination key store, and JKS, CRT, CER, DER for destination trust store. ● You can add certificates only for HTTPS destinations. Truststore can be used for all authentication types. Keystore is available only for ClientCertificateAuthentication and OAuth2SAMLBearerAssertion. ● An uploaded certificate file should contain the entire certificate chain. Procedure Uploading Certificates 1. Choose the Certificates button. 2. Choose Upload Certificate. 3. Browse to the certificate file you need to upload. The certificate file is added. Note You can upload a certificate during creation or editing of a destination, by clicking the Upload and Delete Certificates link. 56 PUBLIC SAP BTP Connectivity Connectivity
- 57. Adding Certificates to Destinations 1. Create a new destination, or open an existing one for editing. 2. In the URL field, enter an HTTPS address. 3. You can use the default JDK truststore or select another one from the dropdown menu. If the menu is empty, you can upload a certificate on the fly. To omit this property, you can set TrustAll=true. 4. If you choose Authentication = ClientCertificateAuthentication, you need to also provide a keystore. Deleting Certificates 1. Choose the Certificates button or click the Upload and Delete Certificates link. 2. Select the certificate you want to remove and choose Delete Selected. 3. Upload another certificate, or close the Certificates window. More Information Create HTTP Destinations [page 43] Edit and Delete Destinations [page 55] Import Destinations [page 57] 1.1.3.1.1.8 Import Destinations How to import destinations in the Destinations editor (SAP BTP cockpit). Prerequisites You have previously created an HTTP destination. Note The Destinations editor allows importing destination files with extension .props, .properties, .jks, and .txt, as well as files with no extension. Destination files must be encoded in ISO 8859-1 character encoding. SAP BTP Connectivity Connectivity PUBLIC 57
- 58. Procedure 1. Log into the cockpit and open the Destinations editor. 2. Choose Import from File. 3. Browse to a configuration file that contains destination configuration. ○ If the configuration file contains valid data, it is displayed in the Destinations editor with no errors. The Save button is enabled so that you can successfully save the imported destination. ○ If the configuration file contains invalid properties or values, under the relevant fields in the Destinations editor are displayed error messages in red which prompt you to correct them accordingly. Related Information Edit and Delete Destinations [page 55] Destination Examples [page 48] 1.1.3.1.1.9 Export Destinations Export destinations from the Destinations editor in the SAP BTP cockpit to backup or reuse a destination configuration. Prerequisites You have created a destination in the Destinations editor. Procedure 1. Log into the cockpit and open the Destinations editor. 2. Select a destination and choose the button. 3. Browse to the location on your local file system where you want to save the new destination. ○ If the destination does not contain client certificate authentication, it is saved as a single configuration file. ○ If the destination provides client certificate data, it is saved as an archive, which contains the main configuration file and a JKS file. 58 PUBLIC SAP BTP Connectivity Connectivity
- 59. Related Information Edit and Delete Destinations [page 55] Destination Examples [page 48] 1.1.3.1.2 Destination Service REST API Destination service REST API specification for the SAP Cloud Foundry environment. The Destination service provides a REST API that you can use to read and manage destinations and certificates on all available levels. This API is documented in the SAP API Business Hub . It shows all available endpoints, the supported operations, parameters, possible error cases and related status codes, etc. You can also execute requests using the credentials (for example, the service key) of your Destination service instance, see Create and Bind a Destination Service Instance [page 161]. 1.1.3.1.3 Create Destinations Using the MTA Descriptor Use the multitarget-application (MTA) descriptor to manage destinations for complex deployments. Content ● Concept [page 59] ● Content Deployment [page 60] ● Create a Destination on Service Instance Creation [page 63] Concept When modeling a multitarget application (MTA), you can create and update destinations from your MTA descriptor. For more information on MTA, see Multitarget Applications in the Cloud Foundry Environment. Back to Content [page 59] SAP BTP Connectivity Connectivity PUBLIC 59
- 60. Content Deployment When modeling MTAs, you can configure content deployments (for more information, see Content Deployment). The Destinations service supports such content deployments, which lets you create or update destinations by modeling them in the MTA descriptor. Other operations, like deleting a destination, are not supported by this method. Parameters The parameters of the content deployment have the following structure: content: subaccount: existing_destinations_policy: <policy> # optional, default value is "fail". See "Existing destinations policy" for more details destinations: - <destination descriptor 1> # See "Modeling options" to learn about the structure of this descriptor ... - <destination descriptor N> # See "Modeling options" to learn about the structure of this descriptor instance: existing_destinations_policy: <policy> # optional, default value is "fail". See "Existing destinations policy" for more details destinations: - <destination descriptor 1> # See "Modeling options" to learn about the structure of this descriptor ... - <destination descriptor N> # See "Modeling options" to learn about the structure of this descriptor Note Both the subaccount and instance sections are optional. They can both be present at the same time, or only one of them. They define the level on which the resulting destination is created. Existing Destinations Policy The existing_destinations_policy setting allows you to control what happens if a destination with the same name already exists. The possible values are: ● fail: Treat it as an error situation and fail the deployment. This is the default value of the setting. ● ignore: Keep what is currently saved in the Destination service, and skip deployment for this destination. ● update: Override what is currently saved in the Destination service. Modeling Options The destinations section represents an array of destination descriptors. Each of these array elements is converted to a destination and saved in the service on the respective level, based on the existing destination policy. The following options are available for modeling a destination descriptor via content deployment. They can be combined: Destination Pointing to a Service Instance 60 PUBLIC SAP BTP Connectivity Connectivity
- 61. This option lets you: ● Reference a service instance and a service key ● Specify a destination name ● Enter a description for the resulting destination (optional) ● Add additional properties and override default properties (optional) As a result, a destination is created, based on the properties in the referenced service key. Note This function is equivalent to the Destinations Pointing to Service Instances [page 51] template. Caution This feature is applicable for a selected set of the most commonly used services (from a Destination service perspective). If you would like to use this feature for a service which is not yet supported, let us know by opening a support ticket, see Connectivity Support [page 581]. In the meantime, you can follow the steps described in Create Destinations from Scratch [page 42]. The descriptor has the following structure: Name: <name> # name of the destination Description: <description> # optional, a description for the destination Authentication: <auth> # optional for some services (the default is service specific). Some services require the Authentication to be specified, like the workflow service. The allowed authentication types are also service-specific ServiceInstanceName: <instance name> # the name of the service instance to which the destination will be created ServiceKeyName: <service key name> # the service key of the instance targeted by ServiceInstanceName which will be used as the source for the destination values AdditionalProp1: value1 # optional ... AdditionalPropN: valueN # optional Destination Pointing to a Resource Protected by an XSUAA Service Instance This option lets you: ● Reference a service instance and a service key ● Specify a destination name ● Enter a description for the resulting destination (optional) ● Specify the URL of the target resource ● Add additional properties and override default properties (optional) As a result, a destination is created with the token service configuration based on the properties in the referenced service key, while the URL will be the one specified when modeling the destination. The descriptor has the following structure: Name: <name> # name of the destination Description: <description> # optional, a description for the destination SAP BTP Connectivity Connectivity PUBLIC 61
- 62. Authentication: <auth> # optional for some services (the default is service specific). Some services require the Authentication to be specified, like the workflow service. The allowed authentication types are also service-specific URL: <url> # the URL of the target resource TokenServiceInstanceName: <instance name> # the name of the service instance used for protecting the target resource TokenServiceKeyName: <service key name> # the service key of the instance targeted by ServiceInstanceName which will be used as the source for the token service values in the destination AdditionalProp1: value1 # optional ... AdditionalPropN: valueN # optional Example: _schema-version: "3.2" ID: example version: 0.0.1 modules: - name: myapp path: ./myapp type: javascript.nodejs requires: - name: xsuaa_service provides: - name: myapp-route properties: url: ${default-url} #generated during deployment - name: destination-content type: com.sap.application.content requires: - name: xsuaa_service parameters: service-key: name: xsuaa_service-key - name: destination-service parameters: content-target: true - name: myapp-route build-parameters: no-source: true parameters: content: subaccount: existing_destinations_policy: update destinations: - Name: myappOauth URL: ~{myapp-route/url} Authentication: OAuth2ClientCredentials TokenServiceInstanceName: xsuaa_service TokenServiceKeyName: xsuaa_service-key myAdditionalProp: myValue - Name: workflowOauthJwtBearer Authentication: OAuth2JWTBearer ServiceInstanceName: workflow_service ServiceKeyName: workflow_service-key instance: existing_destinations_policy: update destinations: - Name: workflowBasicAuthentication Authentication: BasicAuthentication ServiceInstanceName: workflow_service ServiceKeyName: workflow_service-key myAdditionalProp: myValue resources: - name: xsuaa_service 62 PUBLIC SAP BTP Connectivity Connectivity
- 63. type: org.cloudfoundry.managed-service parameters: service: xsuaa service-name: xsuaa_service service-plan: application config: xsappname: "myApp" - name: workflow_service type: org.cloudfoundry.managed-service parameters: service: workflow service-name: workflow_service service-plan: lite - name: destination-service type: org.cloudfoundry.managed-service parameters: service: destination service-name: my-destination-service service-plan: lite Back to Content [page 59] Create a Destination on Service Instance Creation The MTA descriptor lets you create service instances and provide a JSON configuration for this operation. You can use this functionality to create a Destination service instance with a JSON, and include the required data to create or update destinations. For more details, see Use a Config.JSON to Create or Update a Destination Service Instance [page 163]. Back to Content [page 59] 1.1.3.1.4 Create Destinations on Service Instance Creation Use a JSON to create or update a destination when creating a Destination service instance. When creating or updating a service instance of the Destination service, you can provide a JSON object with various configurations. One of the sections of this JSON lets you create or update destinations. Other operations, like deleting a destination, are not supported by this method. For more information, see Use a Config.JSON to Create or Update a Destination Service Instance [page 163]. SAP BTP Connectivity Connectivity PUBLIC 63
- 64. 1.1.3.2 HTTP Destinations Find information about HTTP destinations for Internet and on-premise connections (Cloud Foundry environment). Destination Levels The runtime tries to resolve a destination in the order: Subaccount Level → Service Instance Level. Destinations for Subscribed Applications In subscription-based scenarios, it is not always possible to consume a service instance by binding it to your application. In this case, you must create a destination pointing to your service instance. For more information, see Destinations Pointing to Service Instances [page 51]. Proxy Types The proxy types supported by the Connectivity service are: ● Internet - The application can connect to an external REST or SOAP service on the Internet. ● OnPremise - The application can connect to an on-premise back-end system through the Cloud Connector. The proxy type used for a destination is specified by the destination property ProxyType. The default value is Internet. Proxy Settings for Your Local Runtime If you work in your local development environment behind a proxy server and want to use a service from the Internet, you need to configure your proxy settings on JVM level. To do this, proceed as follows: 1. On the Servers view, double-click the added server and choose Overview to open the editor. 2. Click the Open Launch Configuration link. 3. Choose the (x)=Arguments tab page. 4. In the VM Arguments box, add the following row: -Dhttp.proxyHost=yourproxyHost -Dhttp.proxyPort=yourProxyPort - Dhttps.proxyHost=yourproxyHost -Dhttps.proxyPort=yourProxyPort 5. Choose OK. 6. Start or restart your SAP HANA Cloud local runtime. 64 PUBLIC SAP BTP Connectivity Connectivity
- 65. Configuring Authentication When creating an HTTP destination, you can use different authentication types for access control: ● Server Certificate Authentication [page 65] ● Principal Propagation SSO Authentication [page 68] ● OAuth SAML Bearer Assertion Authentication [page 70] ● Client Authentication Types for HTTP Destinations [page 77] ● OAuth Client Credentials Authentication [page 80] ● OAuth User Token Exchange Authentication [page 86] ● SAP Assertion SSO Authentication [page 91] ● OAuth Password Authentication [page 96] ● OAuth JWT Bearer Authentication [page 100] ● SAML Assertion Authentication [page 105] Related Information OAuth with X.509 Client Certificates [page 109] Create HTTP Destinations [page 43] 1.1.3.2.1 Server Certificate Authentication Create and configure a Server Certificate destination for an application in the Cloud Foundry environment. Context The server certificate authentication is applicable for all client authentication types, described below. Note TLS 1.2 became the default TLS version of HTTP destinations. If an HTTP destination is consumed by a java application the change will be effective after restart. All HTTP destinations that use the HTTPS protocol and have ProxyType=Internet can be affected. Previous TLS version can be used by configuring an additional property TLSVersion=TLSv1.0 or TLSVersion=TLSv1.1. SAP BTP Connectivity Connectivity PUBLIC 65
- 66. Properties Property Description TLSVersion Optional property. Can be used to specify the preferred TLS version to be used by the current destination. Since TLS 1.2 is not enabled by default on the older java versions this property can be used to configure TLS 1.2 in case this is required by the server configured in this destination. It is usable only in HTTP destinations. Example: TLSVersion=TLSv1.2 . TrustStoreLocation 1. When used in local environment 2. When used in cloud environment Path to the JKS file which contains trusted certificates (Certificate Authorities) for authentication against a remote client. 1. The relative path to the JKS file. The root path is the server's location on the file system. 2. The name of the JKS file. Note If the TrustStoreLocation property is not specified, the JDK trust store is used as a default trust store for the destination. TrustStorePassword Password for the JKS trust store file. This property is mandatory in case TrustStoreLocation is used. TrustAll If this property is set to TRUE in the destination, the server certificate will not be checked for SSL connections. It is intended for test scenarios only, and should not be used in production (since the SSL server certificate is not checked, the server is not authenticated). The possible values are TRUE or FALSE; the default value is FALSE (that is, if the property is not present at all). In case TrustAll = TRUE, the TrustStoreLocation property is ignored so you can omit it. In case <TrustAll> = FALSE, the <TrustStoreLocation> property is manda tory to be used. 66 PUBLIC SAP BTP Connectivity Connectivity
- 67. Property Description HostnameVerifier Optional property. It has two values: Strict and BrowserCompatible. This property specifies how the server hostname matches the names stored inside the server's X.509 certificate. This verifying process is only applied if TLS or SSL pro tocols are used and is not applied if the TrustAll property is specified. The de fault value (used if no value is explicitly specified) is Strict. ● Strict HostnameVerifier works in the same way as Oracle Java 1.4, Oracle Java 5, and Oracle Java 6-rc. It is also similar to Microsoft Internet Ex plorer 6. This implementation appears to be compliant with RFC 2818 for dealing with wildcards. A wildcard such as "*.foo.com" matches only subdo mains at the same level, for example "a.foo.com". It does not match deeper subdomains such as "a.b.foo.com". ● BrowserCompatible HostnameVerifier works in the same way as Curl and Mozilla Firefox. The hostname must match either the first common name (CN) or any of the subject-alts. A wildcard can occur in the CN and in any of the subject-alts. The only difference between BrowserCompatible and Strict is that a wild card (such as ".foo.com") with BrowserCompatible matches all subdomains, including "a.b.foo.com". For more information about these Java classes, see Package org.apache.http.conn.ssl . In case <TrustAll> = TRUE, the <HostnameVerifier> property is ignored so you can omit it. Note You can upload trust store JKS files using the same command as for uploading destination configuration property files. You only need to specify the JKS file instead of the destination configuration file. Note Connections to remote services which require Java Cryptography Extension (JCE) unlimited strength jurisdiction policy are not supported. Configuration ● Managing Destinations [page 38] Related Information Client Authentication Types for HTTP Destinations [page 77] SAP BTP Connectivity Connectivity PUBLIC 67
- 68. 1.1.3.2.2 Principal Propagation SSO Authentication Forward the identity of a cloud user from a Cloud Foundry application to a backend system to enable single sign-on (SSO). Context A PrincipalPropagation destination enables single sign-on (SSO) by forwarding the identity of a cloud user to the Cloud Connector, and from there to the target on-premise system. In this way, the cloud user's identity can be provided without manual logon. Note This authentication type applies only for on-premise connectivity. Configuration Steps You can create and configure a PrincipalPropagation destination by using the properties listed below, and deploy it on SAP BTP. For more information, see Managing Destinations [page 38]. Properties The following credentials need to be specified: Property Description Name Destination name. Must be unique for the destination level. Type Destination type. Use HTTP for all HTTP(S) destinations. URL Virtual URL of the protected on-premise application. Authentication Authentication type. Use PrincipalPropagation as a value. ProxyType You can only use proxy type OnPremise. CloudConnectorLocationId As of Cloud Connector 2.9.0, you can connect multiple Cloud Connectors to a subaccount as long as their location ID is different. The location ID specifies the Cloud Connector over which the connection is opened. The default value is an empty string identifying the Cloud Connector that is connected without any location ID. This is also valid for all Cloud Connector versions prior to 2.9.0. 68 PUBLIC SAP BTP Connectivity Connectivity
- 69. Property Description URL.headers.<header-key> A static key prefix used as a namespace grouping of the URL's HTTP headers whose values will be sent to the target endpoint. For each HTTP header's key, you must add a URL.headers prefix separated by dot-delimiter. For example: Sample Code { ... "URL.headers.<header-key-1>" : "<header-value-1>", ... "URL.headers.<header-key-N>": "<header-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expectation for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. URL.queries.<query-key> A static key prefix used as a namespace grouping of URL's query parameters whose values will be sent to the target endpoint. For each query parameter's key, you must add a URL.queries prefix separated by dot-delimiter. For example: Sample Code { ... "URL.queries.<query-key-1>" : "<query-value-1>", ... "URL.queries.<query-key-N>": "<query-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service SAP BTP Connectivity Connectivity PUBLIC 69
- 70. Property Description only provides the configured properties. The expectation for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. Example Name=OnPremiseDestination Type=HTTP URL= http://virtualhost:80 Authentication=PrincipalPropagation ProxyType=OnPremise Related Information Principal Propagation [page 121] 1.1.3.2.3 OAuth SAML Bearer Assertion Authentication Create and configure an OAuth SAML Bearer Assertion destination for an application in the Cloud Foundry environment. Context You can call an OAuth2-protected remote system/API and propagate a user ID to the remote system by using the OAuth2SAMLBearerAssertion authentication type. The Destination service provides functionality for automatic token retrieval and caching, by automating the construction and sending of the SAML assertion. This simplifies application development, leaving you with only constructing the request to the remote system by providing the token, which is fetched for you by the Destination service. For more information, see User Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. 70 PUBLIC SAP BTP Connectivity Connectivity
- 71. Properties The table below lists the destination properties for OAuth2SAMLBearerAssertion authentication type. You can find the values for these properties in the provider-specific documentation of OAuth-protected services. Usually, only a subset of the optional properties is required by a particular service provider. Property Description Required Name Name of the destination. Must be unique for the destination level. Type Destination type. Choose HTTP for all HTTP(S) destinations. URL URL of the target endpoint. ProxyType Choose Internet. OnPremise is not supported for this authentication type. Authentication Authentication type. Use OAuth2SAMLBearerAssertion as value. KeyStoreLocation 1. When used in local environment 2. When used in cloud environment Path to the JKS file that contains the client certificate(s) for authentication against a remote server. 1. The relative path to the JKS file. The root path is the server's location on the file system. 2. The name of the JKS file. This property is optional. If not specified, the subaccount key pair is used. Note You can upload KeyStore JKS files using the same command for uploading destination configuration prop erty file. You only need to specify the JKS file instead of the destination configuration file. Note You can configure the keystore properties only in the Destination editor on subaccount level. KeyStorePassword The password for the key storage. This property is manda tory in case KeyStoreLocation is used. audience Intended audience for the assertion, which is verified by the OAuth authorization server. For more information, see SAML 2.0 Bearer Assertion Profiles for OAuth 2.0 . clientKey Key that identifies the consumer to the authorization server. SAP BTP Connectivity Connectivity PUBLIC 71
- 72. Property Description tokenServiceURL The URL of the token service, against which the token ex change is performed. Depending on the Token Service URL type, this property is interpreted in different ways dur ing the automatic token retrieval: ● For Dedicated, the token service URL is taken as is. ● For Common, the token service URL is searched for the tenant placeholder {tenant}. {tenant} is resolved as the subdomain of the subac count on behalf of which the caller is performing the call. If the placeholder is not found, {tenant} is in serted as a subdomain of the token service URL. The subaccount subdomain is mandated during crea tion of the subaccount, see Create a Subaccount. Examples of interpreting the token service URL for the token service URL type Common, if the call to the Destination serv ice is on behalf of a subaccount subdomain with value mytenant: ● https:// authentication.us10.hana.ondemand.com /oauth/token → https:// mytenant.authentication.us10.hana.ond emand.com/oauth/token ● https:// {tenant}.authentication.us10.hana.ond emand.com/oauth/token → https:// mytenant.authentication.us10.hana.ond emand.com/oauth/token ● https:// authentication.myauthserver.com/ tenant/{tenant}/oauth/token → https:// authentication.myauthserver.com/ tenant/mytenant/oauth/token ● https://oauth. {tenant}.myauthserver.com/token → https:// oauth.mytenant.myauthserver.com/token tokenServiceURLType Either Dedicated - if the token service URL serves only a single tenant, or Common - if the token service URL serves multiple tenants. tokenServiceUser User for basic authentication to OAuth server (if required). tokenServicePassword Password for tokenServiceUser (if required). 72 PUBLIC SAP BTP Connectivity Connectivity
- 73. Property Description (Deprecated) SystemUser User to be used when requesting an access token from the OAuth authorization server. If this property is not specified, the currently logged-in user is used. Caution This property is deprecated and will be removed soon. We recommend that you work on behalf of specific (named) users instead of working with a technical user. As an alternative for technical user communication, we strongly recommend that you use one of these authenti cation types: ● Basic Authentication (see Client Authentication Types for HTTP Destinations [page 77]) ● Client Certificate Authentication (see Client Au thentication Types for HTTP Destinations [page 77]) ● OAuth Client Credentials Authentication [page 80] To extend an OAuth access token's validity, consider us ing an OAuth refresh token. authnContextClassRef Value of the AuthnContextClassRef tag, which is part of generated OAuth2SAMLBearerAssertion authenti cation. For more information, see SAML 2.0 specification . Additional nameQualifier Security domain of the user for which access token is re quested. companyId Company identifier. assertionIssuer Issuer of the SAML assertion. nameIdFormat Value of the NameIdFormat tag, which is part of gener ated OAuth2SAMLBearerAssertion authentication. For more information, see SAML 2.0 specification . userIdSource When this property is set, the generated SAML2 assertion uses the currently logged-in user as a value for the NameId tag. See User Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. scope The value of the OAuth 2.0 scope parameter, expressed as a list of space-delimited, case-sensitive strings. SAP BTP Connectivity Connectivity PUBLIC 73
- 74. Property Description tokenServiceURL.headers.<header-key> A static key prefix used as a namespace grouping of the tokenServiceUrl's HTTP headers. Its values will be sent to the token service during token retrieval. For each HTTP header's key you must add a 'tokenServiceURL.head ers' prefix separated by dot delimiter. For example: Sample Code { ... "tokenServiceURL.headers.<header- key-1>" : "<header-value-1>", ... "tokenServiceURL.headers.<header- key-N>": "<header-value-N>", } tokenServiceURL.queries.<query-key> A static key prefix used as a namespace grouping of tokenServiceUrl's query parameters. Its values will be sent to the token service during token retrieval. For each query paramester's key you must add a 'tokenServi ceURL.queries' prefix separated by dot delimiter. For exam ple: Sample Code { ... "tokenServiceURL.queries.<query- key-1>" : "<query-value-1>", ... "tokenServiceURL.queries.<query- key-N>": "<query-value-N>", } 74 PUBLIC SAP BTP Connectivity Connectivity
- 75. Property Description URL.headers.<header-key> A static key prefix used as a namespace grouping of the URL's HTTP headers whose values will be sent to the target endpoint. For each HTTP header's key, you must add a URL.headers prefix separated by dot-delimiter. For exam ple: Sample Code { ... "URL.headers.<header-key-1>" : "<header-value-1>", ... "URL.headers.<header-key-N>": "<header-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. SAP BTP Connectivity Connectivity PUBLIC 75
- 76. Property Description URL.queries.<query-key> A static key prefix used as a namespace grouping of URL's query parameters whose values will be sent to the target endpoint. For each query parameter's key, you must add a URL.queries prefix separated by dot-delimiter. For exam ple: Sample Code { ... "URL.queries.<query-key-1>" : "<query-value-1>", ... "URL.queries.<query-key-N>": "<query-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. x_user_token.jwks Base64-encoded JSON web key set, containing the signing keys which are used to validate the JWT provided in the X- User-Token header. For more information, see JWK Set Format . x_user_token.jwks_uri URI of the JSON web key set, containing the signing keys which are used to validate the JWT provided in the X-User- Token header. For more information, see OpenID Connect Discovery . Example The connectivity destination below provides HTTP access to the OData API of the SuccessFactors Jam. URL=https://demo.sapjam.com/OData/OData.svc Name=sap_jam_odata TrustAll=true ProxyType=Internet Type=HTTP Authentication=OAuth2SAMLBearerAssertion tokenServiceURL=https://demo.sapjam.com/api/v1/auth/token clientKey=<unique_generated_string> 76 PUBLIC SAP BTP Connectivity Connectivity
- 77. audience=cubetree.com nameQualifier=www.successfactors.com apiKey=<apiKey> The response for "find destination" contains an authTokens object in the format given below. For more information on the fields in authTokens, see "Find Destination" Response Structure [page 196]. Sample Code "authTokens": [ { "type": "Bearer", "value": "eyJhbGciOiJSUzI1NiIsInR5cC...", "http_header": { "key":"Authorization", "value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..." } } ] Related Information Create HTTP Destinations [page 43] Destination Examples [page 48] Exchanging User JWTs via OAuth2UserTokenExchange Destinations [page 204] 1.1.3.2.4 Client Authentication Types for HTTP Destinations Find details about client authentication types for HTTP destinations in the Cloud Foundry environment. Context This section lists the supported client authentication types and the relevant supported properties. No Authentication This is used for destinations that refer to a service on the Internet or an on-premise system that does not require authentication. The relevant property value is: SAP BTP Connectivity Connectivity PUBLIC 77
- 78. Authentication=NoAuthentication Note When a destination is using HTTPS protocol to connect to a Web resource, the JDK truststore is used as truststore for the destination. Basic Authentication This is used for destinations that refer to a service on the Internet or an on-premise system that requires basic authentication. The relevant property value is: Authentication=BasicAuthentication The following credentials need to be specified: Property Description User User name Password Password Preemptive If this property is not set or is set to TRUE (that is, the default behavior is to use preemptive sending), the authentication token is sent preemptively. Otherwise, it relies on the challenge from the server (401 HTTP code). The default value (used if no value is explicitly specified) is TRUE. For more information about preemp tiveness, see http:/ /tools.ietf.org/html/rfc2617#section-3.3 . Note When a destination is using the HTTPS protocol to connect to a Web resource, the JDK truststore is used as truststore for the destination. Note Basic Authentication and No Authentication can be used in combination with ProxyType=OnPremise. In this case, also the CloudConnectorLocationId property can be specified. As of Cloud Connector 2.9.0, you can connect multiple Cloud Connectors to a subaccount as long as their location ID is different. The value defines the location ID identifying the Cloud Connector over which the connection shall be opened. The default value is the empty string identifying the Cloud Connector that is connected without any location ID. This is also the case for all Cloud Connector versions prior to 2.9.0. The response for "find destination" contains an authTokens object in the format given below. For more information on the fields in authTokens, see "Find Destination" Response Structure [page 196]. 78 PUBLIC SAP BTP Connectivity Connectivity
- 79. Sample Code "authTokens": [ { "type": "Basic", "value": "dGVzdDpwYXNzMTIzNDU=", "http_header": { "key":"Authorization", "value":"Basic dGVzdDpwYXNzMTIzNDU=" } } ] Client Certificate Authentication This is used for destinations that refer to a service on the Internet. The relevant property value is: Authentication=ClientCertificateAuthentication The following credentials need to be specified: Property Description KeyStore.Source Optional. Specifies the storage location of the certificate to be used by the client. Supported values are: ● ClientProvided: The key store is managed by the client (the application itself). ● DestinationService: The key store is managed by the Destination service. If the property is not set, the key store is managed by the Destination service (de fault). KeyStoreLocation The name of the key store file that contains the client certificate(s) for client cer tificate authentication against a remote server. This property is optional if KeyStore.Source is set to ClientProvided. KeyStorePassword Password for the key store file specified by KeyStoreLocation. This property is optional if KeyStoreLocation is used in combination with KeyStore.Source, and KeyStore.Source is set to ClientProvided. Note You can upload KeyStore JKS files using the same command for uploading destination configuration property file. You only need to specify the JKS file instead of the destination configuration file. SAP BTP Connectivity Connectivity PUBLIC 79
- 80. Configuration ● Managing Destinations [page 38] Related Information Server Certificate Authentication [page 65] 1.1.3.2.5 OAuth Client Credentials Authentication Create and configure an OAuth2ClientCredentials destination to consume OAuth-protected resources from a Cloud Foundry application. SAP BTP supports applications to use the OAuth client credentials flow for consuming OAuth-protected resources. The client credentials are used to request an access token from an OAuth authorization server. Note The retrieved access token is cached and auto-renovated. When a token is about to expire, a new token is created shortly before the expiration of the old one. Configuration Steps You can create and configure an OAuth2ClientCredentials destination using the properties listed below, and deploy it on SAP BTP. To create and configure a destination, follow the steps described in Managing Destinations [page 38]. Properties The table below lists the destination properties required for the OAuth2ClientCredentials authentication type. Property Description Required Name Destination name. Must be unique for the destination level. 80 PUBLIC SAP BTP Connectivity Connectivity
- 81. Property Description Type Destination type. Use HTTP as value for all HTTP(S) destina tions. URL URL of the protected resource on the called application. ProxyType You can only use proxy type Internet. Authentication Authentication type. Use OAuth2ClientCredentials as value. clientId Client ID used to retrieve the access token. clientSecret Client secret for the Client ID. tokenServiceURL URL of the OAuth server. tokenServiceUser User for basic authentication to OAuth server (if required). tokenServicePassword Password for tokenServiceUser (if required). Additional scope The value of the OAuth 2.0 scope parameter expressed as a list of space-delimited, case-sensitive strings. tokenServiceURL.headers.<header-key> A static key prefix used as a namespace grouping of the tokenServiceUrl's HTTP headers. Its values will be sent to the token service during token retrieval. For each HTTP header's key you must add a 'tokenServiceURL.head ers' prefix separated by dot delimiter. For example: Sample Code { ... "tokenServiceURL.headers.<header- key-1>" : "<header-value-1>", ... "tokenServiceURL.headers.<header- key-N>": "<header-value-N>", } SAP BTP Connectivity Connectivity PUBLIC 81
- 82. Property Description tokenServiceURL.queries.<query-key> A static key prefix used as a namespace grouping of tokenServiceUrl's query parameters. Its values will be sent to the token service during token retrieval. For each query paramester's key you must add a 'tokenServi ceURL.queries' prefix separated by dot delimiter. For exam ple: Sample Code { ... "tokenServiceURL.queries.<query- key-1>" : "<query-value-1>", ... "tokenServiceURL.queries.<query- key-N>": "<query-value-N>", } tokenService.KeyStoreLocation Contains the name of the certificate configuration to be used. This property is required when using client certificates for authentication. See OAuth with X.509 Client Certificates [page 109]. tokenService.KeyStorePassword Contains the password for the certificate configuration (if one is needed) when using client certificates for authentica tion. See OAuth with X.509 Client Certificates [page 109]. 82 PUBLIC SAP BTP Connectivity Connectivity
- 83. Property Description URL.headers.<header-key> A static key prefix used as a namespace grouping of the URL's HTTP headers whose values will be sent to the target endpoint. For each HTTP header's key, you must add a URL.headers prefix separated by dot-delimiter. For exam ple: Sample Code { ... "URL.headers.<header-key-1>" : "<header-value-1>", ... "URL.headers.<header-key-N>": "<header-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. SAP BTP Connectivity Connectivity PUBLIC 83
- 84. Property Description URL.queries.<query-key> A static key prefix used as a namespace grouping of URL's query parameters whose values will be sent to the target endpoint. For each query parameter's key, you must add a URL.queries prefix separated by dot-delimiter. For exam ple: Sample Code { ... "URL.queries.<query-key-1>" : "<query-value-1>", ... "URL.queries.<query-key-N>": "<query-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. Note When the OAuth authorization server is called, it accepts the trust settings of the destination, see Server Certificate Authentication [page 65]. When using an SAP BTP Neo OAuth service (https://api.{landscape-domain}/oauth2/apitoken/v1? grant_type=client_credentials or oauthasservices.{landscape-domain}/oauth2/ apitoken/v1?grant_type=client_credentials) as TokenServiceURL, or any other OAuth token service which accepts client credentials only as authorization header, you must set the clientId and clientSecret values also for the tokenServiceUser and tokenServicePassword properties. Example: Neo OAuth Token Service Sample Code URL=https://api.{landscape-domain}/desired-service-path Name=sapOAuthCC TrustAll=true 84 PUBLIC SAP BTP Connectivity Connectivity
- 85. ProxyType=Internet Type=HTTP Authentication=OAuth2ClientCredentials tokenServiceURL=(https://api.{landscape-domain}/oauth2/apitoken/v1? grant_type=client_credentials tokenServiceUser=clientIdValue tokenServicePassword=secretValue clientId=clientIdValue clientSecret=secretValue Example: OAuth Token Service Accepting Client Credentials as Body Sample Code URL=https://demo.sapjam.com/OData/OData.svc Name=sap_jam_odata TrustAll=true ProxyType=Internet Type=HTTP Authentication=OAuth2ClientCredentials tokenServiceURL=http://demo.sapjam.com/api/v1/auth/token tokenServiceUser=tokenserviceuser tokenServicePassword=pass clientId=clientId clientSecret=secret Example: AuthTokens Object Response The response for "find destination" contains an authTokens object in the format given below. For more information on the fields in authTokens, see "Find Destination" Response Structure [page 196]. Sample Code "authTokens": [ { "type": "Bearer", "value": "eyJhbGciOiJSUzI1NiIsInR5cC...", "http_header": { "key":"Authorization", "value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..." } } ] SAP BTP Connectivity Connectivity PUBLIC 85
- 86. 1.1.3.2.6 OAuth User Token Exchange Authentication Learn about the OAuth2UserTokenExchange authentication type for HTTP destinations in the Cloud Foundry environment: use cases, supported properties and ways to retrieve an access token in an automated way. Content Overview [page 86] Properties [page 86] Example: AuthTokens Object Response [page 90] Overview When a user is logged into an application that needs to call another application and pass the user context, the caller application must perform a user token exchange. The user token exchange is a sequence of steps during which the initial user token is handed over to the authorization server and, in exchange, another access token is returned. The calling application first receives a refresh token out of which the actual user access token is created. The resulting user access token contains the user and tenant context as well as technical access metadata, like scopes, that are required for accessing the target application. Using the OAuth2UserTokenExchange authentication type, the Destination service performs all these steps automatically, which lets you simplify your application development in the Cloud Foundry environment. Back to Content [page 86] Properties To configure a destination of this type, you must specify all the required properties. You can create destinations of this type via the cloud cockpit (Access the Destinations Editor [page 40]) or the Destination Service REST API [page 59]. The following table shows the required properties along with their semantics. 86 PUBLIC SAP BTP Connectivity Connectivity
- 87. Field/Parameter JSON Key Input/Description Required URL URL URL of the target endpoint. Token Service URL tokenServi ceURL The URL of the token service, against which the token exchange is performed. De pending on the Token Service URL Type, this property is interpreted in dif ferent ways during the automatic token retrieval: ● For Dedicated, the token service URL is taken as is. ● For Common, the token service URL is searched for the tenant placeholder {tenant}. {tenant} is resolved as the subdomain of the subaccount on behalf of which the caller is performing the call. If the placeholder is not found, {tenant} is inserted as a subdomain of the token service URL. See Automated Access Token Retrieval [page 205] for information about how the tenant is determined. The subaccount subdomain is mandated during creation of the subaccount, see Create a Subaccount. Examples of interpreting the token service URL for the token service URL type Common, if the call to the Destination service is on behalf of a subaccount subdo main with value mytenant: ● https://authentication.us10.hana.ondemand.com/oauth/ token → https:// mytenant.authentication.us10.hana.ondemand.com/oauth/ token ● https:// {tenant}.authentication.us10.hana.ondemand.com/oauth/ token → https:// mytenant.authentication.us10.hana.ondemand.com/oauth/ token ● https://authentication.myauthserver.com/tenant/ {tenant}/oauth/token → https:// authentication.myauthserver.com/tenant/mytenant/ oauth/token ● https://oauth.{tenant}.myauthserver.com/token → https://oauth.mytenant.myauthserver.com/token Name Name Name of the destination. Must be unique for the destination level. Description Description A human-readable description of the destination. Client Secret clientSecret OAuth 2.0 client secret to be used for the user access token exchange. Client ID clientId OAuth 2.0 client ID to be used for the user access token exchange. Authenticati on Authentication OAuth2UserTokenExchange in this case. SAP BTP Connectivity Connectivity PUBLIC 87
- 88. Field/Parameter JSON Key Input/Description Proxy Type ProxyType Choose Internet. OnPremise is not supported for this authentication type. Type Type Choose HTTP (for HTTP or HTTPS communication). Token Service URL Type tokenServi ceURLType ● Choose Dedicated if the token service URL serves only a single tenant. ● Choose Common if the token service URL serves multiple tenants. Optional Description Description Description of the destination. Additional scope The value of the OAuth 2.0 scope parameter expressed as a list of space-delimited, case-sensitive strings. tokenServic eURL.header s.<header- key> A static key prefix used as a namespace grouping of the tokenServiceUrl's HTTP headers. Its values will be sent to the token service during token retrieval. For each HTTP header's key you must add a 'tokenServiceURL.headers' prefix separated by dot delimiter. For example: Sample Code { ... "tokenServiceURL.headers.<header-key-1>" : "<header-value-1>", ... "tokenServiceURL.headers.<header-key-N>": "<header-value-N>", } tokenServic eURL.querie s.<query- key> A static key prefix used as a namespace grouping of tokenServiceUrl's query parameters. Its values will be sent to the token service during token retrieval. For each query paramester's key you must add a 'tokenServiceURL.queries' prefix sepa rated by dot delimiter. For example: Sample Code { ... "tokenServiceURL.queries.<query-key-1>" : "<query-value-1>", ... "tokenServiceURL.queries.<query-key-N>": "<query-value-N>", } 88 PUBLIC SAP BTP Connectivity Connectivity
- 89. Field/Parameter JSON Key Input/Description URL.headers .<header- key> A static key prefix used as a namespace grouping of the URL's HTTP headers whose values will be sent to the target endpoint. For each HTTP header's key, you must add a URL.headers prefix separated by dot-delimiter. For example: Sample Code { ... "URL.headers.<header-key-1>" : "<header- value-1>", ... "URL.headers.<header-key-N>": "<header-value- N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. URL.queries .<query- key> A static key prefix used as a namespace grouping of URL's query parameters whose values will be sent to the target endpoint. For each query parameter's key, you must add a URL.queries prefix separated by dot-delimiter. For example: Sample Code { ... "URL.queries.<query-key-1>" : "<query- value-1>", ... "URL.queries.<query-key-N>": "<query-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. tokenServic e.KeyStoreL ocation Contains the name of the certificate configuration to be used. This property is re quired when using client certificates for authentication. See OAuth with X.509 Client Certificates [page 109]. SAP BTP Connectivity Connectivity PUBLIC 89
- 90. Field/Parameter JSON Key Input/Description tokenServic e.KeyStoreP assword Contains the password for the certificate configuration (if one is needed) when using client certificates for authentication. See OAuth with X.509 Client Certificates [page 109]. x_user_toke n.jwks Base64-encoded JSON web key set, containing the signing keys which are used to validate the JWT provided in the X-User-Token header. For more information, see JWK Set Format . x_user_toke n.jwks_uri URI of the JSON web key set, containing the signing keys which are used to validate the JWT provided in the X-User-Token header. For more information, see OpenID Connect Discovery . Back to Content [page 86] Example: AuthTokens Object Response The response for "find destination" contains an authTokens object in the format given below. For more information on the fields in authTokens, see "Find Destination" Response Structure [page 196]. Sample Code "authTokens": [ { "type": "Bearer", "value": "eyJhbGciOiJSUzI1NiIsInR5cC...", "http_header": { "key":"Authorization", "value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..." } } ] Back to Content [page 86] Related Information Exchanging User JWTs via OAuth2UserTokenExchange Destinations [page 204] 90 PUBLIC SAP BTP Connectivity Connectivity
- 91. 1.1.3.2.7 SAP Assertion SSO Authentication Create and configure an SAP Assertion SSO destination for an application in the Cloud Foundry environment. Caution Authentication type SAP Assertion SSO is deprecated and will be removed soon. The recommended authentication types for establishing single sign-on (SSO) are: ● Principal Propagation SSO Authentication [page 68] for on-premise connections. ● OAuth SAML Bearer Assertion Authentication [page 70] or SAML Assertion Authentication [page 105] for Internet connections. Context By default, all SAP systems accept SAP assertion tickets for user propagation. Note For more information, see Authentication Assertion Tickets. The aim of the SAPAssertionSSO destination is to generate such an assertion ticket in order to propagate the currently logged-on SAP BTP user to an SAP backend system. You can only use this authentication type if the user IDs on both sides are the same. The following diagram shows the elements of the configuration process on the SAP BTP and in the corresponding backend system: SAP BTP Connectivity Connectivity PUBLIC 91
- 92. Configuration Steps 1. Configure the backend system to accept SAP assertion tickets signed by a trusted x.509 key pair. For more information, see Configuring a Trust Relationship for SAP Assertion Tickets. 2. Create and configure an SAPAssertionSSO destination using the properties listed below in the SAP BTP Destination service. For more information, see: ○ Access the Destinations Editor [page 40] ○ Create HTTP Destinations [page 43] ○ Destination service REST API Properties The following credentials must be specified: Property Description Required Name Destination name. It must be the same as the destination name you use in the configuration tools, that is, Destinations editor (cockpit). Type Destination type. Use HTTP for all HTTP(S) destination. URL URL of the protected resource on the called application. Authentication Authentication type. Use SAPAssertionSSO as a value. IssuerSID This system ID should be trusted by the backend system. IssuerClient This client ID should be trusted by the backend system. RecipientSID System ID (SID) of the backend system. RecipientClient Client ID of the backend system. Certificate A base64 encoded certificate that is trusted by the SAP sys tem. SigningKey A base64 encoded signing/private key that is trusted by the SAP system. 92 PUBLIC SAP BTP Connectivity Connectivity
- 93. Property Description (Deprecated) SystemUser Note Deprecated. This property will be removed soon. Optional property. ● If specified, all SAP assertion tickets are generated with the specified user ID. ● If not specified, all SAP assertion tickets are sent on be half of the currently logged-on user. Thus, if the current user needs to be propagated, do not use this property. ProxyType You can use both proxy types Internet and OnPremise. CloudConnectorLocationId Optional property. As of Cloud Connector version 2.9.0, you can connect multi ple Cloud Connectors to an account as long as their location ID is different. The value defines the location ID identifying the Cloud Connector over which the connection is opened. The default value is an empty string identifying the Cloud Connector that is connected without any location ID, which is also the case for all Cloud Connector versions prior to 2.9.0. Additional userIdSource When this property is set, you can choose which claim in a JWT (JSON Web token) to be considered as <user ID> field in the generated assertion. x_user_token.jwks_uri URI of the JSON web key set, containing the signing keys which are used to validate the JWT provided in the X-User- Token header. For more information, see OpenID Connect Discovery . x_user_token.jwks Base64-encoded JSON web key set, containing the signing keys which are used to validate the JWT provided in the X- User-Token header. For more information, see JWK Set Format . SAP BTP Connectivity Connectivity PUBLIC 93
- 94. Property Description URL.headers.<header-key> A static key prefix used as a namespace grouping of the URL's HTTP headers whose values will be sent to the target endpoint. For each HTTP header's key, you must add a URL.headers prefix separated by dot-delimiter. For exam ple: Sample Code { ... "URL.headers.<header-key-1>" : "<header-value-1>", ... "URL.headers.<header-key-N>": "<header-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. 94 PUBLIC SAP BTP Connectivity Connectivity
- 95. Property Description URL.queries.<query-key> A static key prefix used as a namespace grouping of URL's query parameters whose values will be sent to the target endpoint. For each query parameter's key, you must add a URL.queries prefix separated by dot-delimiter. For exam ple: Sample Code { ... "URL.queries.<query-key-1>" : "<query-value-1>", ... "URL.queries.<query-key-N>": "<query-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. Example { "Name": "weather", "Type": "HTTP", "Authentication": "SAPAssertionSSO", "IssuerSID": "JAV", "IssuerClient": "000", "RecipientSID": "SAP", "RecipientClient": "100", "Certificate": "MIICiDCCAkegAwI...rvHTQ==", "SigningKey": "MIIBSwIB...RuqNKGA=" } The response for "find destination" contains an authTokens object in the format given below. For more information on the fields in authTokens, see "Find Destination" Response Structure [page 196]. Sample Code "authTokens": [ { SAP BTP Connectivity Connectivity PUBLIC 95
- 96. "type": "MYSAPSSO2", "value": "AjExMDACAANKQVYDA...", "http_header": { "key":"MYSAPSSO2", "value":"AjExMDACAANKQVYDA..." } } ] 1.1.3.2.8 OAuth Password Authentication Learn about the OAuth password authentication type for HTTP destinations in the Cloud Foundry environment: use cases, supported properties and examples. Content Overview [page 96] Properties [page 96] Example: OAuth Token Service [page 99] Overview SAP BTP provides support for applications to use the OAuth password grant flow for consuming OAuth- protected resources. The client credentials as well as the user name and password are used to request an access token from an OAuth server, referred to as token service below. Access token retrieval is performed automatically by the Destination service when using the "find destination" REST endpoint. Back to Content [page 96] Properties The table below lists the destination properties needed for the OAuth2Password authentication type. 96 PUBLIC SAP BTP Connectivity Connectivity
- 97. Property Description Required Name Destination name. It must be the same as the destination name you use for the configuration tools, that is, the console client and Destinations editor (cockpit). Type Destination type. Choose HTTP (for HTTP or HTTPS communication). URL The URL of the protected resource being accessed. ProxyType You can only use proxy type Internet. Authenticatio n Authentication type. Use OAuth2Password as value. clientId Client ID used to retrieve the access token. clientSecret Client secret for the client ID. User The user name for the user trying to get a token. Password The password for the user trying to get a token. tokenServiceU RL Token retrieval URL of the OAuth server. Additional scope The value of the OAuth 2.0 scope parameter, expressed as a list of space-delimited, case-sensitive strings. tokenServiceU RL.headers.<h eader-key> A static key prefix used as a namespace grouping of the tokenServiceUrl's HTTP headers. Its values will be sent to the token service during token retrieval. For each HTTP header's key you must add a 'tokenServiceURL.headers' prefix separated by dot delimiter. For example: Sample Code { ... "tokenServiceURL.headers.<header-key-1>" : "<header- value-1>", ... "tokenServiceURL.headers.<header-key-N>": "<header-value- N>", } SAP BTP Connectivity Connectivity PUBLIC 97
- 98. Property Description tokenServiceU RL.queries.<q uery-key> A static key prefix used as a namespace grouping of tokenServiceUrl's query parameters. Its values will be sent to the token service during token retrieval. For each query paramester's key you must add a 'tokenServiceURL.queries' prefix separated by dot delimiter. For example: Sample Code { ... "tokenServiceURL.queries.<query-key-1>" : "<query- value-1>", ... "tokenServiceURL.queries.<query-key-N>": "<query-value-N>", } tokenService. KeyStoreLocat ion Contains the name of the certificate configuration to be used. This property is required when using client certificates for authentication. See OAuth with X.509 Client Certificates [page 109]. tokenService. KeyStorePassw ord Contains the password for the certificate configuration (if one is needed) when using client certifi- cates for authentication. See OAuth with X.509 Client Certificates [page 109]. URL.headers.< header-key> A static key prefix used as a namespace grouping of the URL's HTTP headers whose values will be sent to the target endpoint. For each HTTP header's key, you must add a URL.headers prefix sepa rated by dot-delimiter. For example: Sample Code { ... "URL.headers.<header-key-1>" : "<header-value-1>", ... "URL.headers.<header-key-N>": "<header-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expectation for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. 98 PUBLIC SAP BTP Connectivity Connectivity
- 99. Property Description URL.queries.< query-key> A static key prefix used as a namespace grouping of URL's query parameters whose values will be sent to the target endpoint. For each query parameter's key, you must add a URL.queries prefix separated by dot-delimiter. For example: Sample Code { ... "URL.queries.<query-key-1>" : "<query-value-1>", ... "URL.queries.<query-key-N>": "<query-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expectation for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. Note When the OAuth server is called, the caller side trusts the server based on the trust settings of the destination. For more information, see Server Certificate Authentication [page 65]. Back to Content [page 96] Example: OAuth Token Service Sample Code { "Name": "SapOAuthPassGrant", "Type": "HTTP", "URL": "https://myapp.cfapps.sap.hana.ondemand.com/mypath", "ProxyType": "Internet", "Authentication": "OAuth2Password", "clientId": "my-client-id", "clientSecret": "my-client-pass", "User": "my-username", "Password": "my-password", "tokenServiceURL": "https://authentication.sap.hana.ondemand.com/oauth/ token" } SAP BTP Connectivity Connectivity PUBLIC 99
- 100. The response for "find destination" contains an authTokens object in the format given below. For more information on the fields in authTokens, see "Find Destination" Response Structure [page 196]. Sample Code "authTokens": [ { "type": "Bearer", "value": "eyJhbGciOiJSUzI1NiIsInR5cC...", "http_header": { "key":"Authorization", "value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..." } } ] Back to Content [page 96] 1.1.3.2.9 OAuth JWT Bearer Authentication Learn about the OAuth JWT bearer authentication type for HTTP destinations in the Cloud Foundry environment: use cases, supported properties and examples. Content Overview [page 100] Properties [page 101] Example: AuthTokens Object Response [page 105] Overview To allow an application to call another application, passing the user context, and fetch resources, the caller application must pass an access token. In this authorization flow, the initial user token is passed to the OAuth server as input data. This process is performed automatically by the Destination service, which helps simplifying the application development: You only have to construct the right request to the target URL, by using the outcome (another access token) of the service-side automation. Back to Content [page 100] 100 PUBLIC SAP BTP Connectivity Connectivity
- 101. Properties To configure a destination of this authentication type, you must specify all the required properties. You can do this via SAP BTP cockpit (see Create HTTP Destinations [page 43]), or using the Destination Service REST API [page 59]. The following table shows the properties along with their semantics. Field/Parameter (Cockpit) JSON Key Description Required Authenticati on Authentication OAuth2JWTBearer in this case. Client ID clientId OAuth 2.0 client ID to be used for the user access token exchange. Client Secret clientSecret OAuth 2.0 client secret to be used for the user access token exchange. Name Name Name of the destination. Must be unique for the destination level. Proxy Type ProxyType Choose Internet. OnPremise is not supported for this authentication type. SAP BTP Connectivity Connectivity PUBLIC 101
- 102. Field/Parameter (Cockpit) JSON Key Description Token Service URL tokenServi ceURL The URL of the token service, against which the token exchange is performed. De pending on the Token Service URL Type, this property is interpreted in dif ferent ways during the automatic token retrieval: ● For Dedicated, the token service URL is taken as is. ● For Common, the token service URL is searched for the tenant placeholder {tenant}. {tenant} is resolved as the subdomain of the subaccount on behalf of which the caller is performing the call. If the placeholder is not found, {tenant} is inserted as a subdomain of the token service URL. See Automated Access Token Retrieval [page 205] for information about how the tenant is determined. The subaccount subdomain is mandated during creation of the subaccount, see Create a Subaccount. Examples of interpreting the token service URL for the token service URL type Common, if the call to the Destination service is on behalf of a subaccount subdo main with value mytenant: ● https://authentication.us10.hana.ondemand.com/oauth/ token → https:// mytenant.authentication.us10.hana.ondemand.com/oauth/ token ● https:// {tenant}.authentication.us10.hana.ondemand.com/oauth/ token → https:// mytenant.authentication.us10.hana.ondemand.com/oauth/ token ● https://authentication.myauthserver.com/tenant/ {tenant}/oauth/token → https:// authentication.myauthserver.com/tenant/mytenant/ oauth/token ● https://oauth.{tenant}.myauthserver.com/token → https://oauth.mytenant.myauthserver.com/token Token Service URL Type tokenServi ceURLType ● Choose Dedicated if the token service URL serves only a single tenant. ● Choose Common if the token service URL serves multiple tenants. Type Type Choose HTTP (for HTTP or HTTPS communication). URL URL URL of the target endpoint. Optional Description Description A human-readable description of the destination. Additional 102 PUBLIC SAP BTP Connectivity Connectivity
- 103. Field/Parameter (Cockpit) JSON Key Description scope The value of the OAuth 2.0 scope parameter, expressed as a list of space-delimited, case-sensitive strings. tokenServic eURL.header s.<header- key> A static key prefix used as a namespace grouping of the tokenServiceUrl's HTTP headers. Its values will be sent to the token service during token retrieval. For each HTTP header's key you must add a 'tokenServiceURL.headers' prefix separated by dot delimiter. For example: Sample Code { ... "tokenServiceURL.headers.<header-key-1>" : "<header-value-1>", ... "tokenServiceURL.headers.<header-key-N>": "<header-value-N>", } tokenServic eURL.querie s.<query- key> A static key prefix used as a namespace grouping of tokenServiceUrl's query parameters. Its values will be sent to the token service during token retrieval. For each query paramester's key you must add a 'tokenServiceURL.queries' prefix sepa rated by dot delimiter. For example: Sample Code { ... "tokenServiceURL.queries.<query-key-1>" : "<query-value-1>", ... "tokenServiceURL.queries.<query-key-N>": "<query-value-N>", } x_user_toke n.jwks Base64-encoded JSON web key set, containing the signing keys which are used to validate the JWT provided in the X-User-Token header. For more information, see JWK Set Format . x_user_toke n.jwks_uri URI of the JSON web key set, containing the signing keys which are used to validate the JWT provided in the X-User-Token header. For more information, see OpenID Connect Discovery . SAP BTP Connectivity Connectivity PUBLIC 103
- 104. Field/Parameter (Cockpit) JSON Key Description URL.headers .<header- key> A static key prefix used as a namespace grouping of the URL's HTTP headers whose values will be sent to the target endpoint. For each HTTP header's key, you must add a URL.headers prefix separated by dot-delimiter. For example: Sample Code { ... "URL.headers.<header-key-1>" : "<header- value-1>", ... "URL.headers.<header-key-N>": "<header-value- N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. URL.queries .<query- key> A static key prefix used as a namespace grouping of URL's query parameters whose values will be sent to the target endpoint. For each query parameter's key, you must add a URL.queries prefix separated by dot-delimiter. For example: Sample Code { ... "URL.queries.<query-key-1>" : "<query- value-1>", ... "URL.queries.<query-key-N>": "<query-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. tokenServic e.KeyStoreL ocation Contains the name of the certificate configuration to be used. This property is re quired when using client certificates for authentication. See OAuth with X.509 Client Certificates [page 109]. 104 PUBLIC SAP BTP Connectivity Connectivity
- 105. Field/Parameter (Cockpit) JSON Key Description tokenServic e.KeyStoreP assword Contains the password for the certificate configuration (if one is needed) when using client certificates for authentication. See OAuth with X.509 Client Certificates [page 109]. Back to Content [page 100] Example: AuthTokens Object Response The response for "find destination" contains an authTokens object in the format given below. For more information on the fields in authTokens, see "Find Destination" Response Structure [page 196]. Sample Code "authTokens": [ { "type": "Bearer", "value": "eyJhbGciOiJSUzI1NiIsInR5cC...", "http_header": { "key":"Authorization", "value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cC..." } } ] Back to Content [page 100] 1.1.3.2.10 SAML Assertion Authentication Create and configure an SAML Assertion destination for an application in the Cloud Foundry environment. Context The Destination service lets you generate SAML assertions as per SAML 2.0 specification. You can retrieve a generated SAML assertion from the Destination service by using the SAMLAssertion authentication type, whereas OAuth SAML Bearer Assertion Authentication [page 70] sends the generated SAML assertion to an OAuth server to get a token. The Destination service provides functionality for caching the generated SAML assertion for later use, and caching by the app whenever needed, which helps simplifying application development. SAP BTP Connectivity Connectivity PUBLIC 105
- 106. Properties The table below lists the destination properties for the SAMLAssertion authentication type. Property Description Required Name Name of the destination. Must be unique for the destination level. Type Destination type. Choose HTTP for all HTTP(S) destinations. URL URL of the target endpoint. ProxyType Choose Internet or OnPremise. Authentication Authentication type. Use SAMLAssertion as value. audience Value of the Audience tag, which is part of the generated SAML assertion. For more information, seeSAML 2.0 specifi- cation . authnContextClassRef Value of the AuthnContextClassRef tag, which is part of generated SAML assertion. For more information, see SAML 2.0 specification . Additional clientKey Key that identifies the consumer to the authorization server. nameQualifier When this property is set, the NameQualifier under the NameId tag of the generated SAML assertion is determined in accordance to the value. companyId Company identifier. assertionIssuer Issuer of the SAML assertion. nameIdFormat Value of the NameIdFormat tag, which is part of gener ated SAML Assertion. For more information, see SAML 2.0 specification . userIdSource When this property is set, the user ID in the NameId tag of the generated SAML assertion is determined in accordance to the value of this attribute. For more information, see User Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. x_user_token.jwks Base64-encoded JSON web key set, containing the signing keys which are used to validate the JWT provided in the X- User-Token header. For more information, see JWK Set Format . x_user_token.jwks_uri URI of the JSON web key set, containing the signing keys which are used to validate the JWT provided in the X-User- Token header. For more information, see OpenID Connect Discovery . 106 PUBLIC SAP BTP Connectivity Connectivity
- 107. Property Description URL.headers.<header-key> A static key prefix used as a namespace grouping of the URL's HTTP headers whose values will be sent to the target endpoint. For each HTTP header's key, you must add a URL.headers prefix separated by dot-delimiter. For exam ple: Sample Code { ... "URL.headers.<header-key-1>" : "<header-value-1>", ... "URL.headers.<header-key-N>": "<header-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. SAP BTP Connectivity Connectivity PUBLIC 107
- 108. Property Description URL.queries.<query-key> A static key prefix used as a namespace grouping of URL's query parameters whose values will be sent to the target endpoint. For each query parameter's key, you must add a URL.queries prefix separated by dot-delimiter. For exam ple: Sample Code { ... "URL.queries.<query-key-1>" : "<query-value-1>", ... "URL.queries.<query-key-N>": "<query-value-N>", } Note This is a naming convention. As the call to the target endpoint is performed on the client side, the service only provides the configured properties. The expecta tion for the client-side processing logic is to parse and use them. If you are using higher-level libraries and tools, please check if they support this convention. Example The connectivity destination below provides HTTP access to the OData API of the SuccessFactors Jam. Name=destinationSamlAssertion Type=HTTP URL=https://myXXXXXX-api.s4hana.ondemand.com Authentication=SAMLAssertion ProxyType=Internet audience=https://myXXXXXX.s4hana.ondemand.com authnContextClassRef=urn:oasis:names:tc:SAML:2.0:ac:classes:X509 The response for "find destination" contains an authTokens object in the format given below. For more information on the fields in authTokens, see "Find Destination" Response Structure [page 196]. Sample Code "authTokens": [ { "type": "SAML2.0", "value": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZ...", 108 PUBLIC SAP BTP Connectivity Connectivity
- 109. "http_header": { "key":"Authorization", "value":"SAML2.0 PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZ..." } } ] Related Information Create HTTP Destinations [page 43] Destination Examples [page 48] Exchanging User JWTs via OAuth2UserTokenExchange Destinations [page 204] 1.1.3.2.11 OAuth with X.509 Client Certificates Use an X.509 certificate instead of a secret to authenticate against the authentication server. To perform mutual TLS, you can use an X.509 client certificate instead of a client secret when connecting to the authorization server. To do so, you must create a certificate configuration containing a valid X.509 client certificate or a keystore, and link it to the destination configuration using these properties: Property Description tokenService.KeyStoreLocation Contains the name of the certificate configuration to be used. This property is required. tokenService.KeyStorePassword Contains the password for the certificate configuration (if one is needed). Caution Mutual TLS with an X.509 client certificate is performed only if the tokenService.KeyStoreLocation property is set in the destination configuration. Otherwise, the client secret is used. Supported Certificate Configuration Formats ● Java Keystore (.jks): Requires the tokenService.KeyStorePassword property. ● PKCS12 (.pfx or .p12): Requires the tokenService.KeyStorePassword property. ● PEM-encoded X.509 client certificate and private key (.crt, .cer and .pem): The certificate configuration can contain several valid X.509 certificates and private keys. SAP BTP Connectivity Connectivity PUBLIC 109
- 110. Supported OAuth Flows ● OAuth Client Credentials Authentication [page 80] ● OAuth Password Authentication [page 96] ● OAuth User Token Exchange Authentication [page 86] ● OAuth JWT Bearer Authentication [page 100] 1.1.3.3 RFC Destinations RFC destinations provide the configuration required for communication with an on-premise ABAP system via Remote Function Call. The RFC destination data is used by the Java Connector (JCo) version that is available within SAP BTP to establish and manage the connection. RFC Destination Properties The RFC destination specific configuration in SAP BTP consists of properties arranged in groups, as described below. The supported set of properties is a subset of the standard JCo properties in arbitrary environments. The configuration data is divided into the following groups: ● User Logon Properties [page 111] ● Pooling Configuration [page 113] ● Repository Configuration [page 115] ● Target System Configuration [page 115] ● Parameters Influencing Communication Behavior [page 120] The minimal configuration contains user logon properties and information identifying the target host. This means you must provide at least a set of properties containing this information. Example Name=SalesSystem Type=RFC jco.client.client=000 jco.client.lang=EN jco.client.user=consultant jco.client.passwd=<password> jco.client.ashost=sales-system.cloud jco.client.sysnr=42 jco.destination.pool_capacity=5 jco.destination.peak_limit=10 110 PUBLIC SAP BTP Connectivity Connectivity
- 111. Related Information Invoking ABAP Function Modules via RFC [page 208] 1.1.3.3.1 User Logon Properties JCo properties that cover different types of user credentials, as well as the ABAP system client and the logon language. The currently supported logon mechanism uses user or password as credentials. Property Description jco.client.client Represents the client to be used in the ABAP system. Valid format is a three-digit number. jco.client.lang Optional property. Represents the logon language. If the property is not provided, the user's or system's default lan guage is used. Valid values are two-character ISO language codes or one-character SAP language codes. jco.client.user Represents the user to be used for logging on to the ABAP system. Max. 12 characters long. Note When working with the Destinations editor in the cock pit, enter the value in the <User> field. Do not enter it as additional property. jco.client.alias_user Represents the user to be used for logging on to the ABAP system. Either jco.client.user or jco.client.alias_user must be specified. The alias user may be up to 40 characters long. Note When working with the Destinations editor in the cock pit, enter the value in the <Alias User> field. Do not enter it as additional property. SAP BTP Connectivity Connectivity PUBLIC 111
- 112. Property Description jco.client.passwd Represents the password of the user that is used. Note Passwords in systems of SAP NetWeaver releases lower than 7.0 are case-insensitive and can be only eight char acters long. For releases 7.0 and higher, passwords are case-sensitive with a maximum length of 40. Note When working with the Destinations editor in the cock pit, enter this password in the <Password> field. Do not enter it as additional property. jco.client.tls_client_certificate_logon When set to 1, the client certificate provided by the Key Store, which must be configured in addition, is used for au thentication instead of jco.client.user/ jco.client.alias_user and jco.client.passwd. This property is only relevant for a connection using WebSocket RFC (<Proxy Type>=Inter net). The default value is 0. Note When working with the Destinations editor in the cock pit, the <User>, <Alias User> and <Password> fields are hidden when setting the property to 1. For more information on WebSocket RFC, see also: WebSocket RFC 112 PUBLIC SAP BTP Connectivity Connectivity
- 113. Property Description jco.destination.auth_type Optional property. ● If the property is not provided, its default value CONFIGURED_USER is used, which means that user, password, or other credentials are specified directly. ● To enable single sign-on via principal propagation (which means that the identity logged on in the cloud application is forwarded to the on-premise system), set the value to PrincipalPropagation. In this case, you do not need to provide jco.client.user and jco.client.passwd in the configuration. Note For PrincipalPropagation, you should configure the properties jco.destination.repository.user and jco.destination.repository.passwd in stead, since there are special permissions needed (for metadata lookup in the back end) that not all business application users might have. 1.1.3.3.2 Pooling Configuration Learn about the JCo properties you can use to configure pooling in an RFC destination. Overview This group of JCo properties covers different settings for the behavior of the destination's connection pool. All properties are optional. Property Description jco.destination.pool_capacity Represents the maximum number of idle connec tions kept open by the destination. A value of 0 has the effect of no connection pooling, that is, connec tions will be closed after each request. The default value is 1. jco.destination.peak_limit Represents the maximum number of active connec tions that can simultaneously be created for a desti nation. SAP BTP Connectivity Connectivity PUBLIC 113
- 114. Property Description jco.destination.max_get_client_time Represents the maximum time in milliseconds to wait for a free connection in case the maximum number of active connections is already allocated by applications. jco.destination.expiration_time Represents the time in milliseconds after which idle connections that are available in the pool can be closed. jco.destination.expiration_check_period Represents the interval in milliseconds for the time out checker thread to check the idle connections in the pool for expiration. jco.destination.pool_check_connection When setting this value to 1, a pooled connection will be checked for corruption before being used for the next function module execution. Thus, it is pos sible to recognize corrupted connections and avoid exceptions being passed to applications when con nectivity is basically working (default value is 0). Note Turning on this check has performance impact for stateless communication. This is due to an additional low-level ping to the server, which takes a certain amount of time for non-cor rupted connections, depending on latency. Pooling Details ● Each destination is associated with a connection factory and, if the pooling feature is used, with a connection pool. ● Initially, the destination's connection pool is empty, and the JCo runtime does not preallocate any connection. The first connection will be created when the first function module invocation is performed. The peak_limit property describes how many connections can be created simultaneously, if applications allocate connections in different sessions at the same time. A connection is allocated either when a stateless function call is executed, or when a connection for a stateful call sequence is reserved within a session. ● After the <peak_limit> number of connections has been allocated (in <peak_limit> number of sessions), the next session will wait for at most <max_get_client_time> milliseconds until a different session releases a connection (either finishes a stateless call or ends a stateful call sequence). In case the waiting session does not get any connection during the <max_get_client_time> period, the function request will be aborted with JCoException with the key JCO_ERROR_RESOURCE. ● Connections that are no longer used by applications are returned to the destination pool. There is at most a <pool_capacity> number of connections kept open by the pool. Further connections (<peak_limit> - <pool_capacity>) will be closed immediately after usage. The pooled connections (open connections in the pool) are marked as expired if they are not used again during <expiration_time> milliseconds. All expired connections will be closed by a timeout checker thread which executes the check every <expiration_check_period> milliseconds. 114 PUBLIC SAP BTP Connectivity Connectivity
- 115. 1.1.3.3.3 Repository Configuration JCo properties that allow you to define the behavior of the repository that dynamically retrieves function module metadata. All properties below are optional. Alternatively, you can create the metadata in the application code, using the metadata factory methods within the JCo class, to avoid additional round-trips to the on-premise system. Property Description jco.destination.repository_destination Specifies which destination should be used for repository queries. If the destination does not exist, an error occurs when trying to retrieve the repository. Defaults to itself. jco.destination.repository.user Optional property. If this property is set, and the repository destination is not set, it is used as the user for repository queries. This configuration option allows using a different user for repository lookups with a single destination configu- ration, and restricting this user's permissions accordingly. See also SAP Note 460089 . Note When working with the Destinations editor in the cock pit, enter the value in the <Repository User> field. Do not enter it as additional property. jco.destination.repository.passwd Represents the password for a repository user. If you use such a user, this property is mandatory. Note When working with the Destinations editor in the cock pit, enter this password in the <Repository Password> field. Do not enter it as additional property. 1.1.3.3.4 Target System Configuration Learn about the JCo properties you can use to configure the target sytem information in an RFC destination (Cloud Foundry environment). Note This documentation refers to SAP BTP, Cloud Foundry environment. If you are looking for information about the Neo environment, see Target System Configuration (Neo environment). SAP BTP Connectivity Connectivity PUBLIC 115
- 116. Content Overview [page 116] Proxy Types [page 116] Direct Connection [page 117] Load Balancing Connection [page 117] WebSocket Connection [page 118] Overview You can use the following configuration types alternatively: ● Direct connection to an ABAP application server ● Load balancing connection to a group of ABAP application servers via a message server ● WebSocket connection to an ABAP application server (RFC over Internet) Note When using a WebSocket connection, the target ABAP system must be exposed to the Internet. Depending on the configuration you use, different properties are mandatory or optional. To improve performance, consider using optional properties additionally, such as jco.client.serialization_format. For more information, see JCo documentation . Back to Content [page 116] Proxy Types The field <Proxy Type> lets you choose between Internet and OnPremise. When choosing OnPremise, the RFC communication is routed over a Cloud Connector that is connected to the subaccount. When choosing Internet, the RFC communciation is done over a WebSocket connection. Back to Content [page 116] 116 PUBLIC SAP BTP Connectivity Connectivity
- 117. Direct Connection To use a direct connection (connection without load balancing) to an application server over Cloud Connector, you must set the value for <Proxy Type> to OnPremise. Property Description jco.client.ashost Represents the application server host to be used. For con figurations on SAP BTP, the property must match a virtual host entry in the Cloud Connector Access Control configura- tion. The property indicates that a direct connection is es tablished. jco.client.sysnr Represents the so-called "system number" and has two dig its. It identifies the logical port on which the application server is listening for incoming requests. For configurations on SAP BTP, the property must match a virtual port entry in the Cloud Connector Access Control configuration. Note The virtual port in the above access control entry must be named sapgw<##>, where <##> is the value of sysnr. jco.client.client Three-digit ABAP client number. Defines the client of the tar get ABAP system. Back to Content [page 116] Load Balancing Connection To use load balancing to a system over Cloud Connector, you must set the value for <Proxy Type> to OnPremise. Property Description jco.client.mshost Represents the message server host to be used. For configu- rations on SAP BTP, the property must match a virtual host entry in the Cloud Connector Access Control configuration. The property indicates that load balancing is used for estab lishing a connection. jco.client.group Optional property. Identifies the group of application servers that is used, the so-called "logon group". If the property is not specified, the group PUBLIC is used. SAP BTP Connectivity Connectivity PUBLIC 117
- 118. Property Description jco.client.r3name Represents the three-character system ID of the ABAP sys tem to be addressed. For configurations on SAP BTP, the property must match a virtual port entry in the Cloud Connector Access Control configuration. Note The virtual port in the above access control entry must be named sapms<###>, where <###> is the value of r3name. jco.client.msserv Represents the port on which the message server is listening for incoming requests. you can use this property as an alter native to jco.client.r3name. One of these two must be present. For configurations on SAP BTP, the property must match a virtual port entry in the Cloud Connector Access Control configuration. You can therefore avoid look ups in the /etc/services file (<Install_Drive> WindowsSystem32driversetcservices) on the Cloud Connector host. jco.client.client Three-digit ABAP client number. Defines the client of the tar get ABAP system. Back to Content [page 116] WebSocket Connection To use a direct connection over WebSocket, you must set the value for <Proxy Type> to Internet. Prerequisites ● Your target system is an ABAP server as of S/4HANA (on-premise) version 1909, or a cloud ABAP system. ● Your SAP Java buildpack version is at least 1.26.0. Property Description jco.client.wshost Represents the WebSocket RFC server host on which the tar get ABAP system is running. The system must be exposed to the Internet. jco.client.wsport Represents the WebSocket RFC server port on which the tar get ABAP system is listening. jco.client.client Three-digit ABAP client number. Defines the client of the tar get ABAP system. 118 PUBLIC SAP BTP Connectivity Connectivity
- 119. Property Description jco.client.tls_trust_all If set to 1, all server certificates are considered trusted dur ing TLS handshake. If set to 0, either a dedicated trust store must be configured, or the JDK trust store is used as default. Default value is 0. Note We recommend that you do not use value 1 ("trust all") in productive scenarios, but only for demo/test pur poses. <Trust Store Location> 1. When used in local environment 2. When used in cloud environment If you don't want to use the default JDK trust store (option Use default JDK truststore is unchecked), you must enter a <Trust Store Location>. This field indicates the path to the JKS file which contains trusted certificates (Certificate Authorities) for authentication against a remote client. 1. The relative path to the JKS file. The root path is the server's location on the file system. 2. The name of the JKS file. Note If the <Trust Store Location> is not specified, the JDK trust store is used as a default trust store for the destination. <Trust Store Password> Password for the JKS trust store file. This field is mandatory if <Trust Store Location> is used. Note You can upload trust store JKS files using the same command as for uploading destination configuration property files. You only need to specify the JKS file instead of the destination configuration file. Note Connections to remote services which require Java Cryptography Extension (JCE) unlimited strength jurisdiction policy are not supported. See also WebSocket RFC (ABAP Platform documentation). Back to Content [page 116] SAP BTP Connectivity Connectivity PUBLIC 119
- 120. 1.1.3.3.5 Parameters Influencing Communication Behavior JCo properties that allow you to control the connection to an ABAP system. All properties are optional. Property Description jco.client.trace Defines whether protocol traces are created. Valid values are 1 (trace is on) and 0 (trace is off). The default value is 0. jco.client.codepage Declares the 4-digit SAP codepage that is used when initiat ing the connection to the backend. The default value is 1100 (comparable to iso-8859-1). It is important to provide this property if the password that is used contains characters that cannot be represented in 1100. jco.client.delta Enables or disables table parameter delta management. It is enabled if set to 1, and respectively disabled if set to 0. The default value is 1. jco.client.cloud_connector_version Defines the Cloud Connector version used for establishing a connection to the on-premise system. The default value is 2. Currently, no other values are supported. jco.client.cloud_connector_location_id As of Cloud Connector 2.9.0, you can connect multiple Cloud Connectors to a subaccount as long as their location ID is different. The location ID specifies the Cloud Connector over which the connection is opened. The default value is an empty string identifying the Cloud Connector that is con nected without any location ID. This is also valid for all Cloud Connector versions prior to 2.9.0. Note When working with the Destinations editor in the cock pit, enter the Cloud Connector location ID in the <Location ID> field. Do not enter it as additional property. jco.client.serialization_format Defines the serialization format that is used when transfer ring function module data to the partner system. The prop erty impacts the serialization behavior of function module data. Valid values are columnBased and rowBased. If you choose columnBased, the fast RFC serialization is used, as long as the partner system supports it, see SAP Note 2372888 . When choosing the rowBased option, classic or basXML serialization are used. The default value is rowBased. 120 PUBLIC SAP BTP Connectivity Connectivity
- 121. Property Description jco.client.network Defines which network type is expected to be used for the destination.The property impacts the serialization behavior of function module data, see SAP Note 2372888 . Valid values are WAN and LAN. The default value is LAN. 1.1.3.4 Principal Propagation Enable single sign-on (SSO) by forwarding the identity of cloud users to a remote system or service (Cloud Foundry environment). Content Overview [page 121] Scenario: Cloud to On-Premise [page 122] Configuration: Cloud to On-Premise [page 123] Scenario: Cloud to Cloud [page 123] Configuration: Cloud to Cloud [page 124] Overview The Connectivity and Destination services let you forward the identity of a cloud user to a remote system. This process is called principal propagation (also known as user propagation or user principal propagation). It uses a JSON Web token (JWT) as exchange format for the user information. Two scenarios are supported: Cloud to on-premise (using the Connectivity service) and cloud to cloud (using the Destination service). ● Cloud to on-premise: The user is propagated from a cloud application to an on-premise system using a destination configuration with authentication type PrincipalPropagation. Note This scenario requires the Cloud Connector to connect to your on-premise system. ● Cloud to cloud: The user is propagated from a cloud application to another remote (cloud) system using a destination configuration with authentication type OAuth2SAMLBearerAssertion. For more information on setting up destinations, see Create HTTP Destinations [page 43]. SAP BTP Connectivity Connectivity PUBLIC 121
- 122. Back to Content [page 121] Scenario: Cloud to On-Premise 1. A user logs in to the cloud application. Its identity is established by an identity provider (this can be the default IdP for the subaccount or another trusted IdP). 2. The cloud application then uses a user exchange token to propagate the user to the Connectivity service. See also Configure Principal Propagation via User Exchange Token [page 174]. Optionally, the application may use the Destination service to externalize the connection configuration that points to the target on-premise system. See also Consuming the Destination Service [page 189]. 3. The Connectivity service forwards the JWT (that represents the user) to the Cloud Connector. 4. The Cloud Connector receives the JWT, verifies it, extracts the attributes, and uses its STS (security token service) component to issue a new token (for example, an X.509 certificate) with the same or similar attributes to assert the identity to the backend (BE1-BEm). The Cloud Connector and the cloud application share the same trust settings, see Set Up Trust for Principal Propagation [page 341]. 5. The Cloud Connector sends the new token (for example, an X.509 certificate) to the backend system. Back to Content [page 121] 122 PUBLIC SAP BTP Connectivity Connectivity
- 123. Configuration: Cloud to On-Premise Task Type Task Operator Set Up Trust for Principal Propagation [page 341] (Cloud Connector) Configure Principal Propagation for HTTPS [page 347] (Cloud Connector) Configure a Subject Pattern for Principal Propagation [page 359] (Cloud Connector) Developer Configure Principal Propagation via User Exchange Token [page 174] (Connectivity service) Back to Content [page 121] Scenario: Cloud to Cloud 1. A user logs in to the cloud application. Its identity is established by an identity provider (this can be the default IdP for the subaccount or another trusted IdP). 2. When the application retrieves an OAuthSAMLBearer destination, the user is made available to the Destination Service by means of a user exchange JWT. The service then wraps the user identity in a SAML assertion, signs it with the subaccount's private key and sends it to the specified OAuth token service. SAP BTP Connectivity Connectivity PUBLIC 123
- 124. 3. The OAuth token service accepts the SAML assertion and returns an OAuth access token. In turn, the Destination service returns both the destination and the access token to the requesting application. 4. The application uses the destination properties and the access token to consume the remote API. You can set up user propagation for connections to applications in different cloud systems or environments. Find the basic configuration steps and typical use cases in section Configuration: Cloud to Cloud [page 124]. Back to Content [page 121] Configuration: Cloud to Cloud Task Type Task Operator Set up Trust Between Systems [page 124] Operator and/or Developer User Propagation via SAML 2.0 Bearer Assertion Flow [page 200] (Destination service) Use Cases: Cloud to Cloud ● Scenario: User Propagation from the Cloud Foundry Environment to SAP S/4HANA Cloud [page 126] ● Scenario: User Propagation from the Cloud Foundry Environment to SAP SuccessFactors [page 135] ● Scenario: User Propagation between Cloud Foundry Applications [page 141] ● Scenario: User Propagation from the Cloud Foundry Environment to the Neo Environment [page 149] Back to Content [page 121] 1.1.3.4.1 Set up Trust Between Systems Download and configure X.509 certificates as a prerequisite for user propagation from the Cloud Foundry environment. Setting up a trust scenario for user propagation requires the exchange of public keys and certificates between the affected systems, as well as the respective trust configuration within these systems. This enables you to use an HTTP destination with authentication type OAuth2SAMLBearerAssertion for the communication. 124 PUBLIC SAP BTP Connectivity Connectivity
- 125. A trust scenario can include user propagation from the Cloud Foundry environment to another SAP BTP environment, to another Cloud Foundry subaccount, or to a remote system outside SAP BTP, like S/4HANA Cloud, C4C, Success Factors, and others. Set Up a Certificate [page 125] Renew a Certificate [page 125] Set Up a Certificate Download and save locally the identifying X509 certificate of the subaccount in the Cloud Foundry environment. 1. In the cloud cockpit, log on with Administrator permission. 2. Navigate to your subaccount in the Cloud Foundry environment. 3. From the left-side menu, choose Connectivity Destinations . 4. Choose the Download Trust button and save locally the X.509 certificate that identifies this subaccount. 5. Configure the downloaded X.509 certificate in the target system to which you want to propagate the user. Renew a Certificate If the X.509 certificate validity is about to expire, you can renew the certificate and extend its validity by another 2 years. 1. In the cloud cockpit, log on with Administrator permission. 2. Navigate to your subaccount in the Cloud Foundry environment. 3. From the left-side menu, choose Connectivity Destinations . 4. Choose the Renew Trust button to trigger a renewal of the existing X509 certificate. SAP BTP Connectivity Connectivity PUBLIC 125
- 126. 5. Choose the Download Trust button and save locally the X.509 certificate that identifies this subaccount. 6. Configure the renewed X.509 certificate in the target system to which you want to propagate the user. Related Information Principal Propagation from the Cloud Foundry to the Neo Environment Scenario: User Propagation from the Cloud Foundry Environment to SAP S/4HANA Cloud [page 126] Scenario: User Propagation from the Cloud Foundry Environment to SAP SuccessFactors [page 135] 1.1.3.4.2 Scenario: User Propagation from the Cloud Foundry Environment to SAP S/4HANA Cloud Configure user propagation (single sign-on), using OAuth communication from the SAP BTP Cloud Foundry environment to S/4HANA Cloud. As OAuth mechanism, you use the OAuth 2.0 SAML Bearer Assertion Flow. Steps Scenario [page 126] Prerequisites [page 127] Configuration Tasks [page 128] Scenario As a customer, you own an SAP BTP global account and have created at least one subaccount therein. Within the subaccount, you have deployed a Web application. Authentication against the Web application is based on a trusted identity provider (IdP) that you need to configure for the subaccount. On the S/4HANA Cloud side, you own an S/4HANA ABAP tenant. Authentication against the S/4HANA ABAP tenant is based on the trusted IdP which is always your Identity Authentication Service (IAS) tenant. Typically, you will configure this S/4HANA Cloud Identity tenant to forward authentication requests to your corporate IdP. 126 PUBLIC SAP BTP Connectivity Connectivity
- 127. Prerequisites ● You have an S/4HANA Cloud tenant and a user with the following business catalogs assigned: Business Role ID Area SAP_BCR_CORE_COM Communication Management SAP_BCR_CORE_IAM Identity and Access Management SAP_BCR_CORE_EXT Extensibility ● You have administrator permission for the configured S/4HANA Cloud IAS tenant. ● You have a subaccount and PaaS tenant in the SAP BTP Cloud Foundry environment. Next Step ● Configuration Tasks [page 128] SAP BTP Connectivity Connectivity PUBLIC 127
- 128. 1.1.3.4.2.1 Configuration Tasks Perform these steps to set up user propagation between S/4HANA Cloud and the SAP BTP Cloud Foundry environment. Tasks 1. Configure Single Sign-On between S/4HANA Cloud and the Cloud Foundry Organization on SAP BTP [page 128] 2. Configure OAuth Communication [page 128] 3. Configure Communication Settings in S/4HANA Cloud [page 129] 4. Configure Communication Settings in SAP BTP [page 132] 5. Consume the Destination and Execute the Scenario [page 135] Configure Single Sign-On between S/4HANA Cloud and the Cloud Foundry Organization on SAP BTP To configure SSO with S/4HANA you must configure trust between the S/4HANA IAS tenant and theCloud Foundry organization, see Manually Establish Trust and Federation Between UAA and Identity Authentication. Configure OAuth Communication Download the certificate from your Cloud Foundry subaccount on SAP BTP. 1. From the SAP BTP cockpit, choose Cloud Foundry environment your global account . 2. Choose or create a subaccount, and from your left-side subaccount menu, go to Connectivity Destinations . 3. Press the Download Trust button. 128 PUBLIC SAP BTP Connectivity Connectivity
- 129. Back to Tasks [page 128] Configure Communication Settings in S/4HANA Cloud 1. Create a Communication User 1. In your S/4HANA Cloud launchpad, choose the application Maintain Communication Users. 2. From the User List view, create a new user. 3. Set <User Name>, <Password> and <Description>. 4. Copy this password, you will need it in a later step. 5. Press the Save on the bottom of the screen. 6. Close the Communication Users application. SAP BTP Connectivity Connectivity PUBLIC 129
- 130. 2. Set up a Communication System for OAuth 1. From the launchpad, choose the application Communication Systems. 2. From the list view, select New. 3. A popup window appears. Enter the <System ID> and the <System Name>, then choose Create. 4. Enter the host name. This is your Cloud Foundry region, for example: cf.eu10.hana.ondemand.com for Europe (Frankfurt). Note For the complete list of standard regions, see Regions. 5. Enable the OAuth Identity Provider. 130 PUBLIC SAP BTP Connectivity Connectivity
- 131. 6. Upload the subaccount certificate that you have downloaded before from the SAP BTP cockpit. 7. From <Signing Certificate Subject>, copy the CN value (for example: cfapps.sap.hana.ondemand.com/a352a17b-<...>) and paste it in the field <Provider Name>. 8. Add the Communication User you have created in the previous step. 9. Save your settings and go back to the launchpad. 3. Create a Communication Arrangement 1. Start the Communication Arrangements application. 2. From the list view, select New. SAP BTP Connectivity Connectivity PUBLIC 131
- 132. 3. In the popup, choose a scenario. For our example, we use SAP_COM_0013. Set the arrangement name, for example SAP_COM_0013_MY_TEST. 4. In the Common Data section of the configuration screen, select the <Communication System> that you have created in the step before. The communication user is added automatically in the Inbound Communication section, and the <Authentication Method> is set to OAuth 2.0. 5. In the Outbound Services section, go to Launch SAP Web IDE and uncheck the Active checkbox of the field <Service Status>. 6. Save your settings and go back to the launchpad. Back to Tasks [page 128] Configure Communication Settings in SAP BTP 1. From the SAP BTP cockpit, choose Cloud Foundry environment your global account . 2. Choose your subaccount, and from the left-side subaccount menu, go to Connectivity Destinations . 3. Press the New Destination button. 4. Enter the following parameters for your destination: 132 PUBLIC SAP BTP Connectivity Connectivity
- 133. Parameter Value Name Enter a meaningful name. Type HTTP Description (Optional) Enter a meaningful description. URL The OData URL, for example https://my300117- api.s4hana.ondemand.com/sap/opu/odata/ IWFND/CATALOGSERVICE;v=2?$format=json Proxy Type Internet Authentication OAuth2SAMLBearerAssertion Audience The URL of your SAP S/4HANA Cloud account. To get it, log on to your SAP S/4HANA Cloud account. Se lect the profile picture. Then choose Settings and copy the value from the <Server> field. Add https:// to the be ginning of this string, for example, https:// my300117.s4hana.ondemand.com. Note This URL does not contain my300117-api, but only my300117. Client Key The name of the communication user you have in the SAP S/4HANA ABAP tenant, e.g VIKTOR. SAP BTP Connectivity Connectivity PUBLIC 133
- 134. Parameter Value Token Service URL For this field, you need the part of the URL before / sap/... that you copied before from Communications Arrangements service URL/service interface: https://my300117- api.s4hana.ondemand.com/sap/bc/sec/ oauth2/token? scope=ADT_0001%20%2fUI5%2fAPP_INDEX_000 1%20%2fIWFND%2fSG_MED_CATALOG_0002 Note This URL is pointing to the scope of the Inbound Services of the communication scenario that we have defined when creating the communication arrange ment. The scopes have a fixed naming and are sepa rated by %20 for the space and %2f for the slash : ○ ADT_001: scope of the Gateway service for ADT. ○ /UI5/APP_INDEX_0001: scope of the UI2 App Index. ○ /IWFND/SG_MED_CATALOG_0002: scope of the Catalog service version 2.0. Token Service User The same user as for the Client Key parameter. Token Service Password The password for the communication user. System User This parameter is not used, leave the field empty. authnContextClassRef urn:oasis:names:tc:SAML: 2.0:ac:classes:X509 Back to Tasks [page 128] 134 PUBLIC SAP BTP Connectivity Connectivity
- 135. Consume the Destination and Execute the Scenario To perform the scenario and execute the request from the source application towards the target application, proceed as follows: 1. Decide on where the user identity will be located when calling the Destination service. For details, see User Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. This will determine how exactly you will perform step 2. 2. Execute a "find destination" request from the source application to the Destination service. For details, see Consuming the Destination Service [page 189] and the REST API documentation . 3. From the Destination service response, extract the access token and URL, and construct your request to the target application. See "Find Destination" Response Structure [page 196] for details on the structure of the response from the Destination service. Back to Tasks [page 128] 1.1.3.4.3 Scenario: User Propagation from the Cloud Foundry Environment to SAP SuccessFactors Configure user propagation from the SAP BTP Cloud Foundry environment to SAP SuccessFactors. Steps Scenario [page 135] Prerequisites [page 136] Concept Overview [page 136] Create an OAuth Client in SAP SuccessFactors [page 137] Create and Consume a Destination for the Cloud Foundry Application [page 139] Scenario ● From an application in the SAP BTP Cloud Foundry environment, you want to consume OData APIs exposed by SuccessFactors modules. SAP BTP Connectivity Connectivity PUBLIC 135
- 136. ● To enable single sign-on, you want to propagate the identity of the application's logged-in user to SuccessFactors. Prerequisites ● In your Cloud Foundry space, you have a deployed application. ● You have an instance of the Destination Service that is bound to the application. ● An instance of the xsuaa service with application plan is bound to the application. Concept Overview A user logs in to the Cloud Foundry application. Its identity is established by an Identity Provider (IdP). This could be the default IdP for the Cloud Foundry subaccount or a trusted IdP, for example the SuccessFactors IdP. When the application retrieves an OAuth2SAMLBearer destination, the user is made available to the Cloud Foundry Destination service by means of a user exchange token, represented by a JSON Web Token (JWT). The service then wraps the user identity in a SAML assertion, signs it with the Cloud Foundry subaccount private key and sends it to the token endpoint of the SuccessFactors OAuth server. To accept the SAML assertion and return an access token, a trust relationship must be set up between SuccessFactors and the Cloud Foundry subaccount public key. You can achieve this by providing the Cloud Foundry subaccount X.509 certificate when creating the OAuth client in SuccessFactors. Users that are propagated from the Cloud Foundry application, are verified by the SuccessFactors OAuth server before granting them access tokens. This means, users that do not exist in the SuccessFactors user store will be rejected. For valid users, the OAuth server accepts the SAML assertion and returns an OAuth access token. In turn, the Destination service returns both the destination and the access token to the requesting application. The application then uses the destination properties and the access token to consume SuccessFactors APIs. 136 PUBLIC SAP BTP Connectivity Connectivity
- 137. Next Steps ● Create an OAuth Client in SAP SuccessFactors [page 137] ● Create and Consume a Destination for the Cloud Foundry Application [page 139] 1.1.3.4.3.1 Create an OAuth Client in SAP SuccessFactors Create an OAuth client in SuccessFactors for user propagation from the SAP BTP Cloud Foundry environment. 1. Download the X.509 certificate from your Cloud Foundry subaccount: In the cloud cockpit, navigate to your Cloud Foundry subaccount and from the left-side subaccount menu, choose Connectivity Destinations . Choose Download Trust to get the certificate for this subaccount. SAP BTP Connectivity Connectivity PUBLIC 137
- 138. 2. Create a SuccessFactors OAuth Client: In SuccessFactors, go to the Admin Center and search for OAuth. Choose Manage OAuth2 Client Applications. 3. Press the Register Client Application button on the right. In the <Application Name> field, provide some arbitrary descriptive name for the client. For <Application URL>, enter the Cloud Foundry host of the application, followed by the subaccount GUID, for example cfapps.stagingaws.hanavlab.ondemand.com/17d146c3-bc6c-4424-8360-7d56ee73bd32. This information is available in the cloud cockpit under subaccount details: 4. In the field <X.509 Certificate>, paste the certificate that you downloaded in step 1. 5. Choose Register to save the OAuth client. 6. Now, locate your client in the list by its application name, choose View in the Actions column and take note of the <API Key> that has been generated for it. You will use this key later in the OAuth2SAMLBearer destination in the Cloud Foundry environment. 138 PUBLIC SAP BTP Connectivity Connectivity
- 139. Next Step ● Create and Consume a Destination for the Cloud Foundry Application [page 139] 1.1.3.4.3.2 Create and Consume a Destination for the Cloud Foundry Application Create and consume an OAuth2SAMLBearerAssertion destination for your Cloud Foundry application. Create the Destination 1. In the cloud cockpit, navigate to your Cloud Foundry subaccount and from the left-side subaccount menu, choose Connectivity Destinations . Choose New Destination and enter a name Then provide the following settings: ○ <URL>: URL of the SuccessFactors OData API you want to consume. ○ <Authentication>: OAuth2SAMLBearerAssertion ○ <Audience>: www.successfactors.com ○ <Client Key>: API Key of the OAuth client you created in SuccessFactors. SAP BTP Connectivity Connectivity PUBLIC 139
- 140. ○ <Token Service URL>: API endpoint URL for the SuccessFactors instance, followed by /oauth/ token and the URL parameter company_id with the company ID, for example https:// apisalesdemo2.successfactors.eu/oauth/token?company_id=SFPART019820. 2. Enter three additional properties: ○ apiKey: the API Key of the OAuth client you created in SuccessFactors. ○ authnContextClassRef: urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession ○ nameIdFormat: ○ urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified, if the user ID will be propagated to a SuccessFactors application, or ○ urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, if the user e-mail will be propagated to SuccessFactors. Consume the Destination and Execute the Scenario To perform the scenario and execute the request from the source application towards the target application, proceed as follows: 1. Decide on where the user identity will be located when calling the Destination service. For details, see User Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. This will determine how exactly you will perform step 2. 2. Execute a "find destination" request from the source application to the Destination service. For details, see Consuming the Destination Service [page 189] and the REST API documentation . 3. From the Destination service response, extract the access token and URL, and construct your request to the target application. See "Find Destination" Response Structure [page 196] for details on the structure of the response from the Destination service. 140 PUBLIC SAP BTP Connectivity Connectivity
- 141. 1.1.3.4.4 Scenario: User Propagation between Cloud Foundry Applications Propagate the identity of a user between Cloud Foundry applications that are located in different subaccounts or regions. Steps Scenario [page 141] Prerequisites [page 141] Concept [page 142] Procedure [page 144] 1. Assemble IdP Metadata for Subaccount 1 [page 144] 2. Establish Trust between Subaccount 1 and Subaccount 2 [page 145] 3. Create an OAuthSAMLBearerAssertion Destination for Application 1 [page 146] 4. Consume the Destination and Execute the Scenario [page 148] Scenario ● You have deployed an application in a Cloud Foundry environment (application 1). ● You want to call another Cloud Foundry application (application 2) in a different subaccount, in the same or another region. ● You want to propagate the identity of the user that is logged in to application 1, to application 2. Back to Steps [page 141] Prerequisites ● You have two applications (application 1 and application 2) deployed in Cloud Foundry spaces in different subaccounts in the same region or even in different regions. ● You have an instance of the Destination service bound to application 1. ● You have a user JWT (JSON Web Token) in application 1 where the call to application 2 is performed. Back to Steps [page 141] SAP BTP Connectivity Connectivity PUBLIC 141
- 142. Concept The identity of a user logged in to application 1 is established by an identity provider (IdP) of the respective subaccount (subaccount 1). Note You can use the default IdP for the Cloud Foundry subaccount or a custom-configured IdP. When the application retrieves an OAuthSAMLBearer destination, the user is made available to the Cloud Foundry Destination service by means of a user exchange JWT. See also User Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. The service then wraps the user identity in a SAML assertion, signs it with subaccount 1's private key (which is part of the special key pair for the subaccount, maintained by the Destination service) and sends it to the authentication endpoint of subaccount 2, which hosts application 2. To make the authentication endpoint accept the SAML assertion and return an access token, you must set up a trust relationship between the two subaccounts, by using subaccount 1's public key. You can achieve this by assembling the SAML IdP metadata, using subaccount 1's public key and setting up a new trust configuration for subaccount 2, which is based on that metadata. This way, users propagated from application 1 can be verified by subaccount 2's IdP before granting them access tokens with their respective scopes in the context of subaccount 2. The authentication endpoint accepts the SAML assertion and returns an OAuth access token. In turn, the Destination service returns both the destination configuration and the access token to the requesting application (application 1). Application 1 then uses the destination properties and the access token to call application 2. Option 1 - Setting up Trust between Subaccounts in the Same Region 142 PUBLIC SAP BTP Connectivity Connectivity
- 143. Option 2 - Setting up Trust between Subaccounts in Different Regions SAP BTP Connectivity Connectivity PUBLIC 143
- 144. Back to Steps [page 141] Procedure Assemble IdP Metadata for Subaccount 1 1. Download the X.509 certificate of subaccount 1. For instructions, see Set up Trust Between Systems [page 124]. The content of the file is shown as: -----BEGIN CERTIFICATE-----<content>-----END CERTIFICATE----- Below, we refer to the value of <content> as ${S1_CERTIFICATE}. 2. In the cockpit, navigate to the overview page of subaccount 1. For details, see Navigate in the Cockpit. Here you can see the landscape domain, subaccount ID and subdomain. Below, we refer to the landscape domain as ${S1_LANDSCAPE_DOMAIN}, to the subaccount ID as ${S1_SUBACCOUNT_ID} and to the subdomain as ${S1_SUBDOMAIN}. 3. In your browser, call https://${S1_SUBDOMAIN}.authentication.${S1_LANDSCAPE_DOMAIN}/ saml/metadata and download the XML file. Within the XML file you can find the following structure: Sample Code <?xml version="1.0" encoding="UTF-8"?> ... <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML: 2.0:bindings:URI" Location="https://${S1_SUBDOMAIN}.authentication.$ {S1_LANDSCAPE_DOMAIN}/oauth/token/alias/<alias>" index="1"/> ... Below, we refer to the value of <alias> as ${S1_ALIAS}. 4. Assemble the new IdP metadata for subaccount 1 by replacing the ${...} placeholders in the following template with the values determined in the previous steps: Sample Code <ns3:EntityDescriptor ID="cfapps.${S1_LANDSCAPE_DOMAIN}/${S1_SUBACCOUNT_ID}" entityID="cfapps.${S1_LANDSCAPE_DOMAIN}/${S1_SUBACCOUNT_ID}" xmlns="http://www.w3.org/2000/09/xmldsig#" 144 PUBLIC SAP BTP Connectivity Connectivity
- 145. xmlns:ns2="http://www.w3.org/2001/04/xmlenc#" xmlns:ns4="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns3="urn:oasis:names:tc:SAML:2.0:metadata"> <ns3:SPSSODescriptor AuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <ns3:KeyDescriptor use="signing"> <KeyInfo> <KeyName>${S1_ALIAS}</KeyName> <X509Data> <X509Certificate> ${S1_CERTIFICATE} </X509Certificate> </X509Data> </KeyInfo> </ns3:KeyDescriptor> </ns3:SPSSODescriptor> <ns3:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <ns3:KeyDescriptor use="signing"> <KeyInfo> <KeyName>${S1_ALIAS}</KeyName> <X509Data> <X509Certificate> ${S1_CERTIFICATE} </X509Certificate> </X509Data> </KeyInfo> </ns3:KeyDescriptor> </ns3:IDPSSODescriptor> </ns3:EntityDescriptor> Back to Steps [page 141] Establish Trust between Subaccount 1 and Subaccount 2 1. In the cockpit, navigate to the overview page for subaccount 2. 2. From the left panel, select Security Trust Configuration . Choose New Trust Configuration. For details, see Establish Trust and Federation with UAA Using Any SAML Identity Provider. 3. Paste the assembled IdP metadata for subaccount 1 in the <Metadata> text box and uncheck Available for User Logon. SAP BTP Connectivity Connectivity PUBLIC 145
- 146. 4. Choose Parse. 5. Enter a <Name> for the trust configuration and choose Save. Note Additionally, you must add users to this new trust configuration and assign appropriate scopes to them. Back to Steps [page 141] Create an OAuthSAMLBearerAssertion Destination for Application 1 1. In the cockpit, navigate to the overview page for subaccount 2. 2. Here you can see the landscape domain, subaccount ID and subdomain of subaccount 2. Below, we refer to the landscape domain as ${S2_LANDSCAPE_DOMAIN}, to the subaccount ID as ${S2_SUBACCOUNT_ID} and to the subdomain as ${S2_SUBDOMAIN}. 146 PUBLIC SAP BTP Connectivity Connectivity
- 147. 3. In your browser, call https://${S2_SUBDOMAIN}.authentication.${S2_LANDSCAPE_DOMAIN}/ saml/metadata and download the XML file. Within the XML file, you can find the following structure. It contains the <audience> and the <alias> variables: Sample Code <?xml version="1.0" encoding="UTF-8"?> <md:EntityDescriptor entityID="<audience>" ...> ... <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML: 2.0:bindings:URI" Location="https://${S2_SUBDOMAIN}.authentication.$ {S2_LANDSCAPE_DOMAIN}/oauth/token/alias/<alias>" index="1"/> ... Below, we refer to the value of <alias> as ${S2_ALIAS} and <audience> as ${S2_AUDIENCE}. 4. In cockpit, navigate to subaccount 1. 5. From the left panel, select Connectivity Destinations . 6. Choose New Destination and configure the values as described below. Replace the ${…} placeholders with the values you determined in the previous steps and sections. Property Value Name Choose any name for your destination. You will use this name to request the destination from the Destination service. Type HTTP URL The URL of application 2, identifying the resource you want to consume. Proxy Type Internet Authentication OAuth2SAMLBearerAssertion Audience ${S2_AUDIENCE} Client Key The clientid of the XSUAA instance in subaccount 2. Can be acquired via a binding or service key. Token Service URL https://${S2_SUBDOMAIN}.authentication. ${S2_LANDSCAPE_DOMAIN}/oauth/token/ alias/${S2_ALIAS} SAP BTP Connectivity Connectivity PUBLIC 147
- 148. Property Value Token Service URL Type Dedicated Token Service User The clientid of the XSUAA instance in subaccount 2. Can be acquired via a binding or service key. Token Service Password The clientsecret of the XSUAA instance in subaccount 2. Can be acquired via a binding or service key. authnContextClassRef urn:oasis:names:tc:SAML: 2.0:ac:classes:PreviousSession Additional Properties Property Value nameIdFormat urn:oasis:names:tc:SAML:1.1:nameid- format:emailAddress Example 7. Choose Save. Back to Steps [page 141] Consume the Destination and Execute the Scenario To perform the scenario and execute the request from application 1, targeting application 2, proceed as follows: 1. Decide on where the user identity will be located when calling the Destination service. For details, see User Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. This will determine how exactly you will perform step 2. 2. Execute a "find destination" request from application 1 to the Destination service. For details, see Consuming the Destination Service [page 189] and the REST API documentation . 148 PUBLIC SAP BTP Connectivity Connectivity
- 149. 3. From the Destination service response, extract the access token and URL, and construct your request to application 2. See "Find Destination" Response Structure [page 196] for details on the structure of the response from the Destination service. Back to Steps [page 141] 1.1.3.4.5 Scenario: User Propagation from the Cloud Foundry Environment to the Neo Environment Propagate the identity of a user from a Cloud Foundry application to a Neo application. Steps Scenario [page 149] Prerequisites [page 150] Concept [page 150] Procedure [page 151] 1. Configure a Local Service Provider for the Neo Subaccount [page 151] 2. Establish Trust between Cloud Foundry and Neo Subaccounts [page 152] 3. Create an OAuth Client for the Neo Application [page 154] 4. Create an OAuth2SAMLBearerAssertion Destination for the Cloud Foundry Application [page 154] 5. Consume the Destination and Execute the Scenario [page 156] Scenario ● You have deployed an application in the Cloud Foundry environment. ● You want to consume OAuth protected APIs exposed by an application deployed in the Neo environment. ● You want to propagate the identity of the user logged in to the Cloud Foundry application, to the Neo application. Back to Steps [page 149] SAP BTP Connectivity Connectivity PUBLIC 149
- 150. Prerequisites ● You have deployed an application in the Cloud Foundry environment. ● You have bound an instance of the Destination Service to the application. ● You have bound an instance of the XSUAA service with the application plan to the application. ● You have deployed an application in the Neo environment. Back to Steps [page 149] Concept The identity of a user logged in to the Cloud Foundry application is established by an identity provider (IdP). Note You can use the default IdP of the Cloud Foundry subaccount or any trusted IdP, for example, the Neo subaccount IdP. When the application retrieves an OAuthSAMLBearer destination, the user is made available to Cloud Foundry Destination service by means of a user exchange JWT (JSON Web Token). The service then wraps the user identity in a SAML assertion, signs it with the Cloud Foundry subaccount private key and sends it to the token endpoint of the OAuth service for the Neo application. To make the Neo application accept the SAML assertion, you must set up a trust relationship between the Neo subaccount and the Cloud Foundry subaccount public key. You can achieve this by adding the Cloud Foundry subaccount X.509 certificate as trusted IdP in the Neo subaccount. Thus, the Cloud Foundry application starts acting as an IdP and any users propagated by it are accepted by the Neo application, even users that do not exist in the IdP. The OAuth service accepts the SAML assertion and returns an OAuth access token. In turn, the Destination service returns both the destination and the access token to the requesting application. The application then uses the destination properties and the access token to consume the remote API. 150 PUBLIC SAP BTP Connectivity Connectivity
- 151. Back to Steps [page 149] Procedure Configure a Local Service Provider for the Neo Subaccount 1. In the cockpit, navigate to your Neo subaccount, choose Security Trust from the left menu, and go to tab Local Service Provider on the right. For <Configuration Type>, select Custom and choose Generate Key Pair. 2. Save the configuration. SAP BTP Connectivity Connectivity PUBLIC 151
- 152. Note IMPORTANT: When you choose Custom for the Local Service Provider type, the default IdP (SAP ID service) will no longer be available. If your scenario requires login to the SAP ID service as well, you can safely skip this step and leave the default settings for the Local Service Provider. Back to Steps [page 149] Establish Trust between Cloud Foundry and Neo Subaccounts 1. Download the X.509 certificate of the Cloud Foundry subaccount: In the cockpit, navigate to your Cloud Foundry subaccount and choose Connectivity Destinations . Press Download Trust to get the certificate for this subaccount. 2. Configure trust in the Neo subaccount: In the cockpit, navigate to your Neo subaccount, choose Trust from the left menu, and select the Application Identity Provider tab on the right. Then choose Add Trusted Identity Provider. 152 PUBLIC SAP BTP Connectivity Connectivity
- 153. In the <Name> field, enter the cfapps host followed by the subaccount GUID, for example cfapps.sap.hana.ondemand.com/bf7f2876-5080-40ad-a56b-fff3ee5cff9d. This information is available in the cockpit, on the overview page of your Cloud Foundry subaccount: In the <Signing Certificate> field, paste the X.509 certificate you downloaded in step 1. Make sure you remove the BEGIN CERTIFICATE and END CERTIFICATE strings. Then check Only for IDP-Initiated SSO and save the configuration: Back to Steps [page 149] SAP BTP Connectivity Connectivity PUBLIC 153
- 154. Create an OAuth Client for the Neo Application 1. In the cockpit, navigate to the Neo subaccount, choose Security OAuth from the left menu, select tab Client, and choose Register New Client: 2. Enter a <Name> for the client. 3. In the <Subscription> field, select your Neo application. 4. For <Authorization Grant> select Authorization Code. 5. Check the Confidential checkbox and provide a secret for the OAuth client. Note Make sure you remember the secret, because it will not be visible later. 6. <Redirect URI> is irrelevant for the OAuth SAML Bearer Assertion flow, so you can provide any URL in the Cloud Foundry application. Back to Steps [page 149] Create an OAuth2SAMLBearerAssertion Destination for the Cloud Foundry Application 1. In the cockpit, navigate to the Cloud Foundry subaccount, choose Connectivity Destinations from the left menu, select the Client tab and press New Destination. 2. Enter a <Name> for the destination, then provide: ○ <URL>: the URL of the Neo application/API you want to consume. 154 PUBLIC SAP BTP Connectivity Connectivity
- 155. ○ <Authentication>: OAuth2SAMLBearerAssertion ○ <Audience>: can be taken from the Neo subaccount, if you choose Security Trust form the left menu, go to the Local Service Provider tab, and copy the value of <Local Provider Name>: ○ <Client Key>: the ID of the OAuth client for the Neo application ○ <Token Service URL>: can be taken from the Branding tab in the Neo subaccount (choose Security OAuth from the left menu): ○ <Token Service User>: again the ID of the OAuth client for the Neo application. ○ <Token Service Password>: the OAuth client secret. Enter two additional properties: ● authnContextClassRef: urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession ● nameIdFormat: ○ urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified, if the user ID is propagated to the Neo application, or ○ urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, if the user email is propagated to the Neo application. SAP BTP Connectivity Connectivity PUBLIC 155
- 156. Back to Steps [page 149] Consume the Destination and Execute the Scenario To perform the scenario and execute the request from the source application towards the target application, proceed as follows: 1. Decide on where the user identity will be located when calling the Destination service. For details, see User Propagation via SAML 2.0 Bearer Assertion Flow [page 200]. This will determine how exactly you will perform step 2. 2. Execute a "find destination" request from the source application to the Destination service. For details, see Consuming the Destination Service [page 189] and the REST API documentation . 3. From the Destination service response, extract the access token and URL, and construct your request to the target application. See "Find Destination" Response Structure [page 196] for details on the structure of the response from the Destination service. Back to Steps [page 149] 1.1.3.5 Multitenancy in the Connectivity Service Using multitenancy for Cloud Foundry applications that require a connection to a remote service or on-premise application. Endpoint Configuration Applications that require a connection to a remote service can use the Connectivity service to configure HTTP or RFC endpoints. In a provider-managed application, such an endpoint can either be once defined by the application provider (Provider-Specific Destination [page 157]), or by each application subscriber (Subscriber- Specific Destination [page 158]). 156 PUBLIC SAP BTP Connectivity Connectivity
- 157. If the application needs to use the same endpoint, independently from the current application subscriber, the destination that contains the endpoint configuration is uploaded by the application provider. If the endpoint should be different for each application subscriber, the destination can be uploaded by each particular application subscriber. Note This connectivity type is fully applicable also for on-demand to on-premise connectivity. Destination Levels You can configure destinations simultaneously on two levels: subaccount and service instance. This means that it is possible to have one and the same destination on more than one configuration level. For more information, see Managing Destinations [page 38]. Destination lookup according to the level, when configured on: Level Lookup Subaccount level Looked up on subaccount level, no matter which destination service instance is used. Service instance level Lookup via particular service instance (in provider or sub scriber subaccount associated with this service instance). When the application accesses the destination at runtime, the Connectivity service does the following: ● For a destination associated with a provider subaccount: 1. Checks if the destination is available on the service instance level. If there is no destination found, it 2. Searches the destination on subaccount level. ● For a destination associated with a subscriber subaccount: 1. Checks if the destination is available on the subscription level. If there is no destination found, it 2. Searches the destination on subaccount level. Back to Top [page 156] Provider-Specific Destination SAP BTP Connectivity Connectivity PUBLIC 157
- 158. Back to Top [page 156] Subscriber-Specific Destination Back to Top [page 156] Related Information Developing Multitenant Applications in the Cloud Foundry Environment 158 PUBLIC SAP BTP Connectivity Connectivity
- 159. 1.1.3.6 Create and Bind a Connectivity Service Instance To use the Connectivity service in your application, you need an instance of the service. Prerequisites When using service plan “lite”, quota management is no longer required for this service. From any subaccount you can consume the service using service instances without restrictions on the instance count. Previously, access to service plan “lite” has been granted via entitlement and quota management of the application runtime. It has now become an integral service offering of SAP BTP to simplify its usage. See also Entitlements and Quotas. Procedure You have two options for creating a service instance – using the CLI or using the SAP BTP cockpit: ● Create and Bind a Service Instance from the CLI [page 159] ○ Example [page 159] ○ Result [page 161] ● Create and Bind a Service Instance from the Cockpit [page 160] ○ Result [page 161] Create and Bind a Service Instance from the CLI Use the following CLI commands to create a service instance and bind it to an application: 1. cf marketplace 2. cf create-service connectivity <service-plan> <service-name> 3. cf bind-service <app-name> <service-name> Back to Procedure [page 159] Example To bind an instance of the Connectivity service "lite" plan to application "myapp", use following commands on the Cloud Foundry command line: SAP BTP Connectivity Connectivity PUBLIC 159
- 160. cf create-service connectivity lite myinstance cf bind-service myapp myinstance Back to Procedure [page 159] Create and Bind a Service Instance from the Cockpit Assuming that you have already deployed your application to the platform, follow these steps to create a service instance and bind it to an application: 1. In the SAP BTP Cockpit, navigate to your application. 2. From the left navigation menu, choose Service Bindings. 3. Choose the Bind Service button. 4. The Bind Service wizard appears. 5. Select the Service from the catalog radio button, then choose Next. 6. From the list of available services, select Connectivity, then choose Next. 7. On the next page of the wizard, select the Create new instance radio button. 8. Leave <Plan> lite selected and choose Next. 9. The next page is used for specifying user-provided parameters in JSON format. If you do not want to do that, skip this step by choosing Next. 10. In the <Instance Name> textbox, enter an unique name for your service instance. 11. Choose Finish. 160 PUBLIC SAP BTP Connectivity Connectivity
- 161. Back to Procedure [page 159] Result When the binding is created, the application gets the corresponding connectivity credentials in its environment variables: Sample Code "VCAP_SERVICES": { "connectivity": [ { "credentials": { "onpremise_proxy_host": "10.0.85.1", "onpremise_proxy_port": "20003", "onpremise_proxy_http_port": "20003", "clientid": "sb-connectivity-app", "clientsecret": "KXqObiN6d9gLA4cS2rOVAahPCX0=", "token_service_url": "<token_service_url>", }, "label": "connectivity", "name": "conn-lite", "plan": "default", "provider": null, "syslog_drain_url": null, "tags": [ "connectivity", "conn", "connsvc" ], "volume_mounts": [] } ], Note "onpremise_proxy_http_port" replaces the deprecated variable "onpremise_proxy_port", which will be removed soon. Same goes for "token_service_url", which replaces "url". Back to Procedure [page 159] 1.1.3.7 Create and Bind a Destination Service Instance To use the Destination service in your application, you need an instance of the service. SAP BTP Connectivity Connectivity PUBLIC 161
- 162. Concept To consume the Destination service, you must provide the appropriate credentials through a service instance and a service binding/service key. The Destination service is publicly visible and cross-consumable from several environments and provides the service plan lite to all those environments. Provisioning a service instance and service key is done in the standard way for the respective environment, see: ● Cloud Foundry: Using Services in the Cloud Foundry Environment ● Kyma: Using Services in the Kyma Environment ● Kubernetes: Consuming SAP BTP Services in Kubernetes with SAP Service Manager Broker Proxy (Service Catalog) ● Other environments: Consuming Services in Other Environments Using the SAP Service Manager Instances In all environments, the Destination service lets you provide a configuration JSON during instance creation or update. Using a Configuration JSON You can pass a configuration JSON during instance creation or update to modify some of the default settings of the instance and/or provide some content to be created during the operation. The detailed structure of the configuration JSON is described in Use a Config.JSON to Create or Update a Destination Service Instance [page 163]. Troubleshooting If you get this failure message: Failed to create all provided configurations. Will delete all on instance level, for configurations on subaccount level you can set policies to handle duplicates: "existing_destinations_policy" with value "update|fail|ignore" and "existing_certificates_policy" with value "fail|ignore". the root cause may be: ● A provided destination or certificate with the same name already exists in this subaccount. Solution: set policies on subaccount level to update or ignore in case of conflicts. "existing_destinations_policy": "update|fail|ignore" "existing_certificates_policy: "fail|ignore" ● A client input error occurred. Solution: check the input, apply correction and try again. ● An internal server error occurred. In this case, please try again later or report a support incident. 162 PUBLIC SAP BTP Connectivity Connectivity
- 163. 1.1.3.7.1 Use a Config.JSON to Create or Update a Destination Service Instance Configure specific parameters in a config.json file to create or update a Destination service instance. When creating or updating a Destination service instance, you can configure the following settings, which are part of the config.json input file (see Open Service Broker API ), both via SAP BTP cockpit or Cloud Foundry command line interface (CLI): Parameter Value Description init_data JSON The data (destinations, certificates) to initialise or update the service instance with. The data can be stored on both service instance data and subaccount data. HTML5Runtime_enabled Boolean Indicates whether the SAP BTP HTML5 runtime should be enabled to work with the service instance on behalf of the HTML5 applications associated with it during deployment. Find the config.json structure below: Sample Code { "HTML5Runtime_enabled" : "true", "init_data" : { "subaccount" : { "existing_destinations_policy": "update|fail|ignore", "existing_certificates_policy": "fail|ignore", "destinations" : [ { ... } ], "certificates" : [ { ... } ] }, "instance" : { "existing_destinations_policy": "update|fail|ignore", "existing_certificates_policy": "fail|ignore", "destinations" : [ { ... } ], "certificates" : [ { SAP BTP Connectivity Connectivity PUBLIC 163
- 164. ... } ] } } } 1.1.4 Developing Applications Consume the Connectivity service and the Destination service from an application in the Cloud Foundry environment. Task Description Consuming the Connectivity Service [page 164] Connect your Cloud Foundry application to an on-premise system. Consuming the Destination Service [page 189] Retrieve and store externalized technical information about the destination that is required to consume a target remote service from your application. Invoking ABAP Function Modules via RFC [page 208] Call a remote-enabled function module (RFM) in an on- premise or cloud ABAP server from your Cloud Foundry ap plication, using the RFC protocol. 1.1.4.1 Consuming the Connectivity Service Connect your Cloud Foundry application to an on-premise system via HTTP. Note To use the Connectivity service with a protocol other than HTTP, see ● Invoking ABAP Function Modules via RFC [page 208] ● Using the TCP Protocol for Cloud Applications [page 180] Tasks 164 PUBLIC SAP BTP Connectivity Connectivity
- 165. Task Type Task Operator and/or Developer Overview [page 165] Prerequisites [page 166] Developer Basic Steps [page 167] 1. Read Credentials from the Environment Variables [page 168] 2. Provide the Destination Information [page 168] 3. Set up the HTTP Proxy for On-Premise Connectivity [page 169] Operator and/or Developer Additional Steps [page 171] ● Authentication against the On-Premise System [page 171] ● Specify a Cloud Connector Location ID [page 171] ● Multitenancy in the Connectivity Service [page 172] Overview Using the Connectivity service, you can connect your Cloud Foundry application to an on-premise system through the Cloud Connector. To achieve this, you must provide the required information about the target system (destination), and set up an HTTP proxy that lets your application access the on-premise system. SAP BTP Connectivity Connectivity PUBLIC 165
- 166. Back to Tasks [page 164] Prerequisites ● You must be a Global Account member to connect through the Connectivity service with the Cloud Connector. See Add Members to Your Global Account. Also Security Administrators (which must be either Global Account members or Cloud Foundry Organization/Space members) can do it. See Managing Security Administrators in Your Subaccount [Feature Set A]. Note To connect a Cloud Connector to your subaccount, you must currently be a Security Administrator. ● You have installed and configured a Cloud Connector in your on-premise landscape for to the scenario you want to use. See Installation [page 273] and Configuration [page 311]. 166 PUBLIC SAP BTP Connectivity Connectivity
- 167. ● You have deployed an application in a landscape of the Cloud Foundry environment that complies with the Business Application Pattern. ● Your application is secured as described in . ● The Connectivity service is a regular service in the Cloud Foundry environment. Therefore, to consume the Connectivity service from an application, you must create a service instance and bind it to the application. See Create and Bind a Connectivity Service Instance [page 159]. ● To get the required authorization for making on-premise calls through the connected Cloud Connector, the application must be bound to an instance of the xsuaa service using the service plan 'application'. The xsuaa service instance acts as an OAuth 2.0 client and grants user access to the bound application. Make sure you set the xsappname property to the name of the application when creating the instance. Find a detailed guide for this procedure in section 3. Creation of the Authorization & Trust Management Instance (aka XSUAA) of the SCN blog How to use SAP BTP Connectivity and Cloud Connector in the Cloud Foundry environment . Note Currently, the only supported protocol for connecting the Cloud Foundry environment to an on-premise system is HTTP. HTTPS is not needed, since the tunnel used by the Cloud Connector is TLS-encrypted. Back to Tasks [page 164] Basic Steps To consume the Connectivity service from your Cloud Foundry application, perform the following basic steps: 1. Read Credentials from the Environment Variables [page 168] 2. Provide the Destination Information [page 168] 3. Set up the HTTP Proxy for On-Premise Connectivity [page 169] Back to Tasks [page 164] SAP BTP Connectivity Connectivity PUBLIC 167
- 168. Read Credentials from the Environment Variables Consuming the Connectivity service requires credentials from the xsuaa and Connectivity service instances which are bound to the application. By binding the application to service instances of the xsuaa and Connectivity service as described in the prerequisites, these credentials become part of the environment variables of the application. You can access them as follows: Sample Code JSONObject jsonObj = new JSONObject(System.getenv("VCAP_SERVICES")); JSONArray jsonArr = jsonObj.getJSONArray("<service name, not the instance name>"); JSONObject credentials = jsonArr.getJSONObject(0).getJSONObject("credentials"); Note If you have multiple instances of the same service bound to the application, you must perform additional filtering to extract the correct credential from jsonArr. You must go through the elements of jsonArr and find the one matching the correct instance name. This code stores a JSON object in the credentials variable. Additional parsing is required to extract the value for a specific key. Note We refer to the result of the above code block as connectivityCredentials, when called for connectivity, and xsuaaCredentials for xsuaa. Back to Tasks [page 164] Provide the Destination Information To consume the Connectivity service, you must provide some information about your on-premise system and the system mappings for it in the Cloud Connector. You require the following: ● The endpoint in the Cloud Connector (virtual host and virtual port) and accessible URL paths on it (destinations). See Configure Access Control (HTTP) [page 370]. 168 PUBLIC SAP BTP Connectivity Connectivity
- 169. ● The required authentication type for the on-premise system. See HTTP Destinations [page 64]. ● Depending on the authentication type, you may need a username and password for accessing the on- premise system. For more details, see Client Authentication Types for HTTP Destinations [page 77]. ● (Optional) You can use a location Id. For more details, see section Specify a Cloud Connector Location ID [page 171]. We recommend that you use the Destination service (see Consuming the Destination Service [page 189]) to procure this information. However, using the Destination service is optional. You can also provide (look up) this information in another appropriate way. Back to Tasks [page 164] Set up the HTTP Proxy for On-Premise Connectivity Proxy Setup The Connectivity service provides a standard HTTP proxy for on-premise connectivity that is accessible by any application. Proxy host and port are available as the environment variables <onpremise_proxy_host> and <onpremise_proxy_http_port>. You can set up the on-premise HTTP proxy like this: Sample Code // get value of "onpremise_proxy_host" and "onpremise_proxy_http_port" from the environment variables // and create on-premise HTTP proxy String connProxyHost = connectivityCredentials.getString("onpremise_proxy_host"); int connProxyPort = Integer.parseInt(credentials.getString("onpremise_proxy_http_port")); Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(connProxyHost, connProxyPort)); // create URL to the remote endpoint you like to call: // virtualhost:1234 is defined as an endpoint in the Cloud Connector, as described in the Required Information section URL url = new URL("http://virtualhost:1234"); // create the connection object to the endpoint using the proxy // this does not open a connection but only creates a connection object, which can be modified later, before actually connecting urlConnection = (HttpURLConnection) url.openConnection(proxy); Note "onpremise_proxy_http_port" replaces the deprecated variable "onpremise_proxy_port", which will be removed soon. SAP BTP Connectivity Connectivity PUBLIC 169
- 170. Authorization To make calls to on-premise services configured in the Cloud Connector through the HTTP proxy, you must authorize at the HTTP proxy. For this, the OAuth Client Credentials flow is used: applications must create an OAuth access token using using the parameters clientid and clientsecret that are provided by the Connectivity service in the environment, as shown in the example code below. When the application has retrieved the access token, it must pass the token to the connectivity proxy using the Proxy-Authorization header. The sample code below uses the following Maven artifacts: ● org.springframework.security:spring-security-oauth2-core ● org.springframework.security:spring-security-oauth2-client Sample Code import org.springframework.security.authentication.AbstractAuthenticationToken; import org.springframework.security.oauth2.client.ClientCredentialsOAuth2AuthorizedCl ientProvider; import org.springframework.security.oauth2.client.OAuth2AuthorizationContext; import org.springframework.security.oauth2.client.OAuth2AuthorizedClientProvider; import org.springframework.security.oauth2.client.registration.ClientRegistration; import org.springframework.security.oauth2.core.AuthorizationGrantType; import org.springframework.security.oauth2.core.OAuth2AccessToken; ... // get value of "clientid" and "clientsecret" from the environment variables String clientid = connectivityCredentials.getString("clientid"); String clientsecret = connectivityCredentials.getString("clientsecret"); // get the URL to xsuaa from the environment variables String xsuaaUrl = xsuaaCredentials.getString("token_service_url"); // make request to UAA to retrieve access token ClientRegistration clientRegistration = ClientRegistration.withRegistrationId("some-id"). authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS). clientId(clientid). clientSecret(clientsecret). authorizationUri(xsuaaUrl + "/oauth/authorize"). tokenUri(xsuaaUrl + "/oauth/token"). build(); OAuth2AuthorizationContext xsuaaContext = OAuth2AuthorizationContext.withClientRegistration(clientRegistration). principal(new AbstractAuthenticationToken(null) { @Override public Object getPrincipal() { return null; } @Override public Object getCredentials() { return null; } 170 PUBLIC SAP BTP Connectivity Connectivity
- 171. @Override public String getName() { return "dummyPrincipalName"; // There is no principal in the client credentials authorization grant but a non-empty name is still required. } }).build(); OAuth2AuthorizedClientProvider clientCredentialsAccessTokenProvider = new ClientCredentialsOAuth2AuthorizedClientProvider(); OAuth2AccessToken token = clientCredentialsAccessTokenProvider.authorize(xsuaaContext).getAccessToken(); // set access token as Proxy-Authorization header in the URL connection urlConnection.setRequestProperty("Proxy-Authorization", token.getTokenType().getValue() + " " + token.getTokenValue()); Note xsuaaCredentials.getString("token_service_url") replaces the deprecated property xsuaaCredentials.getString("url"), which will be removed soon. Back to Tasks [page 164] Authentication against the On-Premise System Depending on the required authentication type for the desired on-premise resource, you may have to set an additional header in your request. This header provides the required information for the authentication process against the on-premise resource. See Authentication to the On-Premise System [page 173]. Back to Tasks [page 164] Specify a Cloud Connector Location ID Note This is an advanced option when using more than one Cloud Connector for a subaccount. For more information how to set the location ID in the Cloud Connector, see Managing Subaccounts [page 328], step 4 in section Subaccount Dashboard. SAP BTP Connectivity Connectivity PUBLIC 171
- 172. As of Cloud Connector 2.9.0, you can connect multiple Cloud Connectors to a subaccount if their location ID is different. Using the header SAP-Connectivity-SCC-Location_ID you can specify the Cloud Connector over which the connection should be opened. If this header is not specified, the connection is opened to the Cloud Connector that is connected without any location ID. This also applies for all Cloud Connector versions prior to 2.9.0. For example: Sample Code // Optionally, if configured, add the SCC location ID. urlConnection.setRequestProperty("SAP-Connectivity-SCC-Location_ID", "orlando"); Back to Tasks [page 164] Multitenancy in the Connectivity Service To consume the Connectivity service from an SaaS application in a multitenant way, the only requirement is that the SaaS application returns the Connectivity service as a dependent service in its dependencies list. For more information about the subscription flow, see Develop the Multitenant Business Application. Back to Tasks [page 164] Related Information Cloud Connector [page 267] Set Up an Application as a Sample Backend System Create and Bind a Connectivity Service Instance [page 159] Authentication to the On-Premise System [page 173] Consuming the Destination Service [page 189] What Is the SAP Authorization and Trust Management Service? Multitarget Applications in the Cloud Foundry Environment Security Invoking ABAP Function Modules via RFC [page 208] Using the TCP Protocol for Cloud Applications [page 180] 172 PUBLIC SAP BTP Connectivity Connectivity
- 173. 1.1.4.1.1 Authentication to the On-Premise System Provide authentication information for the authentication type you use. You can use the Connectivity service in different authentication scenarios: ● No authentication to the on-premise system ● Principal propagation (user propagation) to the on-premise system ● Basic authentication to the on-premise system Procedure For each authentication type, you must provide specific information in the request to the virtual host: ● The SAP-Connectivity-Authentication Header [page 173] ● Authentication Types [page 174] The SAP-Connectivity-Authentication Header Note For the principal propagation scenario, the SAP-Connectivity-Authentication header is only required if you do not use the user exchange token flow, see Configure Principal Propagation via User Exchange Token [page 174]. Applications must propagate the user JWT token (userToken) using the SAP-Connectivity-Authentication header. This is required for the Connectivity service to open a tunnel to the subaccount for which a configuration is made in the Cloud Connector. The following example shows you how to do this using the Spring framework: Sample Code Authentication auth = SecurityContextHolder.getContext().getAuthentication(); if (auth == null) { throw new UserInfoException("User not authenticated"); } OAuth2AuthenticationDetails details = (OAuth2AuthenticationDetails) auth.getDetails(); String userToken = details.getTokenValue(); urlConnection.setRequestProperty("SAP-Connectivity-Authentication", "Bearer " + userToken); Back to Procedure [page 173] SAP BTP Connectivity Connectivity PUBLIC 173
- 174. Authentication Types The required setup for each of the authentication type is as follows: No Authentication If the on-premise system does not need to identify the user, you should use this authentication type. It requires no additional information to be passed with the request. Principal Propagation When you open the application router to access your cloud application, you are prompted to log in. Doing so means that the cloud application now knows your identity. Principal propagation forwards this identity via the Cloud Connector to the on-premise system. This information is then used to grant access without additional input from the user. To achieve this, you do not need to send any additional information from your application, but you must set up the Cloud Connector for principal propagation. See Configuring Principal Propagation [page 340]. Basic Authentication If the on-premise system requires username and password to grant access, the cloud application must provide these data using the Authorization header. The following example shows how to do this: Sample Code // Basic authentication to backend system String credentials = MessageFormat.format("{0}:{1}", backendUser, backendPassword); byte[] encodedBytes = Base64.encodeBase64(credentials.getBytes()); urlConnection.setRequestProperty("Authorization", "Basic " + new String(encodedBytes)); Back to Procedure [page 173] Related Information Configure Principal Propagation via User Exchange Token [page 174] Configure Principal Propagation via OIDC Token [page 178] 1.1.4.1.1.1 Configure Principal Propagation via User Exchange Token Configure a user exchange token for principal propagation (user propagation) from your Cloud Foundry application to an on-premise system. 174 PUBLIC SAP BTP Connectivity Connectivity
- 175. Tasks Task Type Task Operator and/or Developer Scenario [page 175] Developer Solutions [page 175] Generate the Authentication Token [page 176] Scenario For a Cloud Foundry application that uses the Connectivity service, you want the currently logged-in user to be propagated to an on-premise system. For more information, see Principal Propagation [page 121]. Back to Tasks [page 175] Solutions You have two options to implement user propagation: 1. Recommended: The application sends one header containing the user exchange token to the Connectivity proxy: Header: "Proxy-Authorization" : "Bearer <userExchangeAcessToken>" This option is described in detail in Generate the Authentication Token [page 176] below. 2. The application sends two headers to the Connectivity proxy: Header: "SAP-Connectivity-Authentication" : "Bearer <userToken>" Header: "Proxy-Authorization" : "Bearer <accessToken>" For more information about this solution, see also Consuming the Connectivity Service [page 164]. SAP BTP Connectivity Connectivity PUBLIC 175
- 176. Note This solution is supported to guarantee backward compatibility. Back to Tasks [page 175] Generate the Authentication Token To propagate a user to an on-premise system, you must call the Connectivity proxy using a special JWT (JSON Web token). This token is obtained by exchanging a valid user token following the OAuth2 JWT Bearer grant type . ● Example: Obtaining a User Token Following the JWT Bearer Grant Type [page 176] ● Example: Calling the Connectivity Proxy with the Exchanged User Token [page 178] Example: Obtaining a User Token Following the JWT Bearer Grant Type Request: Sample Code POST https://<host: the value of 'url' from Connectivity service credentials in VCAP_SERVICES>/oauth/token Accept: application/json Content-Type: application/x-www-form-urlencoded client_id=<connectivity_service_client_id> client_secret=<connectivity_service_client_secret> grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer token_format=jwt response_type=token assertion=<logged-in-user-JWT> Response: Sample Code { "access_token" : "<new-user-JWT>", "token_type" : "bearer", "expires_in" : 43199, "scope" : "<token-scopes>", "jti" : "7cc917b8bf6347a2aa18d7ac8f38a1c2" } 176 PUBLIC SAP BTP Connectivity Connectivity
- 177. The JWT in access_token, also referred to as user exchange token, now contains the user details. It is used to consume the Connectivity service. In case of a Java application, you can use a library that implements the user exchange OAuth flow. Here is an example of how the userExchangeAcessToken can be obtained using the XSUAA Token Client and Token Flow API : Caution Make sure you get the latest API version. A sample Maven dependency declaration: <dependency> <groupId>com.sap.cloud.security.xsuaa</groupId> <artifactId>token-client</artifactId> <version><latest version (e.g.: 2.7.7)></version> </dependency> Remember The XSUAA Token Client library works with multiple HTTP client libraries. Make sure you have one as Maven dependency. The following sample uses the Apache REST client: Sample Code // service instance specific OAuth client credentials shall be used String connectivityServiceClientId = credentials.getString(CLIENT_ID); String connectivityServiceClientSecret = credentials.getString(CLIENT_SECRET); // get the URL to xsuaa from the environment variables URI xsuaaUri = new URI(xsuaaCredentials.getString("token_service_url")); // use the XSUAA client library to ease the implementation of the user token exchange flow XsuaaTokenFlows tokenFlows = new XsuaaTokenFlows(new DefaultOAuth2TokenService(), new XsuaaDefaultEndpoints(xsUaaUri.toString()), new ClientCredentials(connectivityServiceClientId, connectivityServiceClientSecret)); String userExchangeAcessToken = tokenFlows.userTokenFlow().token(<jwtToken_to_exchange>).execute().getAccessTo ken(); For more information about caching, see also XSUAA Token Client and Token Flow API - Cache . Note xsuaaCredentials.getString("token_service_url") replaces the deprecated property xsuaaCredentials.getString("url"), which will be removed soon. SAP BTP Connectivity Connectivity PUBLIC 177
- 178. See also: XSUAA Token Client and Token Flow API . After obtaining the userExchangeAcessToken, you can use it to consume the Connectivity service. Back to Generate the Authentication Token [page 176] Example: Calling the Connectivity Proxy with the Exchanged User Token As a prerequisite to this step, you must configure the Connectivity proxy to be used by your client, see Set up the HTTP Proxy for On-Premise Connectivity [page 169]. Once the application has retrieved the user exchange token, it must pass the token to the Connectivity proxy via the Proxy-Authorization header. In this example, we use urlConnection as a client. Sample Code // set user exchange token as Proxy-Authorization header in the URL connection urlConnection.setRequestProperty("Proxy-Authorization", "Bearer " + userExchangeAcessToken); Note Alternatively, you can use the basic authentication scheme: Sample Code // Basic authentication to Connectivity Proxy String credentials = MessageFormat.format("{0}:{1}", userExchangeAcessToken, ""); byte[] encodedBytes = Base64.encodeBase64(credentials.getBytes()); urlConnection.setRequestProperty("Proxy-Authorization", "Basic " + new String(encodedBytes)); Back to Generate the Authentication Token [page 176] Back to Tasks [page 175] 1.1.4.1.1.2 Configure Principal Propagation via OIDC Token Configure an OpenID-Connect (OIDC) token for principal propagation (user propagation) from your Cloud Foundry application to an on-premise system. 178 PUBLIC SAP BTP Connectivity Connectivity
- 179. Tasks Task Type Task Operator and/or Developer Scenario [page 179] Developer Solution [page 179] Scenario For a Cloud Foundry application that uses the Connectivity service, you want the currently logged-in user to be propagated via the Cloud Connector to an on-premise system. This user is represented in the cloud application by an OIDC token. For more information, see Principal Propagation [page 121] and the OIDC specification . Back to Tasks [page 179] Solution As of version 2.13.0, the Cloud Connector supports principal propagation for OIDC tokens. If on the cloud application side the user is represented by an OIDC token, the application can send the user principal to the Connectivity service (thus reaching the Cloud Connector), using the SAP-Connectivity-Authentication HTTP header. The Cloud Connector validates the token, extracts the available user data, and enables further processing through a configured subject pattern for the resulting short-lived X.509 client certificate. By default, the user principal is identified by one of the following JWT (JSON web token) attributes: ● user_name SAP BTP Connectivity Connectivity PUBLIC 179
- 180. ● email ● mail ● user_uuid ● sub This list specifies the priority (in descending order from top to bottom) for the default value of ${name} in the subject pattern of the X.509 client certificate. If a token has more than one of the above claims, the value of $ {name} is extracted from the claim with the highest priority by default. For the example token below, the default value of ${name} is [email protected]: Sample Code { "aud": "111111111111-2222-3333-444444444444", "iss": "https://issuer.com", "exp": 2091269073, "iat": 1601901108, "jti": "111222333444555666777888999000", "sub": "test", "email": "[email protected]" } The Cloud Connector administrator can control the exact value to be used as user principal for the subject CN of the X.509 client certificate by configuring a subject pattern. For more information, see Configure a Subject Pattern for Principal Propagation [page 359]. Back to Tasks [page 179] 1.1.4.1.2 Using the TCP Protocol for Cloud Applications Access on-premise systems from a Cloud Foundry application via TCP-based protocols, using a SOCKS5 Proxy. Content Concept [page 181] Restrictions [page 182] Example [page 182] Troubleshooting [page 188] 180 PUBLIC SAP BTP Connectivity Connectivity
- 181. Concept SAP BTP Connectivity provides a SOCKS5 proxy that you can use to access on-premise systems via TCP-based protocols. SOCKS5 is the industry standard for proxying TCP-based traffic (for more information, see IETF RFC 1928 ). The SOCKS5 proxy host and port are accessible through the environment variables, which are generated after binding an application to a Connectivity service instance. For more information, see Consuming the Connectivity Service [page 164]. You can access the host under onpremise_proxy_host, and the port through onpremise_socks5_proxy_port, obtained from the Connectivity service instance. Authentication to the SOCKS5 proxy is mandatory. It involves the usage of a JWT (JSON Web token) access token (for more information, see IETF RFC 7519 ). The JWT can be retrieved through the client_id and client_secret, obtained from the Connectivity service instance. For more information, see Set up the HTTP Proxy for On-Premise Connectivity [page 169], section Authorization. The value of the SOCKS5 protocol authentication method is defined as 0x80 (defined as X'80' in IETF, refer to the official specification SOCKS Protocol Version 5 ). This value should be sent as part of the authentication method's negotiation request (known as Initial Request in SOCKS5). The server then confirms with a response containing its decimal representation (either 128 or -128, depending on the client implementation). After a successful SOCKS5 Initial Request, the authentication procedure follows the standard SOCKS5 authentication sub-procedure, that is SOCKS5 Authentication Request. The request bytes, in sequence, should look like this: Bytes Description 1 byte Authentication method version - currently 1 4 bytes Length of the JWT X bytes X - The actual value of the JWT in its encoded form 1 byte Length of the Cloud Connector location ID (0 if no Cloud Connector location ID is used) Y bytes Optional. Y - The value of the Cloud Connector location ID in base64-encoded form (if the the value of the location ID is not 0) The Cloud Connector location ID identifies Cloud Connector instances that are deployed in various locations of a customer's premises and connected to the same subaccount. Since the location ID is an optional property, you should include it in the request only if it has already been configured in the Cloud Connector. For more information, see Set up Connection Parameters and HTTPS Proxy [page 315] (Step 4). If not set in the Cloud Connector, the byte representing the length of the location ID in the Authentication Request should have the value 0, without including any value for the Cloud Connector location ID (sccLocationId). Back to Content [page 180] SAP BTP Connectivity Connectivity PUBLIC 181
- 182. Restrictions ● You cannot use the provided SOCKS5 proxy as general-purpose proxy. ● Proxying UDP traffic is not supported. Back to Content [page 180] Example The following code snippet demonstrates an example based on the Apache Http Client library and Java code, which represents a way to replace the standard socket used in the Apache HTTP client with one that is responsible for authenticating with the Connectivity SOCKS5 proxy: Sample Code @Override public void connect(SocketAddress endpoint, int timeout) throws IOException { super.connect(getProxyAddress(), timeout); OutputStream outputStream = getOutputStream(); executeSOCKS5InitialRequest(outputStream); // 1. Negotiate authentication method, i.e. 0x80 (128) executeSOCKS5AuthenticationRequest(outputStream); // 2. Negotiate authentication sub-version and send the JWT (and optionally the Cloud Connector Location ID) executeSOCKS5ConnectRequest(outputStream, (InetSocketAddress) endpoint); // 3. Initiate connection to target on-premise backend system } Sample Code private byte[] createInitialSOCKS5Request() throws IOException { ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream(); try { byteArraysStream.write(SOCKS5_VERSION); byteArraysStream.write(SOCKS5_AUTHENTICATION_METHODS_COUNT); byteArraysStream.write(SOCKS5_JWT_AUTHENTICATION_METHOD); return byteArraysStream.toByteArray(); } finally { byteArraysStream.close(); } } private void executeSOCKS5InitialRequest(OutputStream outputStream) throws IOException { byte[] initialRequest = createInitialSOCKS5Request(); outputStream.write(initialRequest); assertServerInitialResponse(); } 182 PUBLIC SAP BTP Connectivity Connectivity
- 183. Sample Code private byte[] createJWTAuthenticationRequest() throws IOException { ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream(); try { byteArraysStream.write(SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION); byteArraysStream.write(ByteBuffer.allocate(4).putInt(jwtToken.getBytes().lengt h).array()); byteArraysStream.write(jwtToken.getBytes()); byteArraysStream.write(ByteBuffer.allocate(1).put((byte) sccLocationId.getBytes().length).array()); byteArraysStream.write(sccLocationId.getBytes()); return byteArraysStream.toByteArray(); } finally { byteArraysStream.close(); } } private void executeSOCKS5AuthenticationRequest(OutputStream outputStream) throws IOException { byte[] authenticationRequest = createJWTAuthenticationRequest(); outputStream.write(authenticationRequest); assertAuthenticationResponse(); } In version 4.2.6 of the Apache HTTP client, the class responsible for connecting the socket is DefaultClientConnectionOperator. By extending the class and replacing the standard socket with the complete example code below, which implements a Java Socket, you can handle the SOCKS5 authentication with ID 0x80. It is based on a JWT and supports the Cloud Connector location ID. Sample Code import java.io.ByteArrayOutputStream; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.net.InetAddress; import java.net.InetSocketAddress; import java.net.Socket; import java.net.SocketAddress; import java.net.SocketException; import java.nio.ByteBuffer; import java.util.Base64; // or any other library for base64 encoding import org.json.JSONArray; // or any other library for JSON objects import org.json.JSONObject; // or any other library for JSON objects import org.json.JSONException; // or any other library for JSON objects public class ConnectivitySocks5ProxySocket extends Socket { private static final byte SOCKS5_VERSION = 0x05; private static final byte SOCKS5_JWT_AUTHENTICATION_METHOD = (byte) 0x80; private static final byte SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION = 0x01; private static final byte SOCKS5_COMMAND_CONNECT_BYTE = 0x01; private static final byte SOCKS5_COMMAND_REQUEST_RESERVED_BYTE = 0x00; private static final byte SOCKS5_COMMAND_ADDRESS_TYPE_IPv4_BYTE = 0x01; private static final byte SOCKS5_COMMAND_ADDRESS_TYPE_DOMAIN_BYTE = 0x03; private static final byte SOCKS5_AUTHENTICATION_METHODS_COUNT = 0x01; SAP BTP Connectivity Connectivity PUBLIC 183
- 184. private static final int SOCKS5_JWT_AUTHENTICATION_METHOD_UNSIGNED_VALUE = 0x80 & 0xFF; private static final byte SOCKS5_AUTHENTICATION_SUCCESS_BYTE = 0x00; private static final String SOCKS5_PROXY_HOST_PROPERTY = "onpremise_proxy_host"; private static final String SOCKS5_PROXY_PORT_PROPERTY = "onpremise_socks5_proxy_port"; private final String jwtToken; private final String sccLocationId; public ConnectivitySocks5ProxySocket(String jwtToken, String sccLocationId) { this.jwtToken = jwtToken; this.sccLocationId = sccLocationId != null ? Base64.getEncoder().encodeToString(sccLocationId.getBytes()) : ""; } protected InetSocketAddress getProxyAddress() { try { JSONObject credentials = extractEnvironmentCredentials(); String proxyHost = credentials.getString(SOCKS5_PROXY_HOST_PROPERTY); int proxyPort = Integer.parseInt(credentials.getString(SOCKS5_PROXY_PORT_PROPERTY)); return new InetSocketAddress(proxyHost, proxyPort); } catch (JSONException ex) { throw new IllegalStateException("Unable to extract the SOCKS5 proxy host and port", ex); } } private JSONObject extractEnvironmentCredentials() throws JSONException { JSONObject jsonObj = new JSONObject(System.getenv("VCAP_SERVICES")); JSONArray jsonArr = jsonObj.getJSONArray("connectivity"); return jsonArr.getJSONObject(0).getJSONObject("credentials"); } @Override public void connect(SocketAddress endpoint, int timeout) throws IOException { super.connect(getProxyAddress(), timeout); OutputStream outputStream = getOutputStream(); executeSOCKS5InitialRequest(outputStream); executeSOCKS5AuthenticationRequest(outputStream); executeSOCKS5ConnectRequest(outputStream, (InetSocketAddress) endpoint); } private void executeSOCKS5InitialRequest(OutputStream outputStream) throws IOException { byte[] initialRequest = createInitialSOCKS5Request(); outputStream.write(initialRequest); assertServerInitialResponse(); } private byte[] createInitialSOCKS5Request() throws IOException { ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream(); try { byteArraysStream.write(SOCKS5_VERSION); byteArraysStream.write(SOCKS5_AUTHENTICATION_METHODS_COUNT); byteArraysStream.write(SOCKS5_JWT_AUTHENTICATION_METHOD); 184 PUBLIC SAP BTP Connectivity Connectivity
- 185. return byteArraysStream.toByteArray(); } finally { byteArraysStream.close(); } } private void assertServerInitialResponse() throws IOException { InputStream inputStream = getInputStream(); int versionByte = inputStream.read(); if (SOCKS5_VERSION != versionByte) { throw new SocketException(String.format("Unsupported SOCKS version - expected %s, but received %s", SOCKS5_VERSION, versionByte)); } int authenticationMethodValue = inputStream.read(); if (SOCKS5_JWT_AUTHENTICATION_METHOD_UNSIGNED_VALUE != authenticationMethodValue) { throw new SocketException(String.format("Unsupported authentication method value - expected %s, but received %s", SOCKS5_JWT_AUTHENTICATION_METHOD_UNSIGNED_VALUE, authenticationMethodValue)); } } private void executeSOCKS5AuthenticationRequest(OutputStream outputStream) throws IOException { byte[] authenticationRequest = createJWTAuthenticationRequest(); outputStream.write(authenticationRequest); assertAuthenticationResponse(); } private byte[] createJWTAuthenticationRequest() throws IOException { ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream(); try { byteArraysStream.write(SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION); byteArraysStream.write(ByteBuffer.allocate(4).putInt(jwtToken.getBytes().lengt h).array()); byteArraysStream.write(jwtToken.getBytes()); byteArraysStream.write(ByteBuffer.allocate(1).put((byte) sccLocationId.getBytes().length).array()); byteArraysStream.write(sccLocationId.getBytes()); return byteArraysStream.toByteArray(); } finally { byteArraysStream.close(); } } private void assertAuthenticationResponse() throws IOException { InputStream inputStream = getInputStream(); int authenticationMethodVersion = inputStream.read(); if (SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION != authenticationMethodVersion) { throw new SocketException(String.format("Unsupported authentication method version - expected %s, but received %s", SOCKS5_JWT_AUTHENTICATION_METHOD_VERSION, authenticationMethodVersion)); } int authenticationStatus = inputStream.read(); if (SOCKS5_AUTHENTICATION_SUCCESS_BYTE != authenticationStatus) { throw new SocketException("Authentication failed!"); } } SAP BTP Connectivity Connectivity PUBLIC 185
- 186. private void executeSOCKS5ConnectRequest(OutputStream outputStream, InetSocketAddress endpoint) throws IOException { byte[] commandRequest = createConnectCommandRequest(endpoint); outputStream.write(commandRequest); assertConnectCommandResponse(); } private byte[] createConnectCommandRequest(InetSocketAddress endpoint) throws IOException { String host = endpoint.getHostName(); int port = endpoint.getPort(); ByteArrayOutputStream byteArraysStream = new ByteArrayOutputStream(); try { byteArraysStream.write(SOCKS5_VERSION); byteArraysStream.write(SOCKS5_COMMAND_CONNECT_BYTE); byteArraysStream.write(SOCKS5_COMMAND_REQUEST_RESERVED_BYTE); byte[] hostToIPv4 = parseHostToIPv4(host); if (hostToIPv4 != null) { byteArraysStream.write(SOCKS5_COMMAND_ADDRESS_TYPE_IPv4_BYTE); byteArraysStream.write(hostToIPv4); } else { byteArraysStream.write(SOCKS5_COMMAND_ADDRESS_TYPE_DOMAIN_BYTE); byteArraysStream.write(ByteBuffer.allocate(1).put((byte) host.getBytes().length).array()); byteArraysStream.write(host.getBytes()); } byteArraysStream.write(ByteBuffer.allocate(2).putShort((short) port).array()); return byteArraysStream.toByteArray(); } finally { byteArraysStream.close(); } } private void assertConnectCommandResponse() throws IOException { InputStream inputStream = getInputStream(); int versionByte = inputStream.read(); if (SOCKS5_VERSION != versionByte) { throw new SocketException(String.format("Unsupported SOCKS version - expected %s, but received %s", SOCKS5_VERSION, versionByte)); } int connectStatusByte = inputStream.read(); assertConnectStatus(connectStatusByte); readRemainingCommandResponseBytes(inputStream); } private void assertConnectStatus(int commandConnectStatus) throws IOException { if (commandConnectStatus == 0) { return; } String commandConnectStatusTranslation; switch (commandConnectStatus) { case 1: commandConnectStatusTranslation = "FAILURE"; break; case 2: commandConnectStatusTranslation = "FORBIDDEN"; break; case 3: commandConnectStatusTranslation = "NETWORK_UNREACHABLE"; break; 186 PUBLIC SAP BTP Connectivity Connectivity
- 187. case 4: commandConnectStatusTranslation = "HOST_UNREACHABLE"; break; case 5: commandConnectStatusTranslation = "CONNECTION_REFUSED"; break; case 6: commandConnectStatusTranslation = "TTL_EXPIRED"; break; case 7: commandConnectStatusTranslation = "COMMAND_UNSUPPORTED"; break; case 8: commandConnectStatusTranslation = "ADDRESS_UNSUPPORTED"; break; default: commandConnectStatusTranslation = "UNKNOWN"; break; } throw new SocketException("SOCKS5 command failed with status: " + commandConnectStatusTranslation); } private byte[] parseHostToIPv4(String hostName) { byte[] parsedHostName = null; String[] virtualHostOctets = hostName.split(".", -1); int octetsCount = virtualHostOctets.length; if (octetsCount == 4) { try { byte[] ipOctets = new byte[octetsCount]; for (int i = 0; i < octetsCount; i++) { int currentOctet = Integer.parseInt(virtualHostOctets[i]); if ((currentOctet < 0) || (currentOctet > 255)) { throw new IllegalArgumentException(String.format("Provided octet %s is not in the range of [0-255]", currentOctet)); } ipOctets[i] = (byte) currentOctet; } parsedHostName = ipOctets; } catch (IllegalArgumentException ex) { return null; } } return parsedHostName; } private void readRemainingCommandResponseBytes(InputStream inputStream) throws IOException { inputStream.read(); // skipping over SOCKS5 reserved byte int addressTypeByte = inputStream.read(); if (SOCKS5_COMMAND_ADDRESS_TYPE_IPv4_BYTE == addressTypeByte) { for (int i = 0; i < 6; i++) { inputStream.read(); } } else if (SOCKS5_COMMAND_ADDRESS_TYPE_DOMAIN_BYTE == addressTypeByte) { int domainNameLength = inputStream.read(); int portBytes = 2; inputStream.read(new byte[domainNameLength + portBytes], 0, domainNameLength + portBytes); } } } SAP BTP Connectivity Connectivity PUBLIC 187
- 188. Back to Example [page 182] Back to Content [page 180] Troubleshooting If the handshake with the SOCKS5 proxy server fails, a SOCKS5 protocol error is returned, see IETF RFC 1928 . The table below shows the most common errors and their root cause in the scenario you use: SOCSK5 Error Code Technical Description Client-Side Error Descrip tion Scenario Error 0x00 SUCCESS Success 0x01 FAILURE Connection closed by back end or general scenario fail ure. 0x02 FORBIDDEN Connection not allowed by ruleset No matching host mapping found in Cloud Connector ac cess control settings, see Configure Access Control (TCP) [page 386]. 0x03 NETWORK_UNREACHABLE The Cloud Connector is not connected to the subaccount and the Cloud Connector Location ID that is used by the cloud application can't be identified. See Connect and Disconnect a Cloud Sub account [page 514] and Managing Subaccounts [page 328], section Proce dure. 0x04 HOST_UNREACHABLE Cannot open connection to the backend, that is, the host is unreachable. 0x05 CONNECTION_REFUSED Authentication failure 0x06 TTL_EXPIRED Not used 0x07 COMMAND_UNSUPPORTED Only the SOCKS5 CONNECT command is supported. 0x08 ADDRESS_UNSUPPORTED Only the SOCKS5 DOMAIN and IPv4 commands are supported. Back to Content [page 180] 188 PUBLIC SAP BTP Connectivity Connectivity
- 189. 1.1.4.2 Consuming the Destination Service Retrieve and store externalized technical information about the destination to consume a target remote service from your Cloud Foundry application. Tasks Task Type Task Operator and/or Developer Overview [page 189] Prerequisites [page 190] Developer Steps [page 191] 1. Read Credentials from the Environment Variables [page 191] 2. Generate a JSON Web Token (JWT) [page 192] 3. Call the Destination Service [page 193] Operator and/or Developer Destination Configuration Attributes [page 196] Overview The Destination service lets you find the destination information that is required to access a remote service or system from your Cloud Foundry application. ● For the connection to an on-premise system, you can optionally use this service, together with (i.e. in addition to) the Connectivity service, see Consuming the Connectivity Service [page 164]. ● For the connection to any other Web application (remote service), you can use the Destination service without the Connectivity service. Consuming the Destination Service includes user authorization via a JSON Web Token (JWT) that is provided by the xsuaa service. SAP BTP Connectivity Connectivity PUBLIC 189
- 190. Back to Tasks [page 189] Prerequisites ● To manage destinations and certificates on service instance level (all CRUD operations), you must be assigned to one of the following roles: OrgManager, SpaceManager or SpaceDeveloper. Note The role SpaceAuditor has only Read permission for destinations and certificates. ● To consume the Destination service from an application, you must create a service instance and bind it to the application. See Create and Bind a Destination Service Instance [page 161]. ● To generate the required JSON Web Token (JWT), you must bind the application to an instance of the xsuaa service using the service plan 'application'. The xsuaa service instance acts as an OAuth 2.0 client and 190 PUBLIC SAP BTP Connectivity Connectivity
- 191. grants user access to the bound application. Make sure that you set the xsappname property when creating the instance. Find a detailed guide for this procedure in section 3. Creation of the Authorization & Trust Management Instance (aka XSUAA) of the SCN blog How to use SAP BTP Connectivity and Cloud Connector in the Cloud Foundry environment . ● You need at least one configured destination, otherwise there will be nothing to retrieve via the service. To access the Destinations editor in the cockpit, follow the steps in Access the Destinations Editor [page 40]. To manage destinations via REST API, see Destination Service REST API [page 59]. Back to Tasks [page 189] Steps To consume the Destination service from your application, perform the following basic steps: 1. Read Credentials from the Environment Variables [page 191] 2. Generate a JSON Web Token (JWT) [page 192] 3. Call the Destination Service [page 193] Back to Tasks [page 189] Read Credentials from the Environment Variables The Destination service stores its credentials in the environment variables. To consume the service, you require the following information: ● The value of clientid, clientsecret and uri from the Destination service credentials. SAP BTP Connectivity Connectivity PUBLIC 191
- 192. ● The values of url from the xsuaa credentials. You can access this information as follows: ● From the CLI, the following command lists the environment variables of <app-name>: cf env <app-name> ● From within the application, the service credential can be accessed as described in Consuming the Connectivity Service [page 164]. Note Below, we refer to the JSONObjects, containing the instance credentials as destinationCredentials (for the Destination service) and xsuaaCredentials (for xsuaa). Back to Tasks [page 189] Generate a JSON Web Token (JWT) Your application must create an OAuth client using the attributes clientid and clientsecret, which are provided by the Destination service instance. Then, you must retrieve a new JWT from UAA and pass it in the Authorization HTTP header. Two examples how to achieve this (Java and cURL): Java: For a Java application, you can use a library that implements the client credentials OAuth flow. Here is an example of how the clientCredentialsTokenFlow can be obtained using the XSUAA Token Client and Token Flow API : Caution Make sure you get the latest API version. A sample Maven dependency declaration: <dependency> <groupId>com.sap.cloud.security.xsuaa</groupId> <artifactId>token-client</artifactId> <version><latest version (e.g.: 2.7.7)></version> </dependency> 192 PUBLIC SAP BTP Connectivity Connectivity
- 193. Remember The XSUAA Token Client library works with multiple HTTP client libraries. Make sure you have one as Maven dependency. The following sample uses the Apache REST client: Sample Code // get value of "clientid" and "clientsecret" from the environment variables String clientid = destinationCredentials.getString("clientid"); String clientsecret = destinationCredentials.getString("clientsecret"); // get the URL to xsuaa from the environment variables URI xsuaaUri = new URI(xsuaaCredentials.getString("url")); // use the XSUAA client library to ease the implementation of the user token exchange flow XsuaaTokenFlows tokenFlows = new XsuaaTokenFlows(new DefaultOAuth2TokenService(), new XsuaaDefaultEndpoints(xsUaaUri.toString()), new ClientCredentials(clientid, clientsecret)); String jwtToken = tokenFlows.clientCredentialsTokenFlow().execute().getAccessToken(); For more information about caching, see also XSUAA Token Client and Token Flow API - Cache . cURL: Sample Code curl -X POST <xsuaa-url>/oauth/token -H 'authorization: Basic <<clientid>:<clientsecret> encoded with Base64>' -H 'content-type: application/x-www-form-urlencoded' -d 'client_id=<clientid>&grant_type=client_credentials' Back to Tasks [page 189] Call the Destination Service When calling the Destination service, use the uri attribute, provided in VCAP_SERVICES, to build the request URLs. Read a Destination by only Specifying its Name ("Find Destination") [page 194] SAP BTP Connectivity Connectivity PUBLIC 193
- 194. Read a Destination Associated with a Subaccount [page 194] Get All Destinations Associated with a Subaccount [page 195] Response Codes [page 196] Read a Destination by only Specifying its Name ("Find Destination") This lets you provide simply a name of the destination while the service will search for it. First, the service searches the destinations that are associated with the service instance. If none of the destinations match the requested name, the service searches the destinations that are associated with the subaccount. ● Path: /destination-configuration/v1/destinations/<destination-name> ● Example of a call (cURL): Sample Code curl "<uri>/destination-configuration/v1/destinations/<destination-name>" -X GET -H "Authorization: Bearer <jwtToken>" ● Example of a response (this is a destination found when going through the subaccount destinations): Sample Code { "owner": { "SubaccountId":<id>, "InstanceId":null }, "destinationConfiguration": { "Name": "demo-internet-destination", "URL": "http://www.google.com", "ProxyType": "Internet", "Type": "HTTP", "Authentication": "NoAuthentication" } } Note The response from this type of call contains not only the configuration of the requested destination, but also some additional data. See "Find Destination" Response Structure [page 196]. Back to Call the Destination Service [page 193] Read a Destination Associated with a Subaccount This lets you retrieve the configurations of a destination that is defined within a subaccount, by providing the name of the destination. ● Path: /destination-configuration/v1/subaccountDestinations/<destination-name> 194 PUBLIC SAP BTP Connectivity Connectivity
- 195. ● Example of a call (cURL): Sample Code curl "<uri>/destination-configuration/v1/subaccountDestinations/ <destination name>" -X GET -H "Authorization: Bearer <jwtToken>" ● Example of a response: Sample Code { "Name": "demo-internet-destination", "URL": "http://www.google.com", "ProxyType": "Internet", "Type": "HTTP", "Authentication": "NoAuthentication" } Back to Call the Destination Service [page 193] Get All Destinations Associated with a Subaccount This lets you retrieve the configurations of all destinations that are defined within a subaccount. ● Path: /destination-configuration/v1/subaccountDestinations ● Example of a call (cURL): Sample Code curl "<uri>/destination-configuration/v1/subaccountDestinations" -X GET -H "Authorization: Bearer <jwtToken>" ● Example of a response: Sample Code [ { "Name": "demo-onpremise-destination1", "URL": "http:/virtualhost:1234", "ProxyType": "OnPremise", "Type": "HTTP", "Authentication": "NoAuthentication" }, { "Name": "demo-onpremise-destination2", "URL": "http:/virtualhost:4321", "ProxyType": "OnPremise", "Type": "HTTP", "Authentication": "BasicAuthentication", "User": "myname123", "Password": "123456" } ] SAP BTP Connectivity Connectivity PUBLIC 195
- 196. Back to Call the Destination Service [page 193] Response Codes When calling the Destination service, you may get the following response codes: ● 200: OK (Json of Destination) ● 401: Unauthorized (Authentication Failed) ● 403: Forbidden (Authorization Failed) ● 404: The requested destination could not be found (not applicable to 'get all destinations associated with a subaccount') ● 500: Internal Server Error Back to Call the Destination Service [page 193] Back to Tasks [page 189] Destination Configuration Attributes The JSON object that serves as the response of a successful request (value of the destinationConfiguration property for "Find destination") can have different attributes, depending on the authentication type and proxy type of the corresponding destination. See HTTP Destinations [page 64]. Back to Tasks [page 189] Related Information User Propagation via SAML 2.0 Bearer Assertion Flow [page 200] Destination Service REST API [page 59] Exchanging User JWTs via OAuth2UserTokenExchange Destinations [page 204] Use Cases [page 211] Multitenancy in the Destination Service [page 206] 1.1.4.2.1 "Find Destination" Response Structure Overview of data that are returned by the Destination service for the call type "find destination". 196 PUBLIC SAP BTP Connectivity Connectivity
- 197. Response Structure When you use the "find destination" call (read a destination by only specifying its name), the structure of the response includes four parts: ● The owner of the destination [page 197]. ● The actual destination configuration [page 197]. ● (Optional) Authentication tokens [page 198] that are relevant to the destination. ● (Optional) Certificates [page 199] that are relevant to the destination. Each of these parts is represented in the JSON object as a key-value pair and their values are JSON objects, see Example [page 199]. See also Call the Destination Service [page 193]. Destination Owner ● Key: owner The JSON object that represents the value of this property contains two properties itself: SubaccountId and InstanceId. Depending on where the destination was found (as a service instance destination or a subaccount destination) one of these properties has the value null, and the other one shows the ID of the subaccount/service instance, to which the destination belongs. ● Example: Sample Code "owner": { "SubaccountId": "9acf4877-5a3d-43d2-b67d-7516efe15b11", "InstanceId": null } Back to Response Structure [page 197] Destination Configuration ● Key: destinationConfiguration The JSON object that represents the value of this property contains the actual properties of the destination. To learn more about the available properties, see HTTP Destinations [page 64]. ● Example: Sample Code "destinationConfiguration": { SAP BTP Connectivity Connectivity PUBLIC 197
- 198. "Name": "TestBasic", "Type": "HTTP", "URL": "http://sap.com", "Authentication": "BasicAuthentication", "ProxyType": "OnPremise", "User": "test", "Password": "pass12345" } Back to Response Structure [page 197] Authentication Tokens Note This property is only applicable to destinations that use the following authentication types: BasicAuthentication, OAuth2SAMLBearerAssertion, OAuth2ClientCredentials, OAuthUserTokenExchange, OAuth2JWTBearer, OAuth2Password, and SAPAssertionSSO. ● Key: authTokens The JSON array that represents the value of this property contains tokens that are required for authentication. These tokens are represented by JSON objects with these properties (expect more new properties to be added in the future): ○ type: the type of the token. ○ value: the actual token. ○ http_header: JSON object containing the prepared token in the correct format. The <key> field contains the key of the HTTP header. The <value> field contains the value of the header. ○ expires_in (only in OAuth2 destinations): The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. ○ error (optional): if the retrieval of the token fails, the value of both type and value is an empty string and this property shows an error message, explaining the problem. ○ scope (optional) (only in OAuth2 destinations): The scopes issued with the token. The value of the scope parameter is expressed as a list of space-delimited strings. For example, read write execute. ● Example: Sample Code "authTokens": [ { "type": "Basic", "value": "dGVzdDpwYXNzMTIzNDU=", "http_header": { "key":"Authorization", "value":"Basic dGVzdDpwYXNzMTIzNDU=" } } 198 PUBLIC SAP BTP Connectivity Connectivity
- 199. ] Back to Response Structure [page 197] Certificates Note This property is only applicable to destinations that use the following authentication types: ClientCertificateAuthentication, OAuth2SAMLBearerAssertion (when default JDK trust store is not used). ● Key: certificates The JSON array that represents the value of this property contains the certificates, specified in the destination configuration. These certificates are represented by JSON objects with these properties (expect more new properties to be added in the future): ○ type ○ content: the encoded content of the certificate. ○ name: the name of the certificate, as specified in the destination configuration. ● Example: Sample Code "certificates": [ { "Name": "keystore.jks", "Content": "<value>" "Type": "CERTIFICATE" }, { "Name": "truststore.jks", "Content": "<value>" "Type": "CERTIFICATE" } ] Back to Response Structure [page 197] Example Example of a full response for a destination using basic authentication: Sample Code { SAP BTP Connectivity Connectivity PUBLIC 199
- 200. "owner": { "SubaccountId": "9acf4877-5a3d-43d2-b67d-7516efe15b11", "InstanceId": null }, "destinationConfiguration": { "Name": "TestBasic", "Type": "HTTP", "URL": "http://sap.com", "Authentication": "BasicAuthentication", "ProxyType": "OnPremise", "User": "test", "Password": "pass12345" }, "authTokens": [ { "type": "Basic", "value": "dGVzdDpwYXNzMTIzNDU=" "http_header": { "key":"Authorization", "value":"Basic dGVzdDpwYXNzMTIzNDU=" } } ] } Back to Response Structure [page 197] 1.1.4.2.2 User Propagation via SAML 2.0 Bearer Assertion Flow Learn about the process for automatic token retrieval, using the OAuth2SAMLBearerAssertion authentication type for HTTP destinations. Tasks Task Type Task Operator and/or Developer Prerequisites [page 201] Developer Automated Access Token Retrieval [page 201] ● Determine the Propagated User ID [page 201] ● Propagate User Attributes [page 203] ● Scenarios [page 203] 200 PUBLIC SAP BTP Connectivity Connectivity
- 201. Prerequisites ● You have configured an OAuth2SAMLBearerAssertion destination. See OAuth SAML Bearer Assertion Authentication [page 70]. ● Unless using the destination property SystemUser, the user’s identity should be represented by a JSON Web token (JWT). Note Though actually not being a strict requirement, it is likely that you need a user JWT to get the relevant information. See SAP Authorization and Trust Management Service in the Cloud Foundry Environment. ● If you are using custom user attributes to determine the user, the JWT representing the user (that is passed to the Destination service) must have the user_attributes scope. Back to Tasks [page 200] Automated Access Token Retrieval For an OAuth2SAMLBearerAssertion destination, you can use the automated token retrieval functionality that is available via the "find destination" endpoint. See Destination Service REST API [page 59]. Determine the Propagated User ID There are currently three sources that can provide the propagated user ID. They are prioritized, meaning that the lookup always starts from the top-priority source and goes down the list. If the propagated user ID is not found at a given level, the next level is checked. If not found on any level, the operation would fail. Find the available sources in the table below, in order of their priority. Propagated User ID: Sources Source Procedure System User The system user is a special user ID that is hardcoded in your destination as value of the SystemUser property. If you set this property, its value is used as the propagated user ID. SAP BTP Connectivity Connectivity PUBLIC 201
- 202. Source Procedure Field in the JWT In this case, the Destination service looks for the user ID as a field in the provided JWT. When you make the HTTP call to the Destination service, you must provide the Authorization header. The value must be a JWT in its encoded form (see RFC 7519 ). The procedure is as fol lows: ● If the userIdSource property is configured in the destination, its value is the key of the JWT field that will be the user ID (if there is no such key in the JWT, the flow proceeds to the next level). There are 2 options: ○ plain string: the exact match is searched on the root-level element keys of the JWT. ○ JsonPath expression: lets you use non-root- level elements of the JWT. ● If the userIdSource property is missing, the flow falls back to the destination property nameIdFormat. It must have one of the following two values (or not be set at all), otherwise an exception is thrown: ○ urn:oasis:names:tc:SAML:1.1:nameid-for mat:emailAddress: the email element of the JWT is the user ID. If there is no such element in the JWT, an exception is thrown. ○ urn:oasis:names:tc:SAML:1.1:nameid-format:un specified (or not set): the user_name element of the JWT is the user ID. If there is no such element in the JWT, an exception is thrown. Custom User Attribute Like Field in the JWT, this source must use the Authorization header. In this case, its value is used to retrieve the custom user attributes from the Identity Pro vider (XSUAA). One of those attributes can be used as the propagated user ID. The access token from the header must be a user JWT with the user_attributes scope. Other wise the custom attributes cannot be retrieved, and the op eration results in an error. ● If the userIdSource property is configured in the destination, the same logic applies as for Field in the JWT, but this time on the JSON containing the custom user attributes. ● If userIdSource is missing or the desired key is not found in the custom attributes, the operation fails (user ID could not be determined). Back to Tasks [page 200] 202 PUBLIC SAP BTP Connectivity Connectivity
- 203. Propagate User Attributes You can read additional user attributes from the identity provider (XSUAA), and propagate them as SAML attributes in the generated SAML bearer assertion. These attributes are similar to the ones returned by the Cloud Foundry UAA user info endpoint. However, they may differ depending on the XSUAA behavior, and are specific to the identity provider you use. For more details about these attributes and possible values, see https:/ /docs.cloudfoundry.org/api/uaa/ version/74.15.0/index.html#user-info . Note When adding the attributes, the following rules apply: ● All root elements, except for user_attributes, are added "as is", that is, the attribute name and value are displayed as seen in the source (user info response structure). ● Elements under the user_attribute key are parsed and added as attributes prefixed with 'user_attributes.'. For example, having {"user_attributes": { "my_param": "my_value" }} will result in an attribute called 'user_attributes.my_param' with value 'my_value' in the SAML assertion. In addition to identity provider (XSUAA) user info attributes, there are some more attributes which are read from the passed JWT. They are located via predefined JsonPath expressions and cannot be controlled by the end user: ● $.['xs.system.attributes']['xs.saml.groups'] ● $.['user_attributes']['xs.saml.groups'] Note The 'xs.saml.groups' attribute, read from the passed JWT, is renamed to 'Groups' in the resulting SAML assertion. See also Federation Attribute Settings of Any Identity Provider. Back to Tasks [page 200] Scenarios Refer to the table below to find the JWT requirements for a specific scenario: Scenario Authorization Header Propagate a technical user principal, using the SystemUser property of an OAuth2SAMLBearerAssertion destination main tained in the subscriber subaccount, and used by the pro vider application. Access token, retrieved ● via the client credentials of the Destination service in stance (bound to the application). ● using the subscriber's tenant-specific Token Service URL. SAP BTP Connectivity Connectivity PUBLIC 203
- 204. Scenario Authorization Header Propagate a technical user principal, using the SystemUser property of an OAuth2SAMLBearerAssertion destination main tained in the same subaccount where the application is de ployed. Access token, retrieved ● via the client credentials of the Destination service in stance (bound to the application). ● using the provider's tenant-specific Token Service URL. Propagate a business user principal, using an OAuth2SAMLBearerAssertion destination main tained in the subscriber subaccount where the application is deployed. The business user is represented by a JWT that was issued by the subscriber. The JWT, previously retrieved from the application ● by exchanging the JWT (that represents the user) to an other user access token via the client credentials of the Destination service instance (bound to the application). ● using the subscriber's tenant-specific Token Service URL. Propagate a business user principal, using an OAuth2SAMLBearerAssertion destination main tained in the same subaccount where the application is de ployed. The business user is represented by a JWT that was issued by the provider. The JWT, previously retrieved by the application ● by exchanging the JWT (that represents the user) to an other user access token via the client credentials of the Destination service instance (bound to the application). ● using the provider's tenant-specific Token Service URL. Back to Tasks [page 200] 1.1.4.2.3 Destination Service REST API Destination service REST API specification for the SAP Cloud Foundry environment. The Destination service provides a REST API that you can use to read and manage destinations and certificates on all available levels. This API is documented in the SAP API Business Hub . It shows all available endpoints, the supported operations, parameters, possible error cases and related status codes, etc. You can also execute requests using the credentials (for example, the service key) of your Destination service instance, see Create and Bind a Destination Service Instance [page 161]. 1.1.4.2.4 Exchanging User JWTs via OAuth2UserTokenExchange Destinations Automatic token retrieval using the OAuth2UserTokenExchange authentication type for HTTP destinations. 204 PUBLIC SAP BTP Connectivity Connectivity
- 205. Content Prerequisites [page 205] Automated Access Token Retrieval [page 205] Scenarios [page 205] Prerequisites You have configured an OAuth2UserTokenExchange destination. See OAuth User Token Exchange Authentication [page 86]. The token to be exchanged must have the uaa.user scope to enable the token exchange. See SAP Authorization and Trust Management Service in the Cloud Foundry Environment for more details. Back to Content [page 205] Automated Access Token Retrieval For destinations of authentication type OAuth2UserTokenExchange, you can use the automated token retrieval functionality via the "find destination" endpoint, see Call the Destination Service [page 193]. If you provide the user token exchange header with the request to the Destination service and its value is not empty, it is used instead of the Authorization header to specify the user and the tenant subdomain. It will be the token for which token exchange is performed. ● The header value must be a user JWT (JSON Web token) in encoded form, see RFC 7519 . ● If the user token exchange header is not provided with the request to the Destination Service or it is provided, but its value is empty, the token from the Authorization header is used instead. In this case, the JWT in the Authorization header must be a user JWT in encoded form, otherwise the token exchange does not work. For information about the response structure of this request, see "Find Destination" Response Structure [page 196]. Back to Content [page 205] Scenarios SAP BTP Connectivity Connectivity PUBLIC 205
- 206. To achieve specific token exchange goals, you can use the following headers and values when calling the Destination service: Goal User Token Exchange Header Authorization Header Exchange a user token: ● Issued on behalf of the application provider tenant ● Using a destination in the applica tion provider tenant Not used The user token to be exchanged Previously retrieved by the application via exchanging the initial user token, passed to the application (to another user access token) via the client cre dentials of the Destination service in stance (bound to the application), using the provider tenant-specific token serv ice URL. Exchange a user token: ● Issued on behalf of a tenant, sub scribed to your application ● Using a destination in the applica tion provider tenant <User token to be exchanged> Access token Retrieved via the client credentials of the Destination service instance (bound to the application), using the provider tenant-specific token service URL. Exchange a user token: ● Issued on behalf of a tenant, sub scribed to your application ● Using a destination in the sub scriber tenant <User token to be exchanged> Access token Retrieved via the client credentials of the Destination service instance (bound to the application), using the subscriber tenant-specific token service URL. Back to Content [page 205] 1.1.4.2.5 Multitenancy in the Destination Service Establilsh multitenancy in the Destination service using subscription-level destinations. Concept When developing a provider application (SaaS application) that consumes the Destination service, you can choose between the following destination levels: 206 PUBLIC SAP BTP Connectivity Connectivity
- 207. Level Who has Access and How? Subaccount Any application using any destination service instance in the subaccount context. This is the common level for all applica tions and service instances in the subaccount. Service Instance Any application using the concrete destination service in stance in the context of the provider subaccount (the subac count in which the instance is provisioned). Each service in stance has its own level. Subscription Any application using the concrete destination service in stance in the context of the subscribed subaccount. Each combination of service instance and subscriber subaccount is a unique level. Note The term level is used here to represent an area or visibility scope. The higher the level, the broader is the visibility scope. If you, as an application provider, want to create a destination that is used at runtime only by the subscriber and that should be visible and accessible only to the subscriber, you can create a subscription-level destination for each subscriber subaccount (tenant): Create a Subscription-Level Destination [page 207] Consume a Subscription-Level Destination [page 208] Create a Subscription-Level Destination SAP BTP Connectivity Connectivity PUBLIC 207
- 208. 1. Retrieve an OAuth token from the subscriber token service URL using the OAuth client credentials from the destination service instance, for example: POST https://{subscriber subdomain}.authentication.{region host}/oauth/token 2. Use the retrieved token from step 1 to create (POST) a subscription-level destination in the Destination service, see Destinations on service instance (subscription) level in the REST API specification . Back to Concept [page 206] Consume a Subscription-Level Destination 1. Retrieve an OAuth token from the subscriber token service URL using the OAuth client credentials from the destination service instance, for example: POST https://{subscriber subdomain}.authentication.{region host}/oauth/token 2. Use the token from step 1 to retrieve (GET) the destination stored on subscription level from the Destination service via: ○ Find a destination in the REST API specification ○ Destinations on service instance (subscription) level in the REST API specification Back to Concept [page 206] Related Information Multitenancy in the Connectivity Service [page 156] 1.1.4.3 Invoking ABAP Function Modules via RFC Call a remote-enabled function module in an on-premise or cloud ABAP server from your Cloud Foundry application, using the RFC protocol. Find the tasks and prerequisites that are required to consume an ABAP function module via RFC, using the Java Connector (JCo) API as a built-in feature of SAP BTP. Tasks 208 PUBLIC SAP BTP Connectivity Connectivity
- 209. Task Type Task Operator Prerequisites [page 209] Operator and/or Developer About JCo [page 209] Installation Prerequisites for JCo Applications [page 210] Consume Connectivity via RFC [page 210] Restrictions [page 211] Prerequisites Before you can use RFC communication for an SAP BTP application, you must configure: ● A destination on SAP BTP to use RFC. For more information, see RFC Destinations [page 110]. ● (Only for on-premise backend systems) RFC connectivity between a backend system and the application. To do this, you must install the Cloud Connector [page 267] in your internal network and configure it to expose a remote-enabled function module in an ABAP system. For more information, see Initial Configuration (RFC) [page 321] and Configure Access Control (RFC) [page 377]. Back to Tasks [page 208] About JCo To learn in detail about the SAP JCo API, see the JCo 3.0 documentation on SAP Support Portal . Note Some sections of this documentation are not applicable to SAP BTP: ● Architecture: CPIC is only used in the last mile from your Cloud Connector to an on-premise ABAP backend. From SAP BTP to the Cloud Connector, TLS-protected communication is used. SAP BTP Connectivity Connectivity PUBLIC 209
- 210. ● Installation: SAP BTP runtimes already include all required artifacts. ● Customizing and Integration: On SAP BTP, the integration is already done by the runtime. You can concentrate on your business application logic. ● Server Programming: The programming model of JCo on SAP BTP does not include server-side RFC communication. ● IDoc Support for External Java Applications: Currently, there is no IDocLibrary for JCo available on SAP BTP Back to Tasks [page 208] Installation Prerequisites for JCo Applications ● For connections to an on-premise ABAP backend, you have downloaded the Cloud Connector installation archive from SAP Development Tools for Eclipse and connected the Cloud Connector to your subaccount. ● You have downloaded and set up your Eclipse IDE and the Eclipse Tools for Cloud Foundry . ● You have downloaded the Cloud Foundry CLI, see Tools. Back to Tasks [page 208] Consuming Connectivity via RFC You can call a service from a fenced customer network using an application that consumes a remote-enabled function module. Invoking function modules via RFC is enabled by a JCo API that is comparable to the one available in SAP NetWeaver Application Server Java (version 7.10+), and in JCo standalone 3.0. If you are an experienced JCo developer, you can easily develop a Web application using JCo: you simply consume the APIs like you do in other Java environments. Restrictions that apply in the cloud environment are mentioned in the Restrictions section below. Find a sample Web application in Scenario: Invoke ABAP Function Modules in On-Premise ABAP Systems [page 212]. Back to Tasks [page 208] 210 PUBLIC SAP BTP Connectivity Connectivity
- 211. Restrictions ● The supported runtime environment is SAP Java Buildpack as of version 1.8.0. Note You must use the Tomcat or TomEE runtime offered by the build pack to make JCo work correctly. You cannot bring a container of your own. ● JCoServer functionality cannot be used within SAP BTP. ● Environment embedding, such as offered by JCo standalone 3.0, is not possible. This is, however, similar to SAP NetWeaver AS Java. ● Logon authentication only supports user/password credentials (basic authentication) and principal propagation. See Authentication to the On-Premise System [page 173]. ● The supported set of configuration properties is restricted. For details, see RFC Destinations [page 110]. Back to Tasks [page 208] Related Information Use Cases [page 211] 1.1.4.3.1 Use Cases Find instructions for typical RFC end-to-end scenarios that use the Connectivity service and/or the Destination service (Cloud Foundry environment). Scenario: Invoke ABAP Function Modules in On-Premise ABAP Systems [page 212] Call a function module in an on-premise ABAP system via RFC, using a sample Web application (Cloud Foundry envi ronment). Scenario: Invoke ABAP Function Modules in Cloud ABAP Systems [page 236] Call a function module in a cloud ABAP system via RFC, us ing a sample Web application (Cloud Foundry environment). Scenario: Multitenancy for JCo Applications (Advanced) [page 254] Learn about the required steps to make your Cloud Foundry JCo application tenant-aware. SAP BTP Connectivity Connectivity PUBLIC 211
- 212. 1.1.4.3.1.1 Scenario: Invoke ABAP Function Modules in On- Premise ABAP Systems Call a function module in an on-premise ABAP system via RFC, using a sample Web application (Cloud Foundry environment). This scenario performs a remote function call to invoke an ABAP function module, by using the Connectivity service and the Destination service in the Cloud Foundry environment, as well as a Cloud Foundry application router. Tasks Task Type Task Operator and/or Developer Scenario Overview [page 213] Connectivity User Roles [page 214] Installation Prerequisites [page 215] Used Values [page 214] Developer Develop a Sample Web Application [page 216] Operator and/or Developer Create and Bind Service Instances [page 220] Developer Deploy the Application [page 223] Operator Configure Roles and Trust [page 225] Operator and/or Developer Set Up an Application Router [page 226] 212 PUBLIC SAP BTP Connectivity Connectivity
- 213. Task Type Task Operator Configure the RFC Destination [page 230] Configure the Cloud Connector [page 231] Operator and/or Developer Monitoring Your Web Application [page 235] (Optional) Scenario Overview Control Flow for Using the Java Connector (JCo) with Basic Authentication Process Steps: 1. Call through AppRouter (entry point for business applications). Note AppRouter is only required you want to use multitenancy or perform user-specific service calls. In all other cases, JCo uses cloud-security-xsuaa-integration with ClientCredentialFlow. 2. Redirect to XSUAA for login. JSON Web Token (JWT1) is sent to AppRouter and cached there. SAP BTP Connectivity Connectivity PUBLIC 213
- 214. 3. AppRouter calls Web app and sends JWT1 with credentials. 4. Buildpack/XSUAA interaction: 1. Buildpack requests JWT2 to access the Destination service instance (JCo call). 2. Buildpack requests JWT3 to access the Connectivity service instance. 5. Buildpack requests destination configuration (JWT2). 6. Buildpack sends request to the Connectivity service instance (with JWT3 and Authorization Header). 7. Connectivity service forwards request to the Cloud Connector. 8. Cloud Connector sends request to on-premise system. Since token exchanges are handled by the buildpack, you must only create and bind the service instances, see Create and Bind Service Instances [page 220]. Back to Tasks [page 212] Used Values This scenario uses: ● A subaccount in region Europe (Frankfurt), for which the API endpoint is api.cf.eu10.hana.ondemand.com. ● The application name jco-demo-<subaccount name>, where <subaccount name> is the subdomain name of the subaccount. For this example, we use p1234. Back to Tasks [page 212] Connectivity User Roles Different user roles are involved in the cloud to on-premise connectivity end-to-end scenario. The particular steps for the relevant roles are described below: IT Administrator Sets up and configures the Cloud Connector. Scenario steps: 1. Downloads the Cloud Connector from https:/ /tools.hana.ondemand.com/#cloud 2. Installs the Cloud Connector. 3. Establishes an SSL tunnel from the connector to an SAP BTP subaccount. 4. Configures the exposed back-end systems and resources. Application Developer Develops Web applications using destinations. Scenario steps: 1. Installs Eclipse IDE, the Cloud Foundry Plugin for Eclipse and the Cloud Foundry CLI. 214 PUBLIC SAP BTP Connectivity Connectivity
- 215. 2. Develops a Java EE application using the JCo APIs. 3. Configures connectivity destinations via the SAP BTP cockpit. 4. Deploys and tests the Java EE application on SAP BTP. Account Operator Deploys Web applications, creates application routers, creates and binds service instances, conducts tests. Scenario steps: 1. Obtains a ready Java EE application WAR file. 2. Deploys an application router with respective routes to the application. 3. Creates an XSUAA service instance and binds it to the router. 4. Deploys the Java EE application to an SAP BTP subaccount. 5. Creates a Connectivity service and Destination service instance, and binds them to the application. 6. Creates and manages roles and role collections. Back to Tasks [page 212] Installation Prerequisites ● You have downloaded the Cloud Connector installation archive from SAP Development Tools for Eclipse and connected the Cloud Connector to your subaccount. ● You have downloaded and set up your Eclipse IDE and the Eclipse Tools for Cloud Foundry . ● You have downloaded the Cloud Foundry CLI, see Tools. Back to Tasks [page 212] Next Steps ● Develop a Sample Web Application [page 216] ● Create and Bind Service Instances [page 220] ● Deploy the Application [page 223] ● Configure Roles and Trust [page 225] ● Set Up an Application Router [page 226] ● Configure the RFC Destination [page 230] ● Configure the Cloud Connector [page 231] ● Monitoring Your Web Application [page 235] (Optional) Related Information Scenario: Multitenancy for JCo Applications (Advanced) [page 254] SAP BTP Connectivity Connectivity PUBLIC 215
- 216. 1.1.4.3.1.1.1 Develop a Sample Web Application Create a Web application to call an ABAP function module via RFC. Steps 1. Create a Dynamic Web Project [page 216] 2. Include JCo Dependencies [page 217] 3. Create a Sample Servlet [page 218] Create a Dynamic Web Project 1. Open the Java EE perspective of the Eclipse IDE. 2. On the Project Explorer view, choose New Dynamic Web Project in the context menu. 3. Enter jco_demo as the project name. 4. In the Target Runtime pane, select Cloud Foundry . If it is not yet in the list of available runtimes, choose New Runtime and select it from there. 5. In the Configuration pane, leave the default configuration. 6. Choose Finish. 216 PUBLIC SAP BTP Connectivity Connectivity
- 217. Back to Steps [page 216] Include JCo Dependencies SAP BTP Connectivity Connectivity PUBLIC 217
- 218. To use JCo functionality seamlessly at compile time in Eclipse, you must include the JCo dependencies into your web project. Therefore, you must convert it into a maven project. 1. In the Project Explorer view, right-click on the project jco-demo and choose Configure Convert to Maven Project . 2. In the dialog window, leave the default settings unchanged and choose Finish. 3. Open the pom.xml file and include the following dependency: <dependencies> <dependency> <groupId>com.sap.cloud</groupId> <artifactId>neo-java-web-api</artifactId> <version>[3.71.8,4.0.0)</version> <scope>provided</scope> </dependency> </dependencies> Back to Steps [page 216] Create a Sample Servlet 1. From the jco_demo project node, choose New Servlet in the context menu. 2. Enter com.sap.demo.jco as the <> and ConnectivityRFCExampleJava as the <Class name>. Choose Next. 3. Choose Finish to create the servlet and open it in the Java editor. 4. Replace the entire servlet class to make use of the JCo API. The JCo API is visible by default for cloud applications. You do not need to add it explicitly to the application class path. Sample Code package com.sap.demo.jco; import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import com.sap.conn.jco.AbapException; import com.sap.conn.jco.JCoDestination; import com.sap.conn.jco.JCoDestinationManager; import com.sap.conn.jco.JCoException; import com.sap.conn.jco.JCoFunction; import com.sap.conn.jco.JCoParameterList; import com.sap.conn.jco.JCoRepository; /** * Sample application that uses the Connectivity service. In particular, it is * making use of the capability to invoke a function module in an ABAP system 218 PUBLIC SAP BTP Connectivity Connectivity
- 219. * via RFC * * Note: The JCo APIs are available under <code>com.sap.conn.jco</code>. */ @WebServlet("/ConnectivityRFCExample/*") public class ConnectivityRFCExample extends HttpServlet { private static final long serialVersionUID = 1L; protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { PrintWriter responseWriter = response.getWriter(); try { // access the RFC Destination "JCoDemoSystem" JCoDestination destination = JCoDestinationManager.getDestination("JCoDemoSystem"); // make an invocation of STFC_CONNECTION in the backend; JCoRepository repo = destination.getRepository(); JCoFunction stfcConnection = repo.getFunction("STFC_CONNECTION"); JCoParameterList imports = stfcConnection.getImportParameterList(); imports.setValue("REQUTEXT", "SAP BTP Connectivity runs with JCo"); stfcConnection.execute(destination); JCoParameterList exports = stfcConnection.getExportParameterList(); String echotext = exports.getString("ECHOTEXT"); String resptext = exports.getString("RESPTEXT"); response.addHeader("Content-type", "text/html"); responseWriter.println("<html><body>"); responseWriter.println("<h1>Executed STFC_CONNECTION in system JCoDemoSystem</h1>"); responseWriter.println("<p>Export parameter ECHOTEXT of STFC_CONNECTION:<br>"); responseWriter.println(echotext); responseWriter.println("<p>Export parameter RESPTEXT of STFC_CONNECTION:<br>"); responseWriter.println(resptext); responseWriter.println("</body></html>"); } catch (AbapException ae) { // just for completeness: As this function module does not have an exception // in its signature, this exception cannot occur. But you should always // take care of AbapExceptions } catch (JCoException e) { response.addHeader("Content-type", "text/html"); responseWriter.println("<html><body>"); responseWriter .println("<h1>Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem</h1>"); responseWriter.println("<pre>"); e.printStackTrace(responseWriter); responseWriter.println("</pre>"); responseWriter.println("</body></html>"); } } } 5. Save the Java editor and make sure that the project compiles without errors. Back to Steps [page 216] SAP BTP Connectivity Connectivity PUBLIC 219
- 220. Next Steps ● Create and Bind Service Instances [page 220] ● Deploy the Application [page 223] ● Configure Roles and Trust [page 225] ● Set Up an Application Router [page 226] ● Configure the RFC Destination [page 230] ● Configure the Cloud Connector [page 231] ● Monitoring Your Web Application [page 235] (Optional) 1.1.4.3.1.1.2 Create and Bind Service Instances You must create and bind several service instances, before you can use your application. Procedure 1. Logon to the cloud cockpit and choose your subaccount. 2. Choose the space where you want to deploy your demo application. 3. Choose Service Marketplace and find these 3 services: ○ Connectivity ○ Destination ○ Authorization & Trust Management (XSUAA) 4. Create and bind a service instance for each of these services. ○ Connectivity service [page 221] ○ Destination service [page 221] ○ Authorization & Trust Management (XSUAA service) [page 222] 220 PUBLIC SAP BTP Connectivity Connectivity
- 221. Connectivity Service 1. Choose Connectivity Create Instance . 2. Insert an instance name (for example, connectivity_jco) and choose Create Instance . Back to Procedure [page 220] Destination Service 1. Choose Destination Create Instance . SAP BTP Connectivity Connectivity PUBLIC 221
- 222. 2. Insert an instance name (for example, destination_jco) and choose Create Instance . Back to Procedure [page 220] Authorization & Trust Management (XSUAA Service) 1. Choose Authorization & Trust Management Create Instance 2. Select <Service Plan> application. 3. Enter an <Instance Name> and choose Next. Note The instance name must match the one defined in the manifest file. 4. In the next tab Parameters, insert the following as a JSON file: Sample Code { "xsappname" : "jco-demo-p1234", "tenant-mode": "dedicated", "scopes": [ { "name": "$XSAPPNAME.all", "description": "all" } ], "role-templates": [ { "name": "all", "description": "all", "scope-references": [ "$XSAPPNAME.all" ] } ] } 5. Go to tab Review and choose Create Instance. Back to Procedure [page 220] Next Steps ● Deploy the Application [page 223] ● Configure Roles and Trust [page 225] ● Set Up an Application Router [page 226] ● Configure the RFC Destination [page 230] 222 PUBLIC SAP BTP Connectivity Connectivity
- 223. ● Configure the Cloud Connector [page 231] ● Monitoring Your Web Application [page 235] (Optional) 1.1.4.3.1.1.3 Deploy the Application Deploy your Cloud Foundry application to call an ABAP function module via RFC. Prerequisites You have created and bound the required service instances, see Create and Bind Service Instances [page 220]. Procedure 1. To deploy your Web application, you can use the following two alternative procedures: ○ Deploying from the Eclipse IDE ○ Deploying from the CLI, see Developing Java in the Cloud Foundry Environment 2. In the following, we publish it with the CLI. 3. To do this, create a manifest.yml file. The key parameter is USE_JCO: true, which must be set to include JCo into the buildpack during deployment. manifest.yml Sample Code --- applications: - name: jco-demo-p1234 buildpacks: - sap_java_buildpack env: USE_JCO: true # This is necessary only if more than one instance is bound xsuaa_connectivity_instance_name: "xsuaa_jco" connectivity_instance_name: "connectivity_jco" destination_instance_name: "destination_jco" services: - xsuaa_jco - connectivity_jco - destination_jco SAP BTP Connectivity Connectivity PUBLIC 223
- 224. Caution The client libraries (java-security, spring-xsuaa, and container security api for node.js as of version 3.0.6) have been updated. When using these libraries, setting the parameter SAP_JWT_TRUST_ACL has become obsolete. This update comes with a change regarding scopes: ○ For a business application A calling an application B, it is now mandatory that application B grants at least one scope to the calling business application A. ○ Business application A must accept these granted scopes or authorities as part of the application security descriptor. You can grant scopes using the xs-security.json file. For more information, see Application Security Descriptor Configuration Syntax, specifically the sections Referencing the Application and Authorities. Note If you have more than one instance of those three services bound to your application, you must specify which one JCo should use with the respective env parameters: ○ xsuaa_connectivity_instance_name ○ connectivity_instance_name ○ destination_instance_name. 4. In Eclipse, right-click on the project and navigate to Export WAR file . 5. Choose a destination by pressing the Browse... button next to the manifest.yml you created before, for example as jcodemo.war. 6. Leave the other default settings unchanged and choose Finish to export the WAR file. 7. Perform a CLI login via cf login -a api.cf.eu10.hana.ondemand.com -u <your_email_address> (password, org and space are prompted after a successful login). 8. Push the application with cf push -f manifest.yml -p jcodemo.war. 9. Now, the application should be deployed successfully. Next Steps ● Configure Roles and Trust [page 225] ● Set Up an Application Router [page 226] ● Configure the RFC Destination [page 230] ● Configure the Cloud Connector [page 231] ● Monitoring Your Web Application [page 235] (Optional) 224 PUBLIC SAP BTP Connectivity Connectivity
- 225. 1.1.4.3.1.1.4 Configure Roles and Trust Configure a role that enables your user to access your Web application. To add and assign roles, navigate to the subaccount view of the cloud cockpit and choose Security Role Collections . 1. Create a new role collection with the name all. 2. From the subaccount menu, choose Trust Configuration. 3. If you don't have a trust configuration, follow the steps in Manually Establish Trust and Federation Between UAA and Identity Authentication. 4. Click on the IdP name of your choice. 5. Type in your e-mail address and choose Show Assignments. 6. If your user has not yet been added to the SAP ID service, you see following popup. In this case, add your user now. 7. You should now be able to click Assign Role Collection. Choose role collection all and assign it. Next Steps ● Set Up an Application Router [page 226] ● Configure the RFC Destination [page 230] ● Configure the Cloud Connector [page 231] ● Monitoring Your Web Application [page 235] (Optional) SAP BTP Connectivity Connectivity PUBLIC 225
- 226. Related Information Working with Role Collections 1.1.4.3.1.1.5 Set Up an Application Router For authentication purposes, configure and deploy an application router for your test application. Note AppRouter is only required if you want to use multitenancy or perform user-specific service calls. In all other cases, JCo uses cloud-security-xsuaa-integration with ClientCredentialFlow. 1. To set up an application router, follow the steps in Application Router or use the demo file approuter.zip (download). 2. For deployment, you need a manifest file, similar to this one: Sample Code --- applications: - name: approuter-jco-demo-p1234 path: ./ buildpacks: - nodejs_buildpack memory: 120M routes: - route: approuter-jco-demo-p1234.cfapps.eu10.hana.ondemand.com env: NODE_TLS_REJECT_UNAUTHORIZED: 0 destinations: > [ {"name":"dest-to-example", "url" :"https://jco-demo- p1234.cfapps.eu10.hana.ondemand.com/ConnectivityRFCExample", "forwardAuthToken": true } ] services: - xsuaa_jco Note ○ The routes and destination URLs need to fit your test application. ○ In this example, we already bound our XSUAA instance to the application router. Alternatively, you could also do this via the cloud cockpit. 3. Push the approuter with cf push -f manifest.yml -p approuter.zip. 4. To navigate to the approuter application in the cloud cockpit, choose <your_space> Applications <your application> Overview . 226 PUBLIC SAP BTP Connectivity Connectivity
- 227. 5. When choosing the application route, you are requested to login. Provide the credentials known by the IdP you configured in Roles & Trust. 6. After successful login, you are routed to the test application which is then executed. 7. If the application issues an exception, saying that the JCoDemoSystem destination has not yet been specified, you must configure the JCoDemoSystem destination first. Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem com.sap.conn.jco.JCoException: (106) JCO_ERROR_RESOURCE: Destination JCoDemoSystem does not exist at com.sap.conn.jco.rt.DefaultDestinationManager.update(DefaultDestinationManager .java:223) at com.sap.conn.jco.rt.DefaultDestinationManager.searchDestination(DefaultDestina tionManager.java:377) at com.sap.conn.jco.rt.DefaultDestinationManager.getDestinationInstance(DefaultDe stinationManager.java:96) at com.sap.conn.jco.JCoDestinationManager.getDestination(JCoDestinationManager.ja va:52) at com.sap.demo.jco.ConnectivityRFCExample.doGet(ConnectivityRFCExample.java:47) ..... (cut rest of the call stack) Calling JCo APIs from Newly Created Threads If you are using an Application Router and it is mandatory for you to call JCo APIs from a different thread than the one which is executing your servlet function, make sure the thread local information of the cloud-security- xsuaa-integration API , used by JCo internally, is set again within your newly created thread. To do this, add the following dependency to your project: <dependency> <groupId>com.sap.cloud.security</groupId> <artifactId>java-api</artifactId> <version>2.7.7</version> <scope>provided</scope> SAP BTP Connectivity Connectivity PUBLIC 227
- 228. </dependency> Note Make sure you don't include this dependency with scope compile transitively with any other jar, for example, with <dependency> <groupId>com.sap.cloud.security</groupId> <artifactId>java-security</artifactId> </dependency> In this case, you must exclude java-api from this dependency and add it again as described above, with scope provided. Adjust your code from the step Develop a Sample Web Application [page 216] in the following way: Sample Code package com.sap.demo.jco; import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import com.sap.cloud.security.token.SecurityContext; import com.sap.cloud.security.token.Token; import com.sap.conn.jco.AbapException; import com.sap.conn.jco.JCoDestination; import com.sap.conn.jco.JCoDestinationManager; import com.sap.conn.jco.JCoException; import com.sap.conn.jco.JCoFunction; import com.sap.conn.jco.JCoParameterList; import com.sap.conn.jco.JCoRepository; /** * * Sample application that uses the connectivity service. In particular, it is * making use of the capability to invoke a function module in an ABAP system * via RFC * * Note: The JCo APIs are available under <code>com.sap.conn.jco</code>. */ @WebServlet("/ConnectivityRFCExample/*") public class ConnectivityRFCExample extends HttpServlet { private static final long serialVersionUID = 1L; protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { PrintWriter responseWriter = response.getWriter(); // access the token from the thread which is executing the servlet Token token = SecurityContext.getToken(); Thread runThread = new Thread(() -> { // set the information in the newly created thread SecurityContext.setToken(token); try { // access the RFC Destination "JCoDemoSystem" JCoDestination destination = JCoDestinationManager.getDestination("JCoDemoSystem_Normal"); // make an invocation of STFC_CONNECTION in the backend 228 PUBLIC SAP BTP Connectivity Connectivity
- 229. JCoRepository repo = destination.getRepository(); JCoFunction stfcConnection = repo.getFunction("STFC_CONNECTION"); JCoParameterList imports = stfcConnection.getImportParameterList(); imports.setValue("REQUTEXT", "SAP BTP Connectivity runs with JCo"); stfcConnection.execute(destination); JCoParameterList exports = stfcConnection.getExportParameterList(); String echotext = exports.getString("ECHOTEXT"); String resptext = exports.getString("RESPTEXT"); response.addHeader("Content-type", "text/html"); responseWriter.println("<html><body>"); responseWriter.println("<h1>Executed STFC_CONNECTION in system JCoDemoSystem</h1>"); responseWriter.println("<p>Export parameter ECHOTEXT of STFC_CONNECTION:<br>"); responseWriter.println(echotext); responseWriter.println("<p>Export parameter RESPTEXT of STFC_CONNECTION:<br>"); responseWriter.println(resptext); responseWriter.println("</body></html>"); } catch (AbapException ae) { // just for completeness: As this function module does not have an exception // in its signature, this exception cannot occur. But you should always // take care of AbapExceptions } catch (JCoException e) { response.addHeader("Content-type", "text/html"); responseWriter.println("<html><body>"); responseWriter .println("<h1>Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem</h1>"); responseWriter.println("<pre>"); e.printStackTrace(responseWriter); responseWriter.println("</pre>"); responseWriter.println("</body></html>"); } finally { // after execution clear the token again SecurityContext.clearToken(); } }); runThread.start(); // wait to be finished try { runThread.join(); } catch (InterruptedException e) { e.printStackTrace(responseWriter); } } } Note If you want to use thread pools , make sure that in your thread pool implementation this information is set correctly in the thread which is about to be (re)used, and removed as soon as the thread is put back into the pool. SAP BTP Connectivity Connectivity PUBLIC 229
- 230. Next Steps ● Configure the RFC Destination [page 230] ● Configure the Cloud Connector [page 231] ● Monitoring Your Web Application [page 235] (Optional) 1.1.4.3.1.1.6 Configure the RFC Destination Configure an RFC destination on SAP BTP that you can use in your Web application to call the on-premise ABAP system. To configure the destination, you must use a virtual application server host name (abapserver.hana.cloud) and a virtual system number (42) that you will expose later in the Cloud Connector. Alternatively, you could use a load balancing configuration with a message server host and a system ID. 1. Create a .properties file with the following settings: Name=JCoDemoSystem Type=RFC jco.client.ashost=abapserver.hana.cloud jco.client.sysnr=42 jco.destination.proxy_type=OnPremise jco.client.user=<DEMOUSER> jco.client.passwd=<Password> jco.client.client=000 jco.client.lang=EN jco.destination.pool_capacity=5 2. Go to your subaccount in the cloud cockpit. 1. From the subaccount menu, choose Connectivity Destinations Import Destination and upload this file. 2. Alternatively, you can create a destination for the service instance destination_jco to make it visible only for this instance. To do this, go to <your space> Services Service Instances <your destination_instance> and choose Destinations. 3. Call again the URL that references the cloud application in the Web browser. The Web application should now return a different exception: Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem com.sap.conn.jco.JCoException: (102) JCO_ERROR_COMMUNICATION: Opening connection to backend failed: Opening connection to abapserver.hana.cloud:sapgw42 denied. Expose the system in your Cloud Connector in case it was a valid request. at com.sap.conn.jco.rt.MiddlewareJavaRfc.generateJCoException(MiddlewareJavaRfc.j ava:487) at com.sap.conn.jco.rt.MiddlewareJavaRfc $JavaRfcClient.connect(MiddlewareJavaRfc.java:1216) at com.sap.conn.jco.rt.ClientConnection.connect(ClientConnection.java:700) at com.sap.conn.jco.rt.RepositoryConnection.connect(RepositoryConnection.java:72) at com.sap.conn.jco.rt.PoolingFactory.init(PoolingFactory.java:113) at com.sap.conn.jco.rt.ConnectionManager.createFactory(ConnectionManager.java: 426) 230 PUBLIC SAP BTP Connectivity Connectivity
- 231. at com.sap.conn.jco.rt.DefaultConnectionManager.createFactory(DefaultConnectionMa nager.java:46) at com.sap.conn.jco.rt.ConnectionManager.getFactory(ConnectionManager.java:376) at com.sap.conn.jco.rt.RfcDestination.getSystemID(RfcDestination.java: 1101) ..... (cut rest of the call stack) 4. This means that the Cloud Connector denied opening a connection to this system. As a next step, you must configure the system in your installed Cloud Connector. Next Steps ● Configure the Cloud Connector [page 231] ● Monitoring Your Web Application [page 235] (Optional) Related Information Target System Configuration [page 115] 1.1.4.3.1.1.7 Configure the Cloud Connector Configure the system mapping and the function module in the Cloud Connector. Steps 1. Configure Host Mapping [page 231] 2. Configure the Function Module [page 234] Configure Host Mapping The Cloud Connector only allows access to trusted backend systems. To configure this, follow the steps below: 1. Optional: In the Cloud Connector administration UI, you can check under Audits whether access has been denied: SAP BTP Connectivity Connectivity PUBLIC 231
- 232. Denying access for user DEMOUSER to system abapserver.hana.cloud:sapgw42 [connectionId=-1547299395] 2. In the Cloud Connector administration UI, choose Cloud To On-Premise from your Subaccount menu, tab Access Control. 3. In section Mapping Virtual To Internal System choose Add to define a new system. 1. For Backend Type, select ABAP System and choose Next. 2. For Protocol, select RFC and choose Next. 3. Choose option Without load balancing. 4. Enter application server and instance number. The Application Server entry must be the physical host name of the machine on which the ABAP application server is running. Choose Next. Example: 232 PUBLIC SAP BTP Connectivity Connectivity
- 233. 5. Enter server and instance number for virtual mapping. Note The values must match with the ones of the destination configuration in the cloud cockpit. Example: 6. Summary (example): 4. Call again the URL that references the cloud application in the Web browser. The application should now throw a different exception: om.sap.conn.jco.JCoException: (102) JCO_ERROR_COMMUNICATION: Partner signaled an error: Access denied for STFC_CONNECTION on abapserver.hana.cloud:sapgw42. Expose the function module in your Cloud Connector in case it was a valid request. SAP BTP Connectivity Connectivity PUBLIC 233
- 234. at com.sap.conn.jco.rt.MiddlewareJavaRfc.generateJCoException(MiddlewareJavaRfc.j ava:632) at com.sap.conn.jco.rt.MiddlewareJavaRfc $JavaRfcClient.execute(MiddlewareJavaRfc.java:1764) at com.sap.conn.jco.rt.ClientConnection.execute(ClientConnection.java: 1110) at com.sap.conn.jco.rt.ClientConnection.execute(ClientConnection.java:943) at com.sap.conn.jco.rt.RfcDestination.execute(RfcDestination.java:1307) at com.sap.conn.jco.rt.RfcDestination.execute(RfcDestination.java:1278) at com.sap.conn.jco.rt.AbapFunction.execute(AbapFunction.java:295) at com.sap.demo.jco.ConnectivityRFCExample.doGet(ConnectivityRFCExample.java:55) ..... (cut rest of the call stack) 5. This means that the Cloud Connector denied invoking STFC_CONNECTION in this system. As a final step, you must provide access to this function module. Back to Steps [page 231] Configure the Function Module The Cloud Connector only allows access to explicitly allowed resources (which, in an RFC scenario, are defined on the basis of function module names). To configure the function module, follow the steps below: 1. Optional: In the Cloud Connector administration UI, you can check under Monitor Audit whether access has been denied: Denying access for user DEMOUSER to resource STFC_CONNECTION on system abapserver.hana.cloud:sapgw42 [connectionId=609399452] 2. In the Cloud Connector administration UI, choose again Cloud To On-Premise from your Subaccount menu, and go to tab Access Control. 3. For the specified internal system referring to abapserver.hana.cloud, add a new resource. To do this, select the system in the table. 4. Add a new function name under the list of exposed resources. In section Resources Accessible On abapserver.hana.cloud:sapgw42, choose the Add button and specify STFC_CONNECTION as accessible resource, as shown in the screenshot below. Make sure that you have selected the Exact Name option to only expose this specific function module. 234 PUBLIC SAP BTP Connectivity Connectivity
- 235. 5. Call again the URL that references the cloud application in the Web browser. The application should now return a message showing the export parameters of the function module. See also Configure Access Control (RFC) [page 377]. Back to Steps [page 231] Next Step (Optional) ● Monitoring Your Web Application [page 235] 1.1.4.3.1.1.8 Monitoring Your Web Application Monitor the state and logs of your Web application deployed on SAP BTP, using the Application Logging service. For this purpose, create an instance of the Application Logging service (as you did for the Destination and Connectivity service) and bind it to your application, see Create and Bind Service Instances [page 220]. To activate JCo logging, set the following property in the env section of your manifest file: SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: INFO}' Now you can see and open the logs in the cloud cockpit or in the Kibana Dashboard in the tab Logs, if you are within your application. SAP BTP Connectivity Connectivity PUBLIC 235
- 236. For detailed information, you can activate the internal JCo logs: SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: DEBUG, com.sap.conn.jco: DEBUG}' Including other relevant components for logging: SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: DEBUG, com.sap.conn.jco: DEBUG, com.sap.xs.security: DEBUG, com.sap.cloud.security: DEBUG, com.sap.xs.env: DEBUG}' 1.1.4.3.1.2 Scenario: Invoke ABAP Function Modules in Cloud ABAP Systems Call a function module in a cloud ABAP system via RFC, using a sample Web application (Cloud Foundry environment). This scenario performs a remote function call to invoke an ABAP function module, by using the Destination service in the Cloud Foundry environment, as well as a Cloud Foundry application router. Tasks Task Type Task Operator and/or Developer Scenario Overview [page 237] Used Values [page 238] Connectivity User Roles [page 238] Installation Prerequisites [page 239] Developer Develop a Sample Web Application [page 239] Operator and/or Developer Create and Bind Service Instances [page 244] 236 PUBLIC SAP BTP Connectivity Connectivity
- 237. Task Type Task Developer Deploy the Application [page 246] Operator Configure Roles and Trust [page 248] Operator and/or Developer Set Up an Application Router [page 249] Operator Configure the RFC Destination [page 253] Operator and/or Developer Monitoring Your Web Application [page 254] (Optional) Scenario Overview Control Flow for Using the Java Connector (JCo) with Basic Authentication SAP BTP Connectivity Connectivity PUBLIC 237
- 238. Process Steps: 1. Call through AppRouter (entry point for business applications). Note AppRouter is only required you want to use multitenancy or perform user-specific service calls. In all other cases, JCo uses cloud-security-xsuaa-integration with ClientCredentialFlow. 2. Redirect to XSUAA for login. JSON Web Token (JWT1) is sent to AppRouter and cached there. 3. AppRouter calls Web app and sends JWT1 with credentials. 4. Buildpack/XSUAA interaction: Buildpack requests JWT2 to access the Destination service instance (JCo call). 5. Buildpack requests destination configuration (JWT2). 6. Buildpack sends request to the cloud ABAP system (with JWT2 and Authorization Header). Since token exchanges are handled by the buildpack, you must only create and bind the service instances, see Create and Bind Service Instances [page 220]. Back to Tasks [page 236] Used Values This scenario uses: ● A subaccount in region Europe (Frankfurt), for which the API endpoint is api.cf.eu10.hana.ondemand.com. ● The application name jco-demo-<subaccount name>, where <subaccount name> is the subdomain name of the subaccount. For this example, we use p1234. Back to Tasks [page 236] Connectivity User Roles Different user roles are involved in the cloud-to-cloud connectivity scenario. The particular steps for the relevant roles are described below: Application Developer Develops Web applications using destinations. Scenario steps: 1. Installs Eclipse IDE, the Cloud Foundry Plugin for Eclipse and the Cloud Foundry CLI. 2. Develops a Java EE application using the JCo APIs. 3. Configures connectivity destinations via the SAP BTP cockpit. 4. Deploys and tests the Java EE application on SAP BTP. 238 PUBLIC SAP BTP Connectivity Connectivity
- 239. Account Operator Deploys Web applications, creates application routers, creates and binds service instances, conducts tests. Scenario steps: 1. Obtains a ready Java EE application WAR file. 2. Deploys an application router with respective routes to the application. 3. Creates an XSUAA service instance and binds it to the router. 4. Deploys the Java EE application to an SAP BTP subaccount. 5. Creates a Destination service instance, and binds it to the application. 6. Creates and manages roles and role collections. Back to Tasks [page 236] Installation Prerequisites ● You have downloaded and set up your Eclipse IDE and the Eclipse Tools for Cloud Foundry . ● You have downloaded the Cloud Foundry CLI, see Tools. Back to Tasks [page 236] Next Steps ● Develop a Sample Web Application [page 239] ● Create and Bind Service Instances [page 244] ● Deploy the Application [page 246] ● Configure Roles and Trust [page 248] ● Set Up an Application Router [page 249] ● Configure the RFC Destination [page 253] ● Monitoring Your Web Application [page 254] (Optional) Related Information Scenario: Multitenancy for JCo Applications (Advanced) [page 254] 1.1.4.3.1.2.1 Develop a Sample Web Application Create a Web application to call an ABAP function module via RFC. SAP BTP Connectivity Connectivity PUBLIC 239
- 240. Steps 1. Create a Dynamic Web Project [page 216] 2. Include JCo Dependencies [page 217] 3. Create a Sample Servlet [page 218] Create a Dynamic Web Project 1. Open the Java EE perspective of the Eclipse IDE. 2. On the Project Explorer view, choose New Dynamic Web Project in the context menu. 3. Enter jco_demo as the project name. 4. In the Target Runtime pane, select Cloud Foundry . If it is not yet in the list of available runtimes, choose New Runtime and select it from there. 5. In the Configuration pane, leave the default configuration. 6. Choose Finish. 240 PUBLIC SAP BTP Connectivity Connectivity
- 241. Back to Steps [page 216] Include JCo Dependencies SAP BTP Connectivity Connectivity PUBLIC 241
- 242. To use JCo functionality seamlessly at compile time in Eclipse, you must include the JCo dependencies into your web project. Therefore, you must convert it into a maven project. 1. In the Project Explorer view, right-click on the project jco-demo and choose Configure Convert to Maven Project . 2. In the dialog window, leave the default settings unchanged and choose Finish. 3. Open the pom.xml file and include the following dependency: <dependencies> <dependency> <groupId>com.sap.cloud</groupId> <artifactId>neo-java-web-api</artifactId> <version>[3.71.8,4.0.0)</version> <scope>provided</scope> </dependency> </dependencies> Back to Steps [page 216] Create a Sample Servlet 1. From the jco_demo project node, choose New Servlet in the context menu. 2. Enter com.sap.demo.jco as the <package> and ConnectivityRFCExampleJava as the <Class name>. Choose Next. 3. Choose Finish to create the servlet and open it in the Java editor. 4. Replace the entire servlet class to make use of the JCo API. The JCo API is visible by default for cloud applications. You do not need to add it explicitly to the application class path. Sample Code package com.sap.demo.jco; import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import com.sap.conn.jco.AbapException; import com.sap.conn.jco.JCoDestination; import com.sap.conn.jco.JCoDestinationManager; import com.sap.conn.jco.JCoException; import com.sap.conn.jco.JCoFunction; import com.sap.conn.jco.JCoParameterList; import com.sap.conn.jco.JCoRepository; /** * Sample application that makes use of the capability to invoke a function module in an ABAP system * via RFC * 242 PUBLIC SAP BTP Connectivity Connectivity
- 243. * Note: The JCo APIs are available under <code>com.sap.conn.jco</code>. */ @WebServlet("/ConnectivityRFCExample/*") public class ConnectivityRFCExample extends HttpServlet { private static final long serialVersionUID = 1L; protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { PrintWriter responseWriter = response.getWriter(); try { // access the RFC Destination "JCoDemoSystem" JCoDestination destination = JCoDestinationManager.getDestination("JCoDemoSystem"); // make an invocation of STFC_CONNECTION in the backend; JCoRepository repo = destination.getRepository(); JCoFunction stfcConnection = repo.getFunction("STFC_CONNECTION"); JCoParameterList imports = stfcConnection.getImportParameterList(); imports.setValue("REQUTEXT", "SAP BTP Connectivity runs with JCo"); stfcConnection.execute(destination); JCoParameterList exports = stfcConnection.getExportParameterList(); String echotext = exports.getString("ECHOTEXT"); String resptext = exports.getString("RESPTEXT"); response.addHeader("Content-type", "text/html"); responseWriter.println("<html><body>"); responseWriter.println("<h1>Executed STFC_CONNECTION in system JCoDemoSystem</h1>"); responseWriter.println("<p>Export parameter ECHOTEXT of STFC_CONNECTION:<br>"); responseWriter.println(echotext); responseWriter.println("<p>Export parameter RESPTEXT of STFC_CONNECTION:<br>"); responseWriter.println(resptext); responseWriter.println("</body></html>"); } catch (AbapException ae) { // just for completeness: As this function module does not have an exception // in its signature, this exception cannot occur. But you should always // take care of AbapExceptions } catch (JCoException e) { response.addHeader("Content-type", "text/html"); responseWriter.println("<html><body>"); responseWriter .println("<h1>Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem</h1>"); responseWriter.println("<pre>"); e.printStackTrace(responseWriter); responseWriter.println("</pre>"); responseWriter.println("</body></html>"); } } } 5. Save the Java editor and make sure that the project compiles without errors. Back to Steps [page 216] SAP BTP Connectivity Connectivity PUBLIC 243
- 244. Next Steps ● Create and Bind Service Instances [page 244] ● Deploy the Application [page 246] ● Configure Roles and Trust [page 248] ● Set Up an Application Router [page 249] ● Configure the RFC Destination [page 253] ● Monitoring Your Web Application [page 254] (Optional) 1.1.4.3.1.2.2 Create and Bind Service Instances You must create and bind several service instances, before you can use your application. Procedure 1. Logon to the cloud cockpit and choose your subaccount. 2. Choose the space where you want to deploy your demo application. 3. Choose Service Marketplace and find these 2 services: ○ Destination ○ Authorization & Trust Management (XSUAA) 4. Create and bind a service instance for each of these services. ○ Destination service [page 221] ○ Authorization & Trust Management (XSUAA service) [page 222] 244 PUBLIC SAP BTP Connectivity Connectivity
- 245. Destination Service 1. Choose Destination Create Instance . 2. Insert an instance name (for example, destination_jco) and choose Create Instance. Back to Procedure [page 220] Authorization & Trust Management (XSUAA Service) 1. Choose Authorization & Trust Management Create Instance 2. Select <Service Plan> application. 3. Enter an <Instance Name> and choose Next. Note The instance name must match the one defined in the manifest file. 4. In the next tab Parameters , insert the following as a JSON file: Sample Code { "xsappname" : "jco-demo-p1234", "tenant-mode": "dedicated", "scopes": [ { "name": "$XSAPPNAME.all", "description": "all" } ], "role-templates": [ { "name": "all", "description": "all", "scope-references": [ "$XSAPPNAME.all" ] } ] } 5. Go to tab Review and choose Create Instance. Back to Procedure [page 220] SAP BTP Connectivity Connectivity PUBLIC 245
- 246. Next Steps ● Deploy the Application [page 246] ● Configure Roles and Trust [page 248] ● Set Up an Application Router [page 249] ● Configure the RFC Destination [page 253] ● Monitoring Your Web Application [page 254] (Optional) 1.1.4.3.1.2.3 Deploy the Application Deploy your Cloud Foundry application to call an ABAP function module via RFC. Prerequisites You have created and bound the required service instances, see Create and Bind Service Instances [page 220]. Procedure 1. To deploy your Web application, you can use the following two alternative procedures: ○ Deploying from the Eclipse IDE ○ Deploying from the CLI, see Developing Java in the Cloud Foundry Environment 2. In the following, we publish it with the CLI. 3. To do this, create a manifest.yml file. The key parameter is USE_JCO: true, which must be set to include JCo into the buildpack during deployment. manifest.yml Sample Code --- applications: - name: jco-demo-p1234 buildpacks: - sap_java_buildpack env: USE_JCO: true # This is necessary only if more than one instance is bound xsuaa_connectivity_instance_name: "xsuaa_jco" connectivity_instance_name: "connectivity_jco" destination_instance_name: "destination_jco" services: - xsuaa_jco - connectivity_jco 246 PUBLIC SAP BTP Connectivity Connectivity
- 247. - destination_jco Caution The client libraries (java-security, spring-xsuaa, and container security api for node.js as of version 3.0.6) have been updated. When using these libraries, setting the parameter SAP_JWT_TRUST_ACL has become obsolete. This update comes with a change regarding scopes: ○ For a business application A calling an application B, it is now mandatory that application B grants at least one scope to the calling business application A. ○ Business application A must accept these granted scopes or authorities as part of the application security descriptor. You can grant scopes using the xs-security.json file. For more information, see Application Security Descriptor Configuration Syntax, specifically the sections Referencing the Application and Authorities. Note If you have more than one instance of those three services bound to your application, you must specify which one JCo should use with the respective env parameters: ○ xsuaa_connectivity_instance_name ○ connectivity_instance_name ○ destination_instance_name. 4. In Eclipse, right-click on the project and navigate to Export WAR file . 5. Choose a destination by pressing the Browse... button next to the manifest.yml you created before, for example as jcodemo.war. 6. Leave the other default settings unchanged and choose Finish to export the WAR file. 7. Perform a CLI login via cf login -a api.cf.eu10.hana.ondemand.com -u <your_email_address> (password, org and space are prompted after a successful login). 8. Push the application with cf push -f manifest.yml -p jcodemo.war. 9. Now, the application should be deployed successfully. Next Steps ● Configure Roles and Trust [page 248] ● Set Up an Application Router [page 249] ● Configure the RFC Destination [page 253] ● Monitoring Your Web Application [page 254] (Optional) SAP BTP Connectivity Connectivity PUBLIC 247
- 248. 1.1.4.3.1.2.4 Configure Roles and Trust Configure a role that enables your user to access your Web application. To add and assign roles, navigate to the subaccount view of the cloud cockpit and choose Security Role Collections . 1. Create a new role collection with the name all. 2. From the subaccount menu, choose Trust Configuration. 3. If you don't have a trust configuration, follow the steps in Manually Establish Trust and Federation Between UAA and Identity Authentication. 4. Click on the IdP name of your choice. 5. Type in your e-mail address and choose Show Assignments. 6. If your user has not yet been added to the SAP ID service, you see following popup. In this case, add your user now. 7. You should now be able to click Assign Role Collection. Choose role collection all and assign it. Next Steps ● Set Up an Application Router [page 249] ● Configure the RFC Destination [page 253] ● Monitoring Your Web Application [page 254] (Optional) Related Information Working with Role Collections 248 PUBLIC SAP BTP Connectivity Connectivity
- 249. 1.1.4.3.1.2.5 Set Up an Application Router For authentication purposes, configure and deploy an application router for your test application. Note AppRouter is only required if you want to use multitenancy or perform user-specific service calls. In all other cases, JCo uses cloud-security-xsuaa-integration with ClientCredentialFlow. 1. To set up an application router, follow the steps in Application Router or use the demo file approuter.zip (download). 2. For deployment, you need a manifest file, similar to this one: Sample Code --- applications: - name: approuter-jco-demo-p1234 path: ./ buildpacks: - nodejs_buildpack memory: 120M routes: - route: approuter-jco-demo-p1234.cfapps.eu10.hana.ondemand.com env: NODE_TLS_REJECT_UNAUTHORIZED: 0 destinations: > [ {"name":"dest-to-example", "url" :"https://jco-demo- p1234.cfapps.eu10.hana.ondemand.com/ConnectivityRFCExample", "forwardAuthToken": true } ] services: - xsuaa_jco Note ○ The routes and destination URLs need to fit your test application. ○ In this example, we already bound our XSUAA instance to the application router. Alternatively, you could also do this via the cloud cockpit. 3. Push the approuter with cf push -f manifest.yml -p approuter.zip. 4. To navigate to the approuter application in the cloud cockpit, choose <your_space> Applications <your application> Overview . SAP BTP Connectivity Connectivity PUBLIC 249
- 250. 5. When choosing the application route, you are requested to login. Provide the credentials known by the IdP you configured in Roles & Trust. 6. After successful login, you are routed to the test application which is then executed. 7. If the application issues an exception, saying that the JCoDemoSystem destination has not yet been specified, you must configure the JCoDemoSystem destination first. Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem com.sap.conn.jco.JCoException: (106) JCO_ERROR_RESOURCE: Destination JCoDemoSystem does not exist at com.sap.conn.jco.rt.DefaultDestinationManager.update(DefaultDestinationManager .java:223) at com.sap.conn.jco.rt.DefaultDestinationManager.searchDestination(DefaultDestina tionManager.java:377) at com.sap.conn.jco.rt.DefaultDestinationManager.getDestinationInstance(DefaultDe stinationManager.java:96) at com.sap.conn.jco.JCoDestinationManager.getDestination(JCoDestinationManager.ja va:52) at com.sap.demo.jco.ConnectivityRFCExample.doGet(ConnectivityRFCExample.java:47) ..... (cut rest of the call stack) Calling JCo APIs from Newly Created Threads If you are using an Application Router and it is mandatory for you to call JCo APIs from a different thread than the one which is executing your servlet function, make sure the thread local information of the cloud-security- xsuaa-integration API , used by JCo internally, is set again within your newly created thread. To do this, add the following dependency to your project: <dependency> <groupId>com.sap.cloud.security</groupId> <artifactId>java-api</artifactId> <version>2.7.7</version> <scope>provided</scope> 250 PUBLIC SAP BTP Connectivity Connectivity
- 251. </dependency> Note Make sure you don't include this dependency with scope compile transitively with any other jar, for example, with <dependency> <groupId>com.sap.cloud.security</groupId> <artifactId>java-security</artifactId> </dependency> In this case, you must exclude java-api from this dependency and add it again as described above, with scope provided. Adjust your code from the step Develop a Sample Web Application [page 239] in the following way: Sample Code package com.sap.demo.jco; import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import com.sap.cloud.security.token.SecurityContext; import com.sap.cloud.security.token.Token; import com.sap.conn.jco.AbapException; import com.sap.conn.jco.JCoDestination; import com.sap.conn.jco.JCoDestinationManager; import com.sap.conn.jco.JCoException; import com.sap.conn.jco.JCoFunction; import com.sap.conn.jco.JCoParameterList; import com.sap.conn.jco.JCoRepository; /** * * Sample application that uses the connectivity service. In particular, it is * making use of the capability to invoke a function module in an ABAP system * via RFC * * Note: The JCo APIs are available under <code>com.sap.conn.jco</code>. */ @WebServlet("/ConnectivityRFCExample/*") public class ConnectivityRFCExample extends HttpServlet { private static final long serialVersionUID = 1L; protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { PrintWriter responseWriter = response.getWriter(); // access the token from the thread which is executing the servlet Token token = SecurityContext.getToken(); Thread runThread = new Thread(() -> { // set the information in the newly created thread SecurityContext.setToken(token); try { // access the RFC Destination "JCoDemoSystem" JCoDestination destination = JCoDestinationManager.getDestination("JCoDemoSystem_Normal"); // make an invocation of STFC_CONNECTION in the backend SAP BTP Connectivity Connectivity PUBLIC 251
- 252. JCoRepository repo = destination.getRepository(); JCoFunction stfcConnection = repo.getFunction("STFC_CONNECTION"); JCoParameterList imports = stfcConnection.getImportParameterList(); imports.setValue("REQUTEXT", "SAP BTP Connectivity runs with JCo"); stfcConnection.execute(destination); JCoParameterList exports = stfcConnection.getExportParameterList(); String echotext = exports.getString("ECHOTEXT"); String resptext = exports.getString("RESPTEXT"); response.addHeader("Content-type", "text/html"); responseWriter.println("<html><body>"); responseWriter.println("<h1>Executed STFC_CONNECTION in system JCoDemoSystem</h1>"); responseWriter.println("<p>Export parameter ECHOTEXT of STFC_CONNECTION:<br>"); responseWriter.println(echotext); responseWriter.println("<p>Export parameter RESPTEXT of STFC_CONNECTION:<br>"); responseWriter.println(resptext); responseWriter.println("</body></html>"); } catch (AbapException ae) { // just for completeness: As this function module does not have an exception // in its signature, this exception cannot occur. But you should always // take care of AbapExceptions } catch (JCoException e) { response.addHeader("Content-type", "text/html"); responseWriter.println("<html><body>"); responseWriter .println("<h1>Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem</h1>"); responseWriter.println("<pre>"); e.printStackTrace(responseWriter); responseWriter.println("</pre>"); responseWriter.println("</body></html>"); } finally { // after execution clear the token again SecurityContext.clearToken(); } }); runThread.start(); // wait to be finished try { runThread.join(); } catch (InterruptedException e) { e.printStackTrace(responseWriter); } } } Note If you want to use thread pools , make sure that in your thread pool implementation this information is set correctly in the thread which is about to be (re)used, and removed as soon as the thread is put back into the pool. 252 PUBLIC SAP BTP Connectivity Connectivity
- 253. Next Steps ● Configure the RFC Destination [page 253] ● Monitoring Your Web Application [page 254] (Optional) 1.1.4.3.1.2.6 Configure the RFC Destination Configure an RFC destination on SAP BTP that you can use in your Web application to call the cloud ABAP system. To configure the destination, you must use a WebSocket application server host name (<id>.abap.eu10.hana.ondemand.com) and a WebSocket port (443). 1. Create a .properties file with the following settings: Name=JCoDemoSystem Type=RFC jco.client.wshost= <id>.abap.eu10.hana.ondemand.com jco.client.wsport=443 jco.client.alias_user=<DEMOUSER> jco.client.passwd=<Password> jco.client.client=100 jco.client.lang=EN jco.destination.pool_capacity=5 jco.destination.proxy_type=Internet 2. Go to your subaccount in the cloud cockpit. 1. From the subaccount menu, choose Connectivity Destinations Import Destination and upload this file. 2. Alternatively, you can create a destination for the service instance destination_jco to make it visible only for this instance. To do this, go to <your space> Services Service Instances <your destination_instance> and choose Destinations. 3. Specify a trust/key store or security information, see WebSocket Connection [page 118]. Next Steps ● Monitoring Your Web Application [page 254] (Optional) Related Information Target System Configuration [page 115] SAP BTP Connectivity Connectivity PUBLIC 253
- 254. 1.1.4.3.1.2.7 Monitoring Your Web Application Monitor the state and logs of your Web application deployed on SAP BTP, using the Application Logging service. For this purpose, create an instance of the Application Logging service (as you did for the Destination service) and bind it to your application, see Create and Bind Service Instances [page 220]. To activate JCo logging, set the following property in the env section of your manifest file: SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: INFO}' Now you can see and open the logs in the cloud cockpit or in the Kibana Dashboard in the tab Logs, if you are within your application. For detailed information, you can activate the internal JCo logs: SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: DEBUG, com.sap.conn.jco: DEBUG}' Including other relevant components for logging: SET_LOGGING_LEVEL: '{com.sap.core.connectivity.jco: DEBUG, com.sap.conn.jco: DEBUG, com.sap.xs.security: DEBUG, com.sap.cloud.security: DEBUG, com.sap.xs.env: DEBUG}' 1.1.4.3.1.3 Scenario: Multitenancy for JCo Applications (Advanced) Learn about the required steps to make your Cloud Foundry JCo application tenant-aware. Using this procedure, you can enable the sample JCo application created in Scenario: Invoke ABAP Function Modules in On-Premise ABAP Systems [page 212] or Scenario: Invoke ABAP Function Modules in Cloud ABAP Systems [page 236], for multitenancy. Steps 1. Prerequisites [page 255] 2. Adjust the Application Router [page 255] 3. Adjust the XSUAA Service Instance and Roles [page 256] 4. Make the Application Subscribable [page 257] 254 PUBLIC SAP BTP Connectivity Connectivity
- 255. 5. Create the SAAS Provisioning Service [page 262] 6. Subscribe to the Application [page 263] 7. Create a New Route [page 265] Prerequisites ● Your runtime environment uses SAP Java Buildpack version 1.9.0 or higher. ● You have successfully completed one of these precedures: Scenario: Invoke ABAP Function Modules in On-Premise ABAP Systems [page 212] Scenario: Invoke ABAP Function Modules in Cloud ABAP Systems [page 236] ● You have created a second subaccount (in the same global account), that is used to subscribe to your application. Back to Steps [page 254] Adjust the Application Router The application router needs to be tenant-aware with a TENANT_HOST_PATTERN to recognize different tenants from the URL, see Multitenancy. TENANT_HOST_PATTERN should have the following format: "^(.*).<application domain>". The application router extracts the token captured by "(.*)" to use it as the subscriber tenant. The manifest file might look like this: Sample Code manifest.yml --- applications: - name: approuter-jco-demo-p42424242 path: ./ buildpacks: - nodejs_buildpack memory: 120M routes: - route: approuter-jco-demo-p42424242.cfapps.eu10.hana.ondemand.com env: TENANT_HOST_PATTERN: "^(.*).approuter-jco-demo- p42424242.cfapps.eu10.hana.ondemand.com" NODE_TLS_REJECT_UNAUTHORIZED: 0 destinations: > [ {"name":"dest-to-example", "url" :"https://jco-demo- p42424242.cfapps.eu10.hana.ondemand.com/ConnectivityRFCExample", "forwardAuthToken": true } ] services: - xsuaa_jco SAP BTP Connectivity Connectivity PUBLIC 255
- 256. Back to Steps [page 254] Adjust the XSUAA Service Instance and Roles To call the XSUAA in a tenant-aware way, you must adjust the configuration JSON file. The tenant mode must now have the value "shared". Also, you must allow calling the previously defined REST APIs (callbacks). Sample Code { "xsappname" : "jco-demo-p42424242", "tenant-mode": "shared", "scopes": [ { "name":"$XSAPPNAME.Callback", "description":"With this scope set, the callbacks for tenant onboarding, offboarding and getDependencies can be called.", "grant-as-authority-to-apps":[ "$XSAPPNAME(application,sap-provisioning,tenant-onboarding)" ] }, { "name": "$XSAPPNAME.access", "description": "app access" }, { "name": "uaa.user", "description": "uaa.user" } ], "role-templates": [ { "name":"MultitenancyCallbackRoleTemplate", "description":"Call callback-services of applications", "scope-references":[ "$XSAPPNAME.Callback" ] }, { "name": "UAAaccess", "description": "UAA user access", "scope-references": [ "uaa.user", "$XSAPPNAME.access" ] } ] } Add Roles 1. In the cloud cockpit, navigate to the subaccount view and go the tab Role Collections under Security (see step Configure Roles and Trust [page 225] from the previous procedure). 2. Click on the role collection name. 3. Choose Add Role. 256 PUBLIC SAP BTP Connectivity Connectivity
- 257. 4. In the popup window, select the demo application as <Application Identifier>. 5. For <Role Template> and <Role>, use MultitenancyCallbackRoleTemplate and choose Save. 6. Choose Add Role again. 7. Select the demo application as <Application Identifier>. 8. For Role Template and Role use UAAaccess and choose Save. Back to Steps [page 254] Make the Application Subscribable Firstly, in order to make the application subscribable, it must provide at least the following REST APIs: ● GET dependent services of an application [page 257] ● PUT tenant subscription to an application [page 260] In our sample application, we implement new servlets for each of these APIs. The following servlets need additional maven dependencies: Sample Code <dependency> <groupId>com.google.code.gson</groupId> <artifactId>gson</artifactId> <version>2.8.5</version> </dependency> <dependency> <groupId>com.unboundid.components</groupId> <artifactId>json</artifactId> <version>1.0.0</version> </dependency> <dependency> <groupId>javax.ws.rs</groupId> <artifactId>javax.ws.rs-api</artifactId> <version>2.1.1</version> </dependency> GET Dependencies The current JCo dependencies are the Connectivity and Destination service. Thus, the GET API must return information about these two services: Sample Code import java.io.IOException; import java.util.Arrays; import java.util.List; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; SAP BTP Connectivity Connectivity PUBLIC 257
- 258. import javax.servlet.http.HttpServletResponse; import javax.ws.rs.core.MediaType; import org.json.JSONException; import org.json.JSONObject; import com.google.gson.Gson; @WebServlet("/callback/v1.0/dependencies") public class GetDependencyServlet extends HttpServlet { private static final long serialVersionUID = 1L; private static final String DESTINATION_SERVICE_NAME = "destination"; private static final String CONNECTIVITY_SERVICE_NAME = "connectivity"; private static final String XSAPPNAME_PROPERTY = "xsappname"; protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { try { DependantServiceDto destinationService = createLPSDependency(DESTINATION_SERVICE_NAME); DependantServiceDto connectivityService = createLPSDependency(CONNECTIVITY_SERVICE_NAME); List<DependantServiceDto> dependenciesList = Arrays.asList(destinationService, connectivityService); response.setStatus(200); response.setContentType(MediaType.APPLICATION_JSON); String json = new Gson().toJson(dependenciesList); response.getWriter().println(json); } catch (JSONException e) { response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, e.getMessage()); } } private static DependantServiceDto createLPSDependency(String serviceName) throws JSONException { JSONObject credentials = EnvironmentVariableAccessor.getServiceCredentials(serviceName); String xsappname = credentials.getString(XSAPPNAME_PROPERTY); return new DependantServiceDto(serviceName, xsappname); } } Find the code of the two helper classes below: DependantServiceDto.java public class DependantServiceDto { private String appName; private String appId; public DependantServiceDto() {} public DependantServiceDto(String appName, String appId) { this.appName = appName; this.appId = appId; } public String getAppName() { return appName; } public void setAppName(String appName) { this.appName = appName; } 258 PUBLIC SAP BTP Connectivity Connectivity
- 259. public String getAppId() { return appId; } public void setAppId(String appId) { this.appId = appId; } @Override public boolean equals(Object o) { if (this == o) return true; if (!(o instanceof DependantServiceDto)) return false; DependantServiceDto that = (DependantServiceDto) o; if (!appName.equals(that.appName)) return false; return appId.equals(that.appId); } @Override public int hashCode() { int result = appName.hashCode(); result = 31 * result + appId.hashCode(); return result; } } EnvironmentVariableAccessor.java import java.text.MessageFormat; import org.json.JSONArray; import org.json.JSONException; import org.json.JSONObject; /** * Methods for extracting configurations from the environment variables */ public final class EnvironmentVariableAccessor { public static final String BEARER_WITH_TRAILING_SPACE="Bearer "; private static final String VCAP_SERVICES=System.getenv("VCAP_SERVICES"); private static final String VCAP_SERVICES_CREDENTIALS="credentials"; private static final String VCAP_SERVICES_NAME="name"; private static final String PROP_XSUAA_CONNECTIVITY_INSTANCE_NAME="xsuaa_connectivity_instance_name"; private static final String DEFAULT_XSUAA_CONNECTIVITY_INSTANCE_NAME="conn- xsuaa"; private EnvironmentVariableAccessor() { } /** * Returns service credentials for a given service from VCAP_SERVICES * * @see <a href= "https://docs.run.pivotal.io/devguide/deploy-apps/ environment-variable.html#VCAP-SERVICES">VCAP_SERVICES</a> */ public static JSONObject getServiceCredentials(String serviceName) throws JSONException { return new JSONObject(VCAP_SERVICES).getJSONArray(serviceName).getJSONObject(0).getJSONObjec t(VCAP_SERVICES_CREDENTIALS); } /** * Returns service credentials for a given service instance from VCAP_SERVICES * * @see <a href= "https://docs.run.pivotal.io/devguide/deploy-apps/ environment-variable.html#VCAP-SERVICES">VCAP_SERVICES</a> */ SAP BTP Connectivity Connectivity PUBLIC 259
- 260. public static JSONObject getServiceCredentials(String serviceName, String serviceInstanceName) throws JSONException { JSONArray jsonarr=new JSONObject(VCAP_SERVICES).getJSONArray(serviceName); for (int i=0; i<jsonarr.length(); i++) { JSONObject serviceInstanceObject=jsonarr.getJSONObject(i); String instanceName=serviceInstanceObject.getString(VCAP_SERVICES_NAME); if (instanceName.equals(serviceInstanceName)) { return serviceInstanceObject.getJSONObject(VCAP_SERVICES_CREDENTIALS); } } throw new RuntimeException(MessageFormat.format("Service instance {0} of service {1} not bound to application", serviceInstanceName, serviceName)); } /** * Returns service credentials attribute for a given service from VCAP_SERVICES * * @see <a href= "https://docs.run.pivotal.io/devguide/deploy-apps/ environment-variable.html#VCAP-SERVICES">VCAP_SERVICES</a> */ public static String getServiceCredentialsAttribute(String serviceName, String attributeName) throws JSONException { return getServiceCredentials(serviceName).getString(attributeName); } /** * Returns the name of the xsuaa service for connectivity service. */ public static String getXsuaaConnectivityInstanceName() { String xsuaaConnectivityInstanceName=System.getenv(PROP_XSUAA_CONNECTIVITY_INSTANCE_NAME ); return xsuaaConnectivityInstanceName!=null? xsuaaConnectivityInstanceName:DEFAULT_XSUAA_CONNECTIVITY_INSTANCE_NAME; } } Back to Make the Application Subscribable [page 257] PUT Tenant Subscription This API is called whenever a tenant is subscribing. In our example, we just read the received JSON, and return the tenant-aware URL of the application router which points to our application. Also, if a tenant wants to unsubscribe, DELETE does currently nothing. Sample Code SubscribeServlet import java.io.IOException; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; 260 PUBLIC SAP BTP Connectivity Connectivity
- 261. import com.google.gson.Gson; @WebServlet("/callback/v1.0/tenants/*") public class SubscribeServlet extends HttpServlet { private static final long serialVersionUID = 1L; protected void doPut(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { PayloadDataDto payload = new Gson().fromJson(request.getReader(), PayloadDataDto.class); response.getWriter().println("https://" + payload.getSubscribedSubdomain() + ".approuter-jco- demo.cfapps.eu10.hana.ondemand.com"); } @Override protected void doDelete(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { super.doDelete(req, resp); } } Here is the helper class: PayloadDataDto.java import java.util.Map; public class PayloadDataDto { private String subscriptionAppName; private String subscriptionAppId; private String subscribedTenantId; private String subscribedSubdomain; private String subscriptionAppPlan; private long subscriptionAppAmount; private String[] dependantServiceInstanceAppIds = null; private Map<String, String> additionalInformation; public PayloadDataDto() {} public PayloadDataDto(String subscriptionAppName, String subscriptionAppId, String subscribedTenantId, String subscribedSubdomain, String subscriptionAppPlan, Map<String, String> additionalInformation) { this.subscriptionAppName = subscriptionAppName; this.subscriptionAppId = subscriptionAppId; this.subscribedTenantId = subscribedTenantId; this.subscribedSubdomain = subscribedSubdomain; this.subscriptionAppPlan = subscriptionAppPlan; this.additionalInformation = additionalInformation; } public String getSubscriptionAppName() { return subscriptionAppName; } public void setSubscriptionAppName(String subscriptionAppName) { this.subscriptionAppName = subscriptionAppName; } public String getSubscriptionAppId() { return subscriptionAppId; } public void setSubscriptionAppId(String subscriptionAppId) { this.subscriptionAppId = subscriptionAppId; } public String getSubscribedTenantId() { return subscribedTenantId; } SAP BTP Connectivity Connectivity PUBLIC 261
- 262. public void setSubscribedTenantId(String subscribedTenantId) { this.subscribedTenantId = subscribedTenantId; } public String getSubscribedSubdomain() { return subscribedSubdomain; } public void setSubscribedSubdomain(String subscribedSubdomain) { this.subscribedSubdomain = subscribedSubdomain; } public String getSubscriptionAppPlan() { return subscriptionAppPlan; } public void setSubscriptionAppPlan(String subscriptionAppPlan) { this.subscriptionAppPlan = subscriptionAppPlan; } public Map<String, String> getAdditionalInformation() { return additionalInformation; } public void setAdditionalInformation(Map<String, String> additionalInformation) { this.additionalInformation = additionalInformation; } public long getSubscriptionAppAmount() { return subscriptionAppAmount; } public void setSubscriptionAppAmount(long subscriptionAppAmount) { this.subscriptionAppAmount = subscriptionAppAmount; } public String[] getDependantServiceInstanceAppIds() { return dependantServiceInstanceAppIds; } public void setDependantServiceInstanceAppIds( String[] dependantServiceInstanceAppIds) { this.dependantServiceInstanceAppIds = dependantServiceInstanceAppIds; } public String toString() { return String.format("Payload data: subscriptionAppName=%s, subscriptionAppId=%s, subscribedTenantId=%s," + "subscribedSubdomain=%s subscriptionAppPlan=%s subscriptionAppAmount=%s dependantServiceInstanceAppIds=%s", this.subscriptionAppName, this.subscriptionAppId, this.subscribedTenantId, this.subscribedSubdomain, this.subscriptionAppPlan, this.getSubscriptionAppAmount(), dependantServiceInstanceAppIds); } } Back to Make the Application Subscribable [page 257] Back to Steps [page 254] Create the SAAS Provisioning Service For the subscription of other tenants, your application must have a bound SAAS provisioning service instance. You can do this using the cockpit: 1. Go to the Service Marketplace in the cloud cockpit: 262 PUBLIC SAP BTP Connectivity Connectivity
- 263. 2. Choose Saas Provisioning Instances New Instance . 3. Select application as <Service Plan> and choose Next. 4. In the step Specify Parameters (Optional), insert the following as a JSON file: Sample Code { "xsappname" : "jco-demo-p42424242", "appName" : "JCo-Demo", "appUrls": { "getDependencies": "https://jco-demo- p42424242.cfapps.eu10.hana.ondemand.com/callback/v1.0/dependencies", "onSubscription" : "https://jco-demo- p42424242.cfapps.eu10.hana.ondemand.com/callback/v1.0/tenants/{tenantId}" } } 5. Choose Next, and select the sample application jco-demo-p42424242 in the drop-down menu to assign the SAAS service to it. 6. Choose Next, insert an instance name, for example, saas_jco, and confirm the creation by pressing Finish. Back to Steps [page 254] Subscribe to the Application 1. To subscribe the new application from a different subaccount, go to Subscriptions in the cockpit: SAP BTP Connectivity Connectivity PUBLIC 263
- 264. 2. Click on JCo-Demo. 3. In the next window, choose Subscribe: 4. If the subscription was successful, your window should look like that: 264 PUBLIC SAP BTP Connectivity Connectivity
- 265. Back to Steps [page 254] Create a New Route 1. To call the application with a new tenant, you must create a new route (URL). In the cockpit, choose Routes New Route : 2. For <Domain>, select the landscape your application is deployed in (e.g. cfapps.eu10.hana.ondemand.com). 3. For <Host Name>, choose the tenant-specific link. In our example it would be <tenant-subdomain- name>.approuter-jco-demo-p42424242. 4. Choose Save. 5. Choose Map Route of the newly created route where the field <Mapped Applications> is empty (value none): 6. Select the approuter application and choose Save. 7. Congratulations, you are done, now you are able to call the sample application with this newly created route from the other subaccount! Back to Steps [page 254] SAP BTP Connectivity Connectivity PUBLIC 265
- 266. 1.1.5 Security Find an overview of recommended security measures for SAP BTP Connectivity. Topic More Information Enable single sign-on by forwarding the identity of cloud users to a remote system or service. Principal Propagation [page 121] Set up and run the Cloud Connector according to the highest security standards. Security Guidelines [page 563] 1.1.6 Monitoring and Troubleshooting Find information on monitoring and troubleshooting for SAP BTP Connectivity. Getting Support If you encounter an issue with this service, we recommend to follow the procedure below: Check Platform Status Check the availability of the platform at SAP BTP Status Page . For more information about selected platform incidents, see Root Cause Analyses. Check Guided Answers In the SAP Support Portal, check the Guided Answers section for SAP BTP. You can find solutions for general SAP BTP issues as well as for specific services there. Contact SAP Support You can report an incident or error through the SAP Support Portal . To find the relevant component for your for SAP BTP Connectivity incident, see Connectivity Support [page 581] (section SAP Support Information). When submitting the incident, we recommend including the following information: ● Region information (for example: Canary, EU10, US10) ● Subaccount technical name ● The URL of the page where the incident or error occurs 266 PUBLIC SAP BTP Connectivity Connectivity
- 267. ● The steps or clicks used to replicate the error ● Screenshots, videos, or the code entered More Information Topic More Information Monitor the Cloud Connector from the SAP BTP cockpit and from the Cloud Connector administration UI. Monitoring [page 516] Troubleshoot connection problems and view different types of logs and traces in the Cloud Connector. Troubleshooting [page 548] Detailed support information for SAP Connectivity service and the Cloud Connector. Connectivity Support [page 581] 1.2 Cloud Connector Learn more about the Cloud Connector: features, scenarios and setup. Note This documentation refers to SAP BTP, Cloud Foundry environment. If you are looking for information about the Neo environment, see Connectivity for the Neo Environment. Content In this Topic Hover over the elements for a description. Click an element for more information. SAP BTP Connectivity Connectivity PUBLIC 267
- 268. ● Context [page 268] ● Basic Scenarios [page 269] ● Basic Tasks [page 272] ● Advantages [page 269] ● Extended Scenarios [page 271] ● What's New? [page 272] In this Guide Hover over the elements for a description. Click an element for more information. ● Configuration [page 311] ● Installation [page 273] ● Operations [page 502] ● Frequently Asked Questions [page 571] ● Upgrade [page 567] ● Security [page 556] ● Update the Java VM [page 569] ● Uninstallation [page 570] ● Connectivity Support [page 581] ● Security Guidelines [page 563] Context The Cloud Connector: ● Serves as a link between SAP BTP applications and on-premise systems. ○ Combines an easy setup with a clear configuration of the systems that are exposed to the SAP BTP. ○ Lets you use existing on-premise assets without exposing the entire internal landscape. 268 PUBLIC SAP BTP Connectivity Connectivity
- 269. ● Runs as on-premise agent in a secured network. ○ Acts as a reverse invoke proxy between the on-premise network and SAP BTP. ● Provides fine-grained control over: ○ On-premise systems and resources that can be accessed by cloud applications. ○ Cloud applications using the Cloud Connector. ● Lets you use the features that are required for business-critical enterprise scenarios. ○ Recovers broken connections automatically. ○ Provides audit logging of inbound traffic and configuration changes. ○ Can be run in a high-availability setup. Caution The Cloud Connector must not be used to connect to products other than SAP BTP or S/4HANA Cloud. Back to Content [page 267] Advantages Compared to the approach of opening ports in the firewall and using reverse proxies in the DMZ to establish access to on-premise systems, the Cloud Connector offers the following benefits: ● You don't need to configure the on-premise firewall to allow external access from SAP BTP to internal systems. For allowed outbound connections, no modifications are required. ● The Cloud Connector supports HTTP as well as additional protocols. For example, the RFC protocol supports native access to ABAP systems by invoking function modules. ● You can use the Cloud Connector to connect on-premise databases or BI tools to SAP HANA databases in the cloud. ● The Cloud Connector lets you propagate the identity of cloud users to on-premise systems in a secure way. ● Easy installation and configuration, which means that the Cloud Connector comes with a low TCO and is tailored to fit your cloud scenarios. ● SAP provides standard support for the Cloud Connector. Back to Content [page 267] Basic Scenarios Connecting Cloud Applications to On-Premise Systems [page 270] Connecting On-Premise Database Tools to SAP HANA Databases [page 270] SAP BTP Connectivity Connectivity PUBLIC 269
- 270. Note This section refers to the Cloud Connector installation in a standard on-premise network. Find setup options for other system environments in Extended Scenarios [page 271]. Connecting Cloud Applications to On-Premise Systems 1. Install the Cloud Connector: Installation [page 273] 2. Set up the connection between Cloud Connector, back-end system and your SAP BTP subaccount : Initial Configuration [page 312], Managing Subaccounts [page 328] 3. Allow your cloud application to access a back-end system on the intranet: Configure Access Control [page 369] 4. Connect your cloud application to an on-premise system: Consuming the Connectivity Service [page 164] (Cloud Foundry environment) Back to Basic Scenarios [page 269] Back to Content [page 267] Connecting On-Premise Database Tools to SAP HANA Databases 270 PUBLIC SAP BTP Connectivity Connectivity
- 271. 1. Install and configure the Cloud Connector: Installation [page 273], Initial Configuration [page 312], Managing Subaccounts [page 328] 2. Access HANA databases on SAP BTP: Configure a Service Channel for an SAP HANA Database [page 483] 3. Connect on-premise database or BI tools to a HANA database on SAP BTP: Connect DB Tools to SAP HANA via Service Channels [page 486] Note You can use service channels also for other purposes: ● Connect to a virtual machine on SAP BTP. ● Configure an RFC connection from your on-premise system to S/4HANA Cloud. See Using Service Channels [page 482]. Back to Basic Scenarios [page 269] Back to Content [page 267] Extended Scenarios Besides the standard setup: SAP BTP - Cloud Connector - on-premise system/network, you can also use the Cloud Connector to connect SAP BTP applications to other cloud-based environments, as long as they are operated in a way that is comparable to an on-premise network from a functional perspective. This is particularly true for infrastructure (IaaS) hosting solutions. SAP BTP Connectivity Connectivity PUBLIC 271
- 272. Here's an overview of all environments in which you can or cannot set up the Cloud Connector: Cloud Connector Environment Examples Can be set up in: Note Within extended scenarios that al low a Cloud Connector setup, spe cial procedures may apply for con figuration. If so, they are mentioned in the corresponding configuration steps. Customer on-premise network (see Ba sic Scenarios [page 269]) SAP ERP, SAP S/4HANA SAP Hosting SAP HANA Enterprise Cloud (HEC) Third-party IaaS providers (hosting) Amazon Web Services (AWS), Microsoft Azure, Google Cloud Platform (GCP) Cannot be set up in: SAP SaaS solutions SAP SuccessFactors, SAP Concur, SAP Ariba SAP cloud-based enterprise solutions SAP S/4HANA Cloud, SAP C/4HANA Third-party PaaS providers AWS, Azure, GCP Third-party SaaS providers Back to Content [page 267] Basic Tasks The following steps are required to connect the Cloud Connector to your SAP BTP subaccount: ● Install the Cloud Connector: Installation [page 273] ● Perform the initial configuration for the Cloud Connector: Initial Configuration [page 312] ● Register the Cloud Connector for your SAP BTP subaccount: Managing Subaccounts [page 328] Back to Content [page 267] What's New? Follow the SAP BTP Release Notes to stay informed about Cloud Connector and Connectivity updates. Back to Content [page 267] Related Information 272 PUBLIC SAP BTP Connectivity Connectivity
- 273. Installation [page 273] Configuration [page 311] Operations [page 502] Security [page 556] Upgrade [page 567] Update the Java VM [page 569] Uninstallation [page 570] Frequently Asked Questions [page 571] 1.2.1 Installation Choose a procedure to install the Cloud Connector on your operating system. Portable Version vs. Installer Version On Microsoft Windows and Linux, two installation modes are available: a portable version and an installer version. On Mac OS X, only the portable version is available. ● Portable version: can be installed easily, by extracting a compressed archive into an empty directory. It does not require administrator or root privileges for the installation, and you can run multiple instances on the same host. Restrictions: ○ You cannot run it in the background as a Windows Service or Linux daemon (with automatic start capabilities at boot time). ○ The portable version does not support an automatic upgrade procedure. To update a portable installation, you must delete the current one, extract the new version, and then re-do the configuration. ○ Portable versions are meant for non-productive scenarios only. ○ The environment variable JAVA_HOME is relevant when starting the instance, and therefore must be set properly. ● Installer version: requires administrator or root permissions for the installation and can be set up to run as a Windows service or Linux daemon in the background. You can upgrade it easily, retaining all the configuration and customizing. Note We strongly recommend that you use this variant for a productive setup. SAP BTP Connectivity Connectivity PUBLIC 273
- 274. Prerequisites ● There are some general prerequisites you must fulfill to successfully install the Cloud Connector, see Prerequisites [page 274]. ● For OS-specific requirements and procedures, see section Tasks below. Tasks ● Installation on Microsoft Windows OS [page 292] ● Installation on Linux OS [page 295] ● Installation on Mac OS X [page 298] Related Information Sizing Recommendations [page 286] Recommendations for Secure Setup [page 299] [Deprecated] Replace the Default SSL Certificate [page 306] Uninstallation [page 570] 1.2.1.1 Prerequisites Prerequisites for successful installation of the Cloud Connector. Content Section Description Connectivity Restrictions [page 275] General information about SAP BTP and connectivity restric tions. Hardware [page 275] Hardware prerequisites for a physical or virtual machine. Software [page 275] Required software download and installation. JDKs [page 276] Java Development Kit (JDK) versions that you can use. Product Availability Matrix [page 276] Availability of operating systems/versions for specific Cloud Connector versions. 274 PUBLIC SAP BTP Connectivity Connectivity
- 275. Section Description Network [page 277] Required Internet connection to SAP BTP hosts per region. Note For additional system requirements, see also System Requirements [page 284]. Connectivity Restrictions For general information about SAP BTP restrictions, see Prerequisites and Restrictions. For specific information about all Connectivity restrictions, see Connectivity: Restrictions [page 5]. Back to Content [page 274] Hardware Hardware prerequisites, physical or virtual machine: Minimum Recommended CPU Single core 3 GHz, x86-64 architecture compatible Dual core 2 GHz, x86-64 architecture compatible Memory (RAM) 2 GB 4 GB Free disk space 3 GB 20 GB Back to Content [page 274] Software ● You have downloaded the Cloud Connector installation archive from SAP Development Tools for Eclipse. ● A JDK 8 must be installed. You can download an up-to-date SAP JVM from SAP Development Tools for Eclipse as well. Caution Do not use Apache Portable Runtime (APR) on the system on which you use the Cloud Connector. If you cannot avoid this restriction and want to use APR at your own risk, you must manually adopt the server.xml configuration file in directory <scc_installation_folder>/conf. To do so, follow the steps in HTTPS port configuration for APR. SAP BTP Connectivity Connectivity PUBLIC 275
- 276. Back to Content [page 274] JDKs JDK Version Cloud Connector Version SAP JVM 64-bit (recommended) 7 2.x up to 2.12.2 8 2.7.2 and higher Oracle JDK 64-bit 7 2.x up to 2.12.2 8 2.7.2 and higher Note The support for using Cloud Connector with Java runtime version 7 ended on December 31, 2019. Any Cloud Connector version released after that date may contain Java byte code requiring at least a JVM 8. We therefore strongly recommend that you perform fresh installations only with Java 8, and update existing installations running with Java 7, to Java 8. See SAP Cloud Connector – Java 7 support will phase out and Update the Java VM [page 569]. Back to Content [page 274] Product Availability Matrix Operating System Version Architecture Cloud Connector Version Windows 7, Windows Server 2008 R2 x86_64 2.x SUSE Linux Enterprise Server 11, Red hat Enterprise Linux 6 x86_64 2.x Mac OS X 10.7 (Lion), Mac OS X 10.8 (Mountain Lion) x86_64 2.x Windows 8.1, Windows Server 2012, Windows Server 2012 R2 x86_64 2.5.1 and higher SUSE Linux Enterprise Server 12, Red hat Enterprise Linux 7 x86_64 2.5.1 and higher Mac OS X 10.9 (Mavericks), Mac OS X 10.10 (Yosemite) x86_64 2.5.1 and higher Windows 10 x86_64 2.7.2 and higher Mac OS X 10.11 (El Capitan) x86_64 2.8.1 and higher 276 PUBLIC SAP BTP Connectivity Connectivity
- 277. Operating System Version Architecture Cloud Connector Version Windows Server 2016 x86_64 2.9.1 and higher Windows Server 2019, Mac OS X 10.12 (Sierra), Mac OS X 10.13 (High Sierra), Mac OS X 10.14 (Mojave) x86_64 2.11.3 and higher SUSE Linux Enterprise Server 15 x86_64 2.12.0 and higher Redhat Enterprise Linux 8 x86_64 2.12.2 and higher SUSE Linux Enterprise Server 12, SUSE Linux Enterprise Server 15, Redhat En terprise Linux 7, Redhat Enterprise Li nux 8 ppc64le 2.13.0 and higher Back to Content [page 274] Network You must have Internet connection at least to the following Connectivity service hosts (depending on the region), to which you can connect your Cloud Connector. All connections to the hosts are TLS-based and connect to port 443. Note For general information on IP ranges per region, see Regions (Cloud Foundry and ABAP environment) or Regions and Hosts Available for the Neo Environment. Find detailed information about the region status and planned network updates on http:/ /sapcp.statuspage.io/ . Cloud Foundry Environment [page 277] ABAP Environment [page 280] Neo Environment [page 280] Trial [page 282] Region (Region Host) Hosts IP Address Cloud Foundry Environment Note In the Cloud Foundry environment, IPs are controlled by the respective IaaS provider - Amazon Web Services (AWS), Microsoft Azure (Azure), or Google Cloud Platform (GCP). IPs may change due to network updates on the provider side. Any planned changes will be announced at least 4 weeks before they take effect. See also Regions. SAP BTP Connectivity Connectivity PUBLIC 277
- 278. Region (Region Host) Hosts IP Address Europe (Frankfurt) - AWS (cf.eu10.hana.ondema nd.com) connectivitynotification.cf.eu10.hana.ondemand.com 3.124.222.77, 3.122.209.241, 3.124.208.223 connectivitycertsigning.cf.eu10.hana.ondemand.com 3.124.222.77, 3.122.209.241, 3.124.208.223 connectivitytunnel.cf.eu10.hana.ondemand.com 3.124.222.77, 3.122.209.241, 3.124.208.223 Europe (Netherleands) - Azure (cf.eu20.hana.ondema nd.com) connectivitynotification.cf.eu20.hana.ondemand.com 40.119.153.88 connectivitycertsigning.cf.eu20.hana.ondemand.com 40.119.153.88 connectivitytunnel.cf.eu20.hana.ondemand.com 40.119.153.88 US East (VA) - AWS (cf.us10.hana.ondema nd.com) connectivitynotification.cf.us10.hana.ondemand.com 52.23.189.23, 52.4.101.240, 52.23.1.211 connectivitycertsigning.cf.us10.hana.ondemand.com 52.23.189.23, 52.4.101.240, 52.23.1.211 connectivitytunnel.cf.us10.hana.ondemand.com 52.23.189.23, 52.4.101.240, 52.23.1.211 US West (WA) - Azure (cf.us20.hana.ondema nd.com) connectivitynotification.cf.us20.hana.ondemand.com 40.91.120.100 connectivitycertsigning.cf.us20.hana.ondemand.com 40.91.120.100 connectivitytunnel.cf.us20.hana.ondemand.com 40.91.120.100 US East (VA) - Azure (cf.us21.hana.ondema nd.com) connectivitynotification.cf.us21.hana.ondemand.com 40.88.52.17 connectivitycertsigning.cf.us21.hana.ondemand.com 40.88.52.17 connectivitytunnel.cf.us21.hana.ondemand.com 40.88.52.17 US Central (IA) - GCP (cf.us30.hana.ondema nd.com) connectivitynotification.cf.us30.hana.ondemand.com 35.184.169.79 connectivitycertsigning.cf.us30.hana.ondemand.com 35.184.169.79 connectivitytunnel.cf.us30.hana.ondemand.com 35.184.169.79 Brazil (São Paulo) - AWS (cf.br10.hana.ondema nd.com) connectivitynotification.cf.br10.hana.ondemand.com 18.229.91.150, 52.67.135.4 connectivitycertsigning.cf.br10.hana.ondemand.com 18.229.91.150, 52.67.135.4 connectivitytunnel.cf.br10.hana.ondemand.com 18.229.91.150, 52.67.135.4 278 PUBLIC SAP BTP Connectivity Connectivity
- 279. Region (Region Host) Hosts IP Address Japan (Tokyo) - AWS (cf.jp10.hana.ondema nd.com) connectivitynotification.cf.jp10.hana.ondemand.com 13.114.117.83, 3.114.248.68, 3.113.252.15 connectivitycertsigning.cf.jp10.hana.ondemand.com 13.114.117.83, 3.114.248.68, 3.113.252.15 connectivitytunnel.cf.jp10.hana.ondemand.com 13.114.117.83, 3.114.248.68, 3.113.252.15 Japan (Tokyo) - Azure (cf.jp20.hana.ondema nd.com) connectivitynotification.cf.jp20.hana.ondemand.com 20.43.89.91 connectivitycertsigning.cf.jp20.hana.ondemand.com 20.43.89.91 connectivitytunnel.cf.jp20.hana.ondemand.com 20.43.89.91 Australia (Sidney) - AWS (cf.ap10.hana.ondema nd.com) connectivitynotification.cf.ap10.hana.ondemand.com 13.236.220.84, 13.211.73.244, 3.105.95.184 connectivitycertsigning.cf.ap10.hana.ondemand.com 13.236.220.84, 13.211.73.244, 3.105.95.184 connectivitytunnel.cf.ap10.hana.ondemand.com 13.236.220.84, 13.211.73.244, 3.105.95.184 Singapore - AWS (cf.ap11.hana.ondema nd.com) connectivitynotification.cf.ap11.hana.ondemand.com 3.0.9.102, 18.140.39.70, 18.139.147.53 connectivitycertsigning.cf.ap11.hana.ondemand.com 3.0.9.102, 18.140.39.70, 18.139.147.53 connectivitytunnel.cf.ap11.hana.ondemand.com 3.0.9.102, 18.140.39.70, 18.139.147.53 Singapore - Azure (cf.ap21.hana.ondema nd.com) connectivitynotification.cf.ap21.hana.ondemand.com 20.184.61.122 connectivitycertsigning.cf.ap21.hana.ondemand.com 20.184.61.122 connectivitytunnel.cf.ap21.hana.ondemand.com 20.184.61.122 Canada (Montreal) - AWS (cf.ca10.hana.ondema nd.com) connectivitynotification.cf.ca10.hana.ondemand.com 35.182.75.101, 35.183.74.34 connectivitycertsigning.cf.ca10.hana.ondemand.com 35.182.75.101, 35.183.74.34 connectivitytunnel.cf.ca10.hana.ondemand.com 35.182.75.101, 35.183.74.34 SAP BTP Connectivity Connectivity PUBLIC 279
- 280. Region (Region Host) Hosts IP Address China (Shanghai) - Alibaba Cloud (cf.cn40.platform.sa pcloud.cn) connectivitynotification.cf.cn40.platform.sapcloud.cn 139.224.7.71 connectivitycertsigning.cf.cn40.platform.sapcloud.cn 139.224.7.71 connectivitytunnel.cf.cn40.platform.sapcloud.cn 139.224.7.71 Back to Network [page 277] Back to Content [page 274] Region (Region Host) Hosts IP Address ABAP Environment Note For scenarios using the ABAP environment, include the IPs of the corresponding region below in your firewall rules, in addition to the IPs listed for the same region above (Cloud Foundry environment), if you use IP-based firewall rules. Europe (Frankfurt) - AWS *.abap.eu10.hana.ondemand.com 18.185.129.45, 52.29.97.247 US East (VA) - AWS *.abap.us10.hana.ondemand.com 52.4.22.116, 52.1.251.254 Japan (Tokyo) - AWS *.abap.jp10.hana.ondemand.com 18.177.215.21, 3.115.146.41 Back to Network [page 277] Back to Content [page 274] Region (Region Host) Hosts IP Address Neo Environment Europe (Rot) (hana.ondemand.com) connectivitynotification.hana.ondemand.com 155.56.210.83 connectivitycertsigning.hana.ondemand.com 155.56.210.43 connectivitytunnel.hana.ondemand.com 155.56.210.84 Europe (Frankfurt) (eu2.hana.ondemand.c om) connectivitynotification.eu2.hana.ondemand.com 157.133.206.143 connectivitycertsigning.eu2.hana.ondemand.com 157.133.205.174 connectivitytunnel.eu2.hana.ondemand.com 157.133.205.233 Europe (Amsterdam) (eu3.hana.ondemand.c om) connectivitynotification.eu3.hana.ondemand.com 157.133.141.140 connectivitycertsigning.eu3.hana.ondemand.com 157.133.141.132 connectivitytunnel.eu3.hana.ondemand.com 157.133.141.141 United States East (Ashburn) connectivitynotification.us1.hana.ondemand.com Old: 65.221.12.40 New: 157.133.18.120 280 PUBLIC SAP BTP Connectivity Connectivity
- 281. Region (Region Host) Hosts IP Address (us1.hana.ondemand.c om) Note Due to a network update, IP addresses for this re gion change as of May 24, 2020. Please make sure to include also the new IP addresses in your firewall rules if you use IP-based firewall rules. connectivitycertsigning.us1.hana.ondemand.com Old: 65.221.12.241 New: 157.133.18.101 connectivitytunnel.us1.hana.ondemand.com Old: 65.221.12.41 New: 157.133.18.121 United States West (Chan dler) (us2.hana.ondemand.c om) Note Due to a network update, IP addresses for this re gion change as of June 14, 2020. Please make sure to include also the new IP addresses in your firewall rules if you use IP-based firewall rules. connectivitynotification.us2.hana.ondemand.com Old: 64.95.110.215 New: 157.133.26.25 connectivitycertsigning.us2.hana.ondemand.com Old: 64.95.110.211 New: 157.133.26.20 connectivitytunnel.us2.hana.ondemand.com Old: 64.95.110.214 New: 157.133.26.24 United States East (Sterling) (us3.hana.ondemand.c om) connectivitynotification.us3.hana.ondemand.com 169.145.118.140 connectivitycertsigning.us3.hana.ondemand.com 169.145.118.132 connectivitytunnel.us3.hana.ondemand.com 169.145.118.141 US States West (Colorado Springs) (us4.hana.ondemand.c om ) connectivitynotification.us4.hana.ondemand.com 157.133.45.140 connectivitycertsigning.us4.hana.ondemand.com 157.133.45.132 connectivitytunnel.us4.hana.ondemand.com 157.133.45.141 Australia (Sydney) (ap1.hana.ondemand.c om) connectivitynotification.ap1.hana.ondemand.com 157.133.97.47 connectivitycertsigning.ap1.hana.ondemand.com 157.133.97.27 connectivitytunnel.ap1.hana.ondemand.com 157.133.97.46 China (Shanghai) connectivitynotification.cn1.platform.sapcloud.cn 157.133.194.81 connectivitycertsigning.cn1.platform.sapcloud.cn 157.133.194.77 SAP BTP Connectivity Connectivity PUBLIC 281
- 282. Region (Region Host) Hosts IP Address (cn1.platform.sapclo ud.cn) connectivitytunnel.cn1.platform.sapcloud.cn 157.133.194.82 Japan (Tokyo) (jp1.hana.ondemand.c om) connectivitynotification.jp1.hana.ondemand.com 157.133.150.140 connectivitycertsigning.jp1.hana.ondemand.com 157.133.150.132 connectivitytunnel.jp1.hana.ondemand.com 157.133.150.141 Canada (Toronto) (ca1.hana.ondemand.c om) connectivitynotification.ca1.hana.ondemand.com 157.133.54.140 connectivitycertsigning.ca1.hana.ondemand.com 157.133.54.132 connectivitytunnel.ca1.hana.ondemand.com 157.133.54.141 Russia (Moscow) (ru1.hana.ondemand.c om) connectivitynotification.ru1.hana.ondemand.com 157.133.2.140 connectivitycertsigning.ru1.hana.ondemand.com 157.133.2.132 connectivitytunnel.ru1.hana.ondemand.com 157.133.2.141 Brazil (São Paulo) (br1.hana.ondemand.c om) connectivitynotification.br1.hana.ondemand.com 157.133.246.140 connectivitycertsigning.br1.hana.ondemand.com 157.133.246.132 connectivitytunnel.br1.hana.ondemand.com 157.133.246.141 UAE (Dubai) (ae1.hana.ondemand.c om) connectivitynotification.ae1.hana.ondemand.com 157.133.85.140 connectivitycertsigning.ae1.hana.ondemand.com 157.133.85.132 connectivitytunnel.ae1.hana.ondemand.com 157.133.85.141 KSA (Riyadh) (sa1.hana.ondemand.c om) connectivitynotification.sa1.hana.ondemand.com 157.133.93.140 connectivitycertsigning.sa1.hana.ondemand.com 157.133.93.132 connectivitytunnel.sa1.hana.ondemand.com 157.133.93.141 Back to Network [page 277] Back to Content [page 274] Region (Region Host) Hosts IP Address Trial (Cloud Foundry Environment) Note In the Cloud Foundry environment, IPs are controlled by the respective IaaS provider (AWS, Azure, or GCP). IPs may change due to network updates on the provider side. Any planned changes will be announced several weeks before they take effect. See also Regions. Europe (Frankfurt) - AWS (cf.eu10.hana.ondema nd.com) connectivitynotification.cf.eu10.hana.ondemand.com 3.124.222.77, 3.122.209.241, 3.124.208.223 connectivitycertsigning.cf.eu10.hana.ondemand.com 3.124.222.77, 3.122.209.241, 3.124.208.223 282 PUBLIC SAP BTP Connectivity Connectivity
- 283. Region (Region Host) Hosts IP Address connectivitytunnel.cf.eu10.hana.ondemand.com 3.124.222.77, 3.122.209.241, 3.124.208.223 Europe (Netherleands) - Azure (cf.eu20.hana.ondema nd.com) connectivitynotification.cf.eu20.hana.ondemand.com 40.119.153.88 connectivitycertsigning.cf.eu20.hana.ondemand.com 40.119.153.88 connectivitytunnel.cf.eu20.hana.ondemand.com 40.119.153.88 United States East (VA) - AWS (cf.us10.hana.ondema nd.com) connectivitynotification.cf.us10.hana.ondemand.com 52.23.189.23, 52.4.101.240, 52.23.1.211 connectivitycertsigning.cf.us10.hana.ondemand.com 52.23.189.23, 52.4.101.240, 52.23.1.211 connectivitytunnel.cf.us10.hana.ondemand.com 52.23.189.23, 52.4.101.240, 52.23.1.211 US Central (IA) - GCP (cf.us30.hana.ondema nd.com) connectivitynotification.cf.us30.hana.ondemand.com 35.184.169.79 connectivitycertsigning.cf.us30.hana.ondemand.com 35.184.169.79 connectivitytunnel.cf.us30.hana.ondemand.com 35.184.169.79 Trial (Neo Environment) Trial (Europe only) (hanatrial.ondemand. com) connectivitynotification.hanatrial.ondemand.com 155.56.219.26 connectivitycertsigning.hanatrial.ondemand.com 155.56.219.22 connectivitytunnel.hanatrial.ondemand.com 155.56.219.27 Back to Network [page 277] Back to Content [page 274] Note If you install the Cloud Connector in a network segment that is isolated from the backend systems, make sure the exposed hosts and ports are still reachable and open them in the firewall that protects them: ● for HTTP, the ports you chose for the HTTP/S server. ● for LDAP, the port of the LDAP server. ● for RFC, it depends on whether you use an SAProuter or not and whether load balancing is used: ○ if you use an SAProuter, it is typically configured as visible in the network of the Cloud Connector and the corresponding routtab is exposing all the systems that should be used. ○ without SAProuter, you must open the application server hosts and the corresponding gateway ports (33##, 48##). When using load balancing for the connection, you must also open the message server host and port. See also Network Zones [page 285]. SAP BTP Connectivity Connectivity PUBLIC 283
- 284. For more information about the used ABAP server ports, see: Ports of SAP NetWeaver Application Server ABAP. Back to Network [page 277] Back to Content [page 274] Related Information Installation on Microsoft Windows OS [page 292] Installation on Linux OS [page 295] Installation on Mac OS X [page 298] Recommendations for Secure Setup [page 299] Sizing Recommendations [page 286] 1.2.1.1.1 System Requirements Additional system requirements for installing and running the Cloud Connector. Supported Browsers The browsers you can use for the Cloud Connector Administration UI are the same as those currently supported by SAPUI5. See: Browser and Platform Support. Minimum Disk Space for Download and Installation The minimum free disk space required to download and install a new Cloud Connector server is as follows: ● Size of downloaded Cloud Connector installation file (ZIP, TAR, MSI files): 50 MB ● Newly installed Cloud Connector server: 70 MB ● Total: 120 MB as a minimum Additional Disk Space for Log and Configuration Files The Cloud Connector writes configuration files, audit log files and trace files at runtime. We recommend that you reserve between 1 and 20 GB of disk space for those files. 284 PUBLIC SAP BTP Connectivity Connectivity
- 285. Trace and log files are written to <scc_dir>/log/ within the Cloud Connector root directory. The ljs_trace.log file contains traces in general, communication payload traces are stored in traffic_trace_*.trc. These files may be used by SAP Support to analyze potential issues. The default trace level is Information, where the amount of written data is generally only a few KB per day. You can turn off these traces to save disk space. However, we recommend that you don't turn off this trace completely, but that you leave it at the default settings, to allow root cause analysis if an issue occurs. If you set the trace level to All, the amount of data can easily reach the range of several GB per day. Use trace level All only to analyze a specific issue. Payload trace, however, should normally be turned off, and used only for analysis by SAP Support. Note Regularly back up or delete written trace files to clean up the used disk space. Audit log files are written to /log/audit/<subaccount-name>/audit-log_<subaccount- name>_<date>.csv within the Cloud Connector root directory. By default, only security-related events are written in the audit log. You can change the audit log level using the administration UI, as described in Manage Audit Logs [page 545]. To be compliant with the regulatory requirements of your organization and the regional laws, the audit log files must be persisted for a certain period of time for traceability purposes. Therefore, we recommend that you back up the audit log files regularly from the Cloud Connector file system and keep the backup for the length of time required. Related Information Prerequisites [page 274] 1.2.1.1.2 Network Zones Choose a network zone for your Cloud Connector installation. A customer network is usually divided into multiple network zones or subnetworks according to the security level of the contained components. For example, the DMZ that contains and exposes the external-facing services of an organization to an untrusted network, usually the Internet, and there are one or more other network zones which contain the components and services provided in the company’s intranet. You can generally choose the network zone in which to set up the Cloud Connector: ● Internet access to the SAP BTP region host, either directly or via HTTPS proxy. ● Direct access to the internal systems it provides access to, which means that there is transparent connectivity between the Cloud Connector and the internal system. The Cloud Connector can be set up either in the DMZ and operated centrally by the IT department, or set up in the intranet and operated by the appropriate line of business. SAP BTP Connectivity Connectivity PUBLIC 285
- 286. Note The internal network must allow access to the required ports; the specific configuration depends on the firewall software used. The default ports are 80 for HTTP and 443 for HTTPS. For RFC communication, you need to open a gateway port (default: 33+<instance number> and an arbitrary message server port. For a connection to a HANA Database (on SAP BTP) via JDBC, you need to open an arbitrary outbound port in your network. Mail (SMTP) communication is not supported. 1.2.1.2 Sizing Recommendations When installing a Cloud Connector, the first thing you need to decide is the sizing of the installation. This section gives some basic guidance what to consider for this decision. The provided information includes the shadow instance, which should always be added in productive setups. See also Install a Failover Instance for High Availability [page 508]. Note The following recommendations are based on current experiences. However, they are only a rule of thumb since the actual performance strongly depends on the specific environment. The overall performance of a Cloud Connector is impacted by many factors (number of hosted subaccounts, bandwidth, latency to the attached regions, network routers in the corporate network, used JVM, and others). Restrictions The sizing data refer to a single Cloud Connector installation. Note Up until now, you cannot perform horizontal scaling directly. However, you can distribute the load statically by operating multiple Cloud Connector installations with different location IDs for all involved subaccounts. In this scenario, you can use multiple destinations with virtually the same configuration, except for the location ID. See also Managing Subaccounts [page 328], step 4. Alternatively, each of the Cloud Connector instances can host its own list of subaccounts without any overlap in the respective lists. Thus, you can handle more load, if a single installation risks to be overloaded. Related Information Hardware Setup [page 287] Configuration Setup [page 290] 286 PUBLIC SAP BTP Connectivity Connectivity
- 287. 1.2.1.2.1 Hardware Setup How to choose the right sizing for your Cloud Connector installation. Regarding the hardware, we recommend that you use different setups for master and shadow. One dedicated machine should be used for the master, another one for the shadow. Usually, a shadow instance takes over the master role only temporarily. During most of its lifetime, in the shadow state, it needs less resources compared to the master. If the master instance is available again after a downtime, we recommend that you switch back to the actual master. Note The sizing recommendations refer to the overall load across all subaccounts that are connected via the Cloud Connector. This means that you need to accumulate the expected load of all subaccounts and should not only calculate separately per subaccount (taking the one with the highest load as basis). Related Information Sizing for the Master Instance [page 287] Sizing for the Shadow Instance [page 289] 1.2.1.2.1.1 Sizing for the Master Instance Learn more about the basic criteria for the sizing of your Cloud Connector master instance. For the master setup, keep in mind the expected load for communication between the SAP BTP and on- premise systems. The setups listed below differ in a mostly qualitative manner, without hard limits for each of them. Note The mentioned sizes are considered as minimal configuration, larger ones are always ok. In general, the more applications, application instances, and subaccounts are connected, the more competition will exist for the limited resources on the machine. SAP BTP Connectivity Connectivity PUBLIC 287
- 288. Installation Size (S, M, L) CPU (x86_64) Machine Memory / Heap / Direct Memory Disk Space S: The expected load is small (up to 1 million requests per day, request concurrency and size is in average low) and only a few subaccounts with some applications are connected. In addition, only a few serv ice channels are used, only small data amount is repli cated to cloud systems. Setup can be a done in a vir tual or physical machine. 2 cores 2.6 GHz 4GB RAM / 1GB / 2GB 10GB M : The expected load is medium (up to 10 million requests per day, request concurrency and size is in average me dium) and multiple subac counts with multiple appli cations are connected. In addition, many service channels are used, and a medium data amount is re plicated to cloud systems. We recommend that you do the setup in a virtual or phys ical machine. A virtual ma chine should be on a host without overcommitted re sources. 4 cores 3.0 Ghz 16GB RAM / 4GB / 8GB 20GB 288 PUBLIC SAP BTP Connectivity Connectivity
- 289. Installation Size (S, M, L) CPU (x86_64) Machine Memory / Heap / Direct Memory Disk Space L: The expected load is large (more than 10 million re quests per day, request con currency and size is in aver age medium or high) and multiple subaccounts with multiple applications are connected. In addition, many service channels are used, and a large data amount is repli cated to cloud systems con currently. We recommend that you do the setup in a virtual or phys ical machine. A virtual ma chine should be on a host without overcommitted re sources. 8 cores 3.0 Ghz 32GB RAM / 8GB / 16GB 40GB Particularly the heap size is critical. If you size it too low for the load passing the Cloud Connector, at some point the Java Virtual Machine will execute full GCs (garbage collections) more frequently, blocking the processing of the Cloud Connector completely for multiple seconds, which massively slows down overall performance. If you experience such situations regularly, you should increase the heap size in the Cloud Connector UI (choose Configuration Advanced JVM ). See also Configure the Java VM [page 497]. Note You should use the same value for both <initial heap size> and <maximum heap size>. 1.2.1.2.1.2 Sizing for the Shadow Instance Learn more about the basic criteria for the sizing of your Cloud Connector shadow instance (high availability mode). The shadow installation is typically not used in standard situations and hence does not need the same sizing, assuming that the time span in which it takes over the master role is limited. Note The shadow only acts as master, for example, during an upgrade or when an abnormal situation occurs on the master machine, and either the Cloud Connector or the full machine on OS level needs to be restarted. SAP BTP Connectivity Connectivity PUBLIC 289
- 290. While being in the shadow state, the resource consumption is very low, especially in productive environments, where typically only few configuration changes are required. Therefore, the machine sizing can usually be smaller than the one for the master. However, if you want to mitigate the risk of a longer outage of the master machine, you should increase the sizing of the shadow up to the master size: Master Shadow S S installation as virtual machine M S installation (with double memory) as virtual or physical machine M installation as virtual or physical machine for risk mitiga tion L M installation as virtual or physical machine L installation as virtual or physical machine for risk mitiga tion 1.2.1.2.2 Configuration Setup Choose the right connection configuration options to improve the performance of the Cloud Connector. This section provides detailed information how you can adjust the configuration to improve overall performance. This is typically relevant for an M or L installation (see Hardware Setup [page 287]). For S installations, the default configuration will probably be sufficient to handle the traffic. To change the connection parameters, proceed as follows: ● As of Cloud Connector 2.11, you can configure the number of physical connections through the Cloud Connector UI. See also Configure Tunnel Connections [page 496]. ● In versions prior to 2.11, you have to modify the configuration files with an editor and restart the Cloud Connector to activate the changes. In general, the Cloud Connector tunnel is multiplexing multiple virtual connections over a single physical connection. Thus, a single connection can handle a considerable amount of traffic. However, increasing the maximum number of physical connections allows you to make use of the full available bandwidth and to minimize latency effects. If the bandwidth limit of your network is reached, adding additional connections doesn't increase the througput, but will only consume more resources. Note Different network access parameters may impact and limit your configuration options: if the access to an external network is a 1 MB line with an added latency of 50 ms, you will not be able to achieve the same data volumes like with a 10 GB line with an added latency of < 1 ms. However, even if the line is good, for example 10 GB, but with an added latency of 100 ms, the performance might still be bad. 290 PUBLIC SAP BTP Connectivity Connectivity
- 291. Optimal configuration strongly depends on your actual scenarios. A good approach is to try out different settings, if the current performance does not meet your expectations. Related Information On-Demand To On-Premise Connections [page 291] On-Premise To On-Demand Connections (Service Channels) [page 292] 1.2.1.2.2.1 On-Demand To On-Premise Connections Configure the physical connections for on-demand to on-premise calls in the Cloud Connector. Adjusting the number of physical connections for this direction is possible both globally in the Cloud Connector UI ( Configuration Advanced ), and for individual communication partners on cloud side ( On-Demand To On-Premise Applications ). Connections are established for each defined and connected subaccount. The current number of opened connections is visible in the Cloud Connector UI via <Subaccount> Cloud Connections . The global default is 1 physical connection per connected subaccount. This value is used across all subaccounts hosted by the Cloud Connector instance and applies for all communication partners. In general, the default should be sufficient for applications with low traffic. If you expect medium traffic for most applications, it may be useful to set the default value to 2. Note An exact traffic forecast is difficult to achieve. It requires a deep understanding of the use case and of the possible future load generated by different applications. For this reason, we recommend that you focus on subsequent configuration adjustments, using the Cloud Connector monitoring tools to recognize bottlenecks in time, and adjust Cloud Connector configuration accordingly. Tunnel Worker Threads In addition to the number of connections, you can configure the number of <Tunnel Worker Threads>. This value should be at least equal to the maximum of all individual application tunnel connections in all subaccounts, to have at least 1 thread available for each connection that can process incoming requests and outgoing responses. SAP BTP Connectivity Connectivity PUBLIC 291
- 292. Protocol Processor Worker Threads The value for <Protocol Processor Worker Threads> is mainly relevant if RFC is used as protocol. Since its communication model towards the ABAP system is a blocking one, each thread can handle only one call at a time and cannot be shared. Hence, you should provide 1 thread per 5 concurrent RFC requests. Note The longer the RFC execution time in the backend, the more threads you should provide. Threads can be reused only after the response of a call was returned to SAP BTP. 1.2.1.2.2.2 On-Premise To On-Demand Connections (Service Channels) Configure the number of physical connections for a Cloud Connector service channel. Service channels let you configure the number of physical connections to the communication partner on cloud side, see Using Service Channels [page 482]. The default is 1. This value is used as well in versions prior to Cloud Connector 2.11, which did not offer a configuration option for each service channel. You should define the number of connections depending on the expected number of clients and, with lower priority, depending on the size of the exchanged messages. If there is only a single RFC client for an S/4HANA Cloud channel or only a single HANA client for a HANA DB on SAP BTP side, increasing the number doesn't help, as each virtual connection is assigned to one physical connection. The following simple rule lets you to define the required number of connections per service channel: ● Per 10 concurrent clients, use one physical connection. ● If the transferred net data size is larger than 500k per request, make sure to add an additional connection per 2 of such clients. Example For a HANA system in the SAP BTP, data is replicated using 18 concurrent clients in the on-premise network. In average, about 5 of those clients are regularly sending 600k. For the number of clients, you should use 2 physical connections, for the 5 clients sending larger amounts add an additional 3, which sums up to 5 connections. 1.2.1.3 Installation on Microsoft Windows OS Installing the Cloud Connector on a Microsoft Windows operating system. 292 PUBLIC SAP BTP Connectivity Connectivity
- 293. Context You can choose between a simple portable variant of the Cloud Connector and the MSI-based installer. The installer is the generally recommended version that you can use for both developer and productive scenarios. It lets you, for example, register the Cloud Connector as a Windows service and this way automatically start it after machine reboot. Tip If you are a developer, you might want to use the portable variant as you can run the Cloud Connector after a simple unzip (archive extraction). You might want to use it also if you cannot perform a full installation due to lack of permissions, or if you want to use multiple versions of the Cloud Connector simultaneously on the same machine. Prerequisites ● You have either of the following 64-bit operating systems: Windows 7, Windows 8.1, Windows 10, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server 2016, or Windows Server 2019. ● You have downloaded either the portable variant as ZIP archive for Windows, or the MSI installer from the SAP Development Tools for Eclipse page. ● You must install Microsoft Visual Studio C++ 2013 runtime libraries (vcredist_x64.exe). For more information, see Visual C++ Redistributable Packages for Visual Studio 2013 . Note Even if you have a more recent version of the Microsoft Visual C++ runtime libraries, you still must install the Microsoft Visual Studio C++ 2013 libraries. ● Java 8 must be installed. In case you want to use SAP JVM, you can download it from the SAP Development Tools for Eclipse page. ● When using the portable variant, the environment variable <JAVA_HOME> must be set to the Java installation directory, so that the bin subdirectory can be found. Alternatively, you can add the relevant bin subdirectory to the <PATH> variable. Portable Scenario 1. Extract the <sapcc-<version>-windows-x64.zip> ZIP file to an arbitrary directory on your local file system. 2. Set the environment variable JAVA_HOME to the installation directory of the JDK that you want to use to run the Cloud Connector. Alternatively, you can add the bin subdirectory of the JDK installation directory to the PATH environment variable. SAP BTP Connectivity Connectivity PUBLIC 293
- 294. 3. Go to the Cloud Connector installation directory and start it using the go.bat batch file. 4. Continue with the Next Steps section. Note The Cloud Connector is not started as a service when using the portable variant, and hence will not automatically start after a reboot of your system. Also, the portable version does not support the automatic upgrade procedure. Installer Scenario 1. Start the <sapcc-<version>-windows-x64.msi> installer by double-clicking it. 2. The installer informs you that you are now guided through the installation process. Choose Next>. 3. Navigate to the desired installation directory for your Cloud Connector and choose Next>. When doing the installation in the context of an upgrade, make sure you choose the previous installation directory again. 4. You can choose the port on which the administration UI is reachable. Either leave the default 8443 or choose a different port if needed. Then, choose Next>. 5. Select the JDK to be used for running the Cloud Connector. The installer displays a list of all usable JDKs that are installed on your machine. If the needed JDK is not listed in the drop-down box (for example, if it's an SAP JVM that is not registered in the Windows registry upon installation), you can browse to its installation directory and select it. We recommend that you use an up-to-date Java 8 installation to run the Cloud Connector. 6. Decide whether the Cloud Connector should be started immediately after finishing the setup. Then, choose Next>. 7. To start the installation, press the Next> button again. 8. After successful installation, choose Close. 9. Continue with the Next Steps section. Note The Cloud Connector is started as a Windows service in the productive use case. Therefore, installation requires administration permissions. After installation, manage this service under Control Panel Administrative Tools Services . The service name is Cloud Connector (formerly named Cloud Connector 2.0). Make sure the service is executed with a user that has limited privileges. Typically, privileges allowed for service users are defined by your company policy. Adjust the folder and file permissions to be manageable by only this user and system administrators. On Windows, the file scc_service.log is created and used by the Microsoft MSI installer (during Cloud Connector installation), and by the scchost.exe executable, which registers and runs the Windows service if you install the Cloud Connector as a Windows background job. This log file is only needed if a problem occurs during Cloud Connector installation, or during creation and start of the Windows service, in which the Cloud Connector is running. You can find the file in the log folder of your Cloud Connector installation directory. 294 PUBLIC SAP BTP Connectivity Connectivity
- 295. Starting the Cloud Connector After installation, the Cloud Connector is registered as a Windows service that is configured to be started automatically after a system reboot. You can start and stop the service via shortcuts on the desktop ("Start Cloud Connector" and "Stop Cloud Connector"), or by using the Windows Services manager and look for the service SAP Cloud Connector. Access the Cloud Connector administration UI at https:/ /localhost:<port>, where the default port is 8443 (but this port might have been modified during the installation). Next Steps 1. Open a browser and enter: https://<hostname>:8443. <hostname> is the host name of the machine on which you have installed the Cloud Connector. If you access the Cloud Connector locally from the same machine, you can simply enter localhost. 2. Continue with the initial configuration of the Cloud Connector, see Initial Configuration [page 312]. Related Information (Optional) Install SAP JVM Recommendations for Secure Setup [page 299] [Deprecated] Replace the Default SSL Certificate [page 306] 1.2.1.4 Installation on Linux OS Installing the Cloud Connector on a Linux operating system. Context You can choose between a simple portable variant of the Cloud Connector and the RPM-based installer. The installer is the generally recommended version that you can use for both the developer and the productive scenario. It registers, for example, the Cloud Connector as a daemon service and this way automatically starts it after machine reboot. Tip If you are a developer, you might want to use the portable variant as you can run the Cloud Connector after a simple "tar -xzof" execution. You also might want to use it if you cannot perform a full installation SAP BTP Connectivity Connectivity PUBLIC 295
- 296. due to missing permissions for the operating system, or if you want to use multiple versions of the Cloud Connector simultaneously on the same machine. Prerequisites ● You have either of the following 64-bit operating systems: SUSE Linux Enterprise Server 11, 12, or 15, or Redhat Enterprise Linux 6, 7, or 8. ● The supported platforms are x64 and ppc64le, represented below by the variable <platform>. Variable <arch> is x86_64 or ppc64le respectively. ● You have downloaded either the portable variant as tar.gz archive for Linux or the RPM installer contained in the ZIP for Linux, from SAP Development Tools for Eclipse. ● Java 8 must be installed. If you want to use SAP JVM, you can download an up-to-date version from SAP Development Tools for Eclipse as well. Use the following command to install it: rpm -i sapjvm-<version>-linux-<platform>.rpm If you want to check the JVM version installed on your system, use the following command: rpm -qa | grep jvm When installing it using the RPM package, the Cloud Connector will detect it and use it for its runtime. ● When using the tar.gz archive, the environment variable <JAVA_HOME> must be set to the Java installation directory, so that the bin subdirectory can be found. Alternatively, you can add the Java installation's bin subdirectory to the <PATH> variable. Portable Scenario 1. Extract the tar.gz file to an arbitrary directory on your local file system using the following command: tar -xzof sapcc-<version>-linux-<platform>.tar.gz Note If you use the parameter "o", the extracted files are assigned to the user ID and the group ID of the user who has unpacked the archive. This is the default behavior for users other than the root user. 2. Go to this directory and start the Cloud Connector using the go.sh script. 3. Continue with the Next Steps section. Note In this case, the Cloud Connector is not started as a daemon, and therefore will not automatically start after a reboot of your system. Also, the portable version does not support the automatic upgrade procedure. 296 PUBLIC SAP BTP Connectivity Connectivity
- 297. Installer Scenario 1. Extract the sapcc-<version>-linux-<platform>.zip archive to an arbitrary directory by using the following the command: unzip sapcc-<version>-linux-<platform>.zip 2. Go to this directory and install the extracted RPM using the following command. You can perform this step only as a root user. rpm -i com.sap.scc-ui-<version>.<arch>.rpm 3. Continue with the Next Steps section. In the productive case, the Cloud Connector is started as a daemon. If you need to manage the daemon process, execute: System V init distributions: service scc_daemon stop|restart|start|status systemd distributions: systemctl stop|restart|start|status scc_daemon Caution When adjusting the Cloud Connector installation (for example, restoring a backup), make sure the RPM package management is synchronized with such changes. If you simply replace files that do not fit to the information stored in the package management, lifecycle operations (such as upgrade or uninstallation) might fail with errors. Also, the Cloud Connector might get into unrecoverable state. Example: After a file system restore, the system files represent Cloud Connector 2.3.0 but the RPM package management "believes" that version 2.4.3 is installed. In this case, commands like rpm -U and rpm -e do not work as expected. Furthermore, avoid using the --force parameter as it may lead to an unpredictable state with two versions being installed concurrently, which is not supported. Extending the Daemon (as of Cloud Connector version 2.12.3) When using SNC for encrypting RFC communication, it might be required to provide some settings, for example, environment variables that must be visible for the Cloud Connector process. To achieve this, you must store a file named scc_daemon_extension.sh in the installation directory of the Cloud Connector (/opt/sap/scc), containing all commands needed for initialization without a shebang. Example (SAP CommonCryptoLibrary requires SECUDIR to be set): Sample Code export SECUDIR=/path/to/psefile To activate it, you must reinstall the daemon. Make sure JAVA_HOME is set to the JVM used. Then execute the following command to reinstall the daemon: System V init distributions: /opt/sap/scc/daemon.sh reinstall systemd distributions: /opt/sap/scc/daemon.sh reinstallSystemd The daemon extension will survive Cloud Connector version updates. SAP BTP Connectivity Connectivity PUBLIC 297
- 298. Starting the Cloud Connector After installation via RPM manager, the Cloud Connector process is started automatically and registered as a daemon process, which ensures the automatic restart of the Cloud Connector after a system reboot. To start, stop, or restart the process explicitly, open a command shell and use the following commands, which require root permissions: System V init distributions: service scc_daemon start|stop|restart systemd distributions: systemctl start|stop|restart scc_daemon Next Steps 1. Open a browser and enter: https://<hostname>:8443. <hostname> is the host name of the machine on which you installed the Cloud Connector. If you access the Cloud Connector locally from the same machine, you can simply enter localhost. 2. Continue with the initial configuration of the Cloud Connector, see Initial Configuration [page 312]. Related Information Recommendations for Secure Setup [page 299] [Deprecated] Replace the Default SSL Certificate [page 306] 1.2.1.5 Installation on Mac OS X Installing the Cloud Connector on a Mac OS X operating system. Prerequisites Note Mac OS X is not supported for productive scenarios. The developer version described below must not be used as productive version. ● You have either of the following 64-bit operating systems: Mac OS X 10.7 (Lion), Mac OS X 10.8 (Mountain Lion), Mac OS X 10.9 (Mavericks), Mac OS X 10.10 (Yosemite), or Mac OS X 10.11 (El Capitan), Mac OS X 10.12 (Sierra), Mac OS X 10.13 (High Sierra), or Mac OS X 10.14 (Mojave). ● You have downloaded the tar.gz archive for the developer use case on Mac OS X from SAP Development Tools for Eclipse. 298 PUBLIC SAP BTP Connectivity Connectivity
- 299. ● Java 8 must be installed. If you want to use SAP JVM, you can download it from SAP Development Tools for Eclipse as well. ● Environment variable <JAVA_HOME> must be set to the Java installation directory so that the bin subdirectory can be found. Alternatively, you can add the Java installation's bin subdirectory to the <PATH> variable. Procedure 1. Extract the tar.gz file to an arbitrary directory on your local file system using the following command: tar -xzof sapcc-<version>-macosx-x64.tar.gz 2. Go to this directory and start Cloud Connector using the go.sh script. 3. Continue with the Next Steps section. Note The Cloud connector is not started as a daemon, and therefore will not automatically start after a reboot of your system. Also, the Mac OS X version of Cloud Connector does not support the automatic upgrade procedure. Next Steps 1. Open a browser and enter: https://<hostname>:8443. <hostname> is the host name of the machine on which you installed the Cloud Connector. If you access the Cloud Connector locally from the same machine, you can simply enter localhost. 2. Continue with the initial configuration of the Cloud Connector, see Initial Configuration [page 312]. Related Information Recommendations for Secure Setup [page 299] [Deprecated] Replace the Default SSL Certificate [page 306] 1.2.1.6 Recommendations for Secure Setup For the Connectivity service and the Cloud Connector, you should apply the following guidelines to guarantee the highest level of security for these components. SAP BTP Connectivity Connectivity PUBLIC 299
- 300. Security Status From the Connector menu, choose Security Status to access an overview showing potential security risks and the recommended actions. The General Security Status addresses security topics that are subaccount-independent. ● Choose any of the Actions icons in the corresponding line to navigate to the UI area that deals with that particular topic and view or edit details. Note Navigation is not possible for the last item in the list (Service User). ● The service user is specific to the Windows operating system (see Installation on Microsoft Windows OS [page 292] for details) and is only visible when running the Cloud Connector on Windows. It cannot be accessed or edited through the UI. If the service user was set up properly, choose Edit and check the corresponding checkbox. The Subaccount-Specific Security Status lists security-related information for each and every subaccount. Note The security status only serves as a reminder to address security issues and shows if your installation complies with all recommended security settings. 300 PUBLIC SAP BTP Connectivity Connectivity
- 301. Password Policy Upon installation, the Cloud Connector provides an initial user name and password for the administration UI, and forces the user (Administrator) to change the password. You must change the password immediately after installation. The connector itself does not check the strength of the password. You should select a strong password that cannot be guessed easily. Note To enforce your company's password policy, we recommend that you configure the Administration UI to use an LDAP server for authorizing access to the UI. UI Access The Cloud Connector administration UI can be accessed remotely via HTTPS. The connector uses a standard X.509 self-signed certificate as SSL server certificate. You can exchange this certificate with a specific certificate that is trusted by your company. See [Deprecated] Replace the Default SSL Certificate [page 306]. Note Since browsers usually do not resolve localhost to the host name whereas the certificate usually is created under the host name, you might get a certificate warning. In this case, simply skip the warning message. OS-Level Access The Cloud Connector is a security-critical component that handles the external access to systems of an isolated network, comparable to a reverse proxy. We therefore recommend that you restrict the access to the operating system on which the Cloud Connector is installed to the minimal set of users who would administrate the Cloud Connector. This minimizes the risk of unauthorized users getting access to credentials, such as certificates stored in the secure storage of the Cloud Connector. We also recommend that you use the machine to operate only the Cloud Connector and no other systems. Administrator Privileges To log on to the Cloud Connector administration UI, the Administrator user of the connector must not have an operating system (OS) user for the machine on which the connector is running. This allows the OS administrator to be distinguished from the Cloud Connector administrator. To make an initial connection between the connector and a particular SAP BTP subaccount, you need an SAP BTP user with the required permissions for the related subaccount. We recommend that you separate these roles/duties (that means, you have separate users for Cloud Connector administrator and SAP BTP). SAP BTP Connectivity Connectivity PUBLIC 301
- 302. Note We recommend that only a small number of users are granted access to the machine as root users. Hard Drive Encryption Hard drive encryption for machines with a Cloud Connector installation ensures that the Cloud Connector configuration data cannot be read by unauthorized users, even if they obtain access to the hard drive. Supported Protocols Currently, the protocols HTTP and RFC are supported for connections between the SAP BTP and on-premise systems when the Cloud Connector and the Connectivity service are used. The whole route from the application virtual machine in the cloud to the Cloud Connector is always SSL-encrypted. The route from the connector to the back-end system can be SSL-encrypted or SNC-encrypted. See Configure Access Control (HTTP) [page 370] and Configure Access Control (RFC) [page 377]. Audit Log on OS Level We recommend that you turn on the audit log on operating system level to monitor the file operations. Audit Log on Cloud Connector Level The Cloud Connector audit log must remain switched on during the time it is used with productive systems. The default audit level is SECURITY. Set it to ALL if required by your company policy. The administrators who are responsible for a running Cloud Connector must ensure that the audit log files are properly archived, to conform to the local regulations. You should switch on audit logging also in the connected back-end systems. Encryption Ciphers By default, all available encryption ciphers are supported for HTTPS connections to the administration UI. However, some of them may not conform to your security standards and therefore should be excluded: 1. From the main menu, choose Configuration and select the tab User Interface, section Cipher Suites. By default, all available ciphers are marked as selected. 2. Choose the Remove icon to unselect the ciphers that do not meet your security requirements. 302 PUBLIC SAP BTP Connectivity Connectivity
- 303. Note We recommend that you revert the selection to the default (all ciphers selected) whenever you plan to switch to another JVM. As the set of supported ciphers may differ, the selected ciphers may not be supported by the new JVM. In that case the Cloud Connector does not start anymore. You need to fix the issue manually by adapting the file default-server.xml (cp. attribute ciphers, see section Accessing the Cloud Connector Administrator UI above). After switching the JVM, you can adjust the list of eligible ciphers. 3. Choose Save. Related Information Connectivity via Reverse Proxy [page 579] Security [page 556] 1.2.1.7 Recommended: Exchange UI Certificates in the Administration UI By default, the Cloud Connector includes a self-signed UI certificate. It is used to encrypt the communication between the browser-based user interface and the Cloud Connector itself. For security reasons, however, you SAP BTP Connectivity Connectivity PUBLIC 303
- 304. should replace this certificate with your own one to let the browser accept the certificate without security warnings. Procedure Master Instance 1. From the main menu, choose Configuration and go to the User Interface tab. 2. In the UI Certificate section, start a certificate signing request procedure by choosing the icon Generate a Certificate Signing Request. 3. In the pop-up Generate CSR, specify a subject fitting to your host name. For host matching, you should use the available names within the subjectAlternativeName (SAN) extension, see RFC 2818 . A check verifies whether the host matches one of the entries in the SAN extension. Choose either of the procedures below, according to your Cloud Connector version: 1. Procedure up to Cloud Connector version 2.12.0 The field <SAN> allows a simple value as well as formatted complex values: ○ A simple value is treated as DNS name, for example, xyz.sap.com means that the allowed host is xyz.sap.com. ○ <SAN> also allows a list of DNS names, IPs (4 byte or IPv6), URIs, and RFC 822 names (for example, e-mail addresses). Note In this case, the field <SAN> contains key:value pairs separated by ';'. ';' must not be used in a value. Example for a complex SAN value : DNS:localhost;DNS:*.sap.com;IP: 10.20.30.40;IP:fe80::78cc:a107:dcf2:73fe%13. 2. Procedure as of Cloud Connector version 2.12.1 304 PUBLIC SAP BTP Connectivity Connectivity
- 305. This new version simplifies the SAN mamagement. The CSR generation dialog now separates SAN values from the Subject DN of the certificate by introducing two sections. In the new section Subject Alternative Names, you can add additional values easily by pressing the Add button. Choose one or more of the following SAN types and provide the matching values: ○ DNS: a specific host name (for example, www.sap.com) or a wildcard hostname (for example, *.sap.com). ○ IP: an IPv4 or IPv6 address. ○ RFC822 : an example for this type of value is a simple email address: for example, [email protected]. ○ URI: a URI for which the certificate should be valid. 4. Press Generate. 5. You are prompted to save the signing request in a file. The content of the file is the signing request in PEM format. The signing request must be provided to a Certificate Authority (CA) - either one within your company or another one you trust. The CA signs the request and the returned response should be stored in a file. SAP BTP Connectivity Connectivity PUBLIC 305
- 306. Note The response should be either an X.509 certificate or a PKCS#7 in PEM format. 6. To import the signing response, choose the Upload icon. As of Cloud Connector version 2.13, you can also upload an existing PKCS#12 certificate directly (instead of generating a CSR). 7. Select Browse to locate the file and then choose the Import button. 8. Review the certificate details that are displayed. 9. Restart the Cloud Connector to activate the new certificate. Shadow Instance In a High Availability setup, perform the same operation on the shadow instance. 1.2.1.7.1 [Deprecated] Replace the Default SSL Certificate Note This procedure only applies for Cloud Connector versions prior to 2.13. You can now use the UI-based procedure instead, see Recommended: Exchange UI Certificates in the Administration UI [page 303]. 306 PUBLIC SAP BTP Connectivity Connectivity
- 307. Overview By default, the Cloud Connector includes a self-signed UI certificate. It is used to encrypt the communication between the browser-based user interface and the Cloud Connector itself. For security reasons, however, you should replace this certificate with your own certificate so that the browser accepts the certificate without security warnings. Up to version 2.5.2, for this purpose, you need to know the password of the Cloud Connector's Java keystore. This password is generated during installation and then kept in an encrypted secure storage area. To obtain the password, follow the steps described below. Note As of version 2.6.0, you can easily replace the default certificate within the Cloud Connector administration UI . See Recommended: Exchange UI Certificates in the Administration UI [page 303]. Caution The Cloud Connector's keystore may contain a certificate used in the High Availability setup. This certificate has the alias "ha". Any changes on it or removal would cause a disruption of communication between the shadow and the master instance, and therefore to a failed procedure. We recommend that you replace the keystore on both the master and shadow server before establishing the connection between the two instances. Procedure You can read the password by executing the following command: ● on Microsoft Windows OS: java -cp <scc_install_dir>pluginscom.sap.scc.rt*.jar - Djava.library.path=<scc_install_dir>auditor com.sap.scc.jni.SecStoreAccess - path <scc_install_dir>scc_config -p ● on Linux OS: java -cp /opt/sap/scc/plugins/com.sap.scc.rt*.jar - Djava.library.path=/opt/sap/scc/auditor com.sap.scc.jni.SecStoreAccess - path /opt/sap/scc/scc_config -p Note Memorize the keystore password, as you will need it for later operations. See related links. Make sure you go to directory /opt/sap/scc/config before executing the commands described in the following procedures. Note For a detailed description of the keytool tool, see http:/ /docs.oracle.com/javase/7/docs/technotes/tools/ solaris/keytool.html . SAP BTP Connectivity Connectivity PUBLIC 307
- 308. Related Information Recommended: Exchange UI Certificates in the Administration UI [page 303] [Deprecated] Use a Self-Signed Certificate [page 308] [Deprecated] Use Certificates Signed by a Trusted Certificate Authority [page 309] 1.2.1.7.2 [Deprecated] Use a Self-Signed Certificate Generate a self-signed certificate for special purposes like, for example, a demo setup. Context Note As of Cloud Connector 2.10 you can generate self-signed certificates also from the administration UI. See Configure a CA Certificate for Principal Propagation [page 344] and Initial Configuration (HTTP) [page 319]. In this case, the steps below are not required. If you want to use a simple, self-signed certificate, follow the procedure below. Note The parameter values in the following section are examples. The server configuration delivered by SAP uses the same password for key store (option -storepass) and key (option -keypass) under alias tomcat. Procedure 1. Remove the current default certificate: keytool -delete -alias tomcat -keystore ks.store -storepass <password> 2. Generate a certificate: keytool -genkey -v -keyalg RSA -alias tomcat -keypass <password> -keystore ks.store -storepass <password> -dname "CN=SCC, OU=<YourCompany>, O=<YourCompany>" 3. Self-sign it - you will be prompted for the keypass password defined in step 2: keytool -selfcert -v -alias tomcat -storepass <password> -keystore ks.store 308 PUBLIC SAP BTP Connectivity Connectivity
- 309. 1.2.1.7.3 [Deprecated] Use Certificates Signed by a Trusted Certificate Authority Use a signed certificate by a trusted certificate authority (CA) to increase the security level when running the Cloud Connector. Note This procedure only applies for Cloud Connector versions prior to 2.13. You can now use the UI-based procedure instead, see Recommended: Exchange UI Certificates in the Administration UI [page 303]. Before starting the procedure, note the following: ● The parameter values of the following steps are only examples. ● We recommend that you use a signed certificate by a trusted CA, because it is more secure than a self- signed certificate. ● For your convenience, you can set the generated password as environment variable, like in the command below, and then use $PASS as a password: export PASS=`<the release-dependent command as given in the parent page>` ● The keytool supports delete and changealias commands. If the Cloud Connector SSL certificate is changed on a running instance, we recommend that you prepare a new certificate under a temporary alias. Once everything is ready, you change the alias. Procedure Note If you already have a signed certificate produced by a trusted certificate authority (CA), skip steps 1,2, and 4, and only follow the instructions provided in step 3. 1. Generate your key pair if you start fresh: keytool -genkey -v -keyalg RSA -alias tomcat -keypass <password> -keystore ks.store -storepass <password> -dname "CN=SCC, OU=<YourCompany>, O=<YourCompany>" Alternatively, you may reuse an existing key store. 2. Create a local certificate signing request (CSR): keytool -certreq -keyalg RSA -alias tomcat -keypass <password> -keystore ks.store -storepass <password> -file <csr-file-name> You now have a file called <csr-file-name> that you can submit to the certificate authority. In return, you get a certificate. 3. Import the certificate chain that you obtained from your trusted CA: keytool -import -alias root -keystore ks.store -storepass <password> - trustcacerts -file <filename_of_the_certificate_chain> SAP BTP Connectivity Connectivity PUBLIC 309
- 310. Note If you already have a signed certificate produced by a trusted certificate authority (CA), continue with the following steps (skipping 1,2, and 4): ○ Create a backup copy of the keystore file ks.store. ○ Import your keystore with option -importkeystore (documented here ) into the Cloud Connector keystore ks.store. keytool -importkeystore -srckeystore mypfxfile.pfx -srcstoretype pkcs12 -destkeystore ks.store -deststoretype JKS -srcstorepass <your_pw> - deststorepass <pw_from_sec_store> – srcalias <your_alias> -destalias tomcat -srckeypass <your_pw> -destkeypass <pw_from_sec_store> 4. Import your new certificate: keytool -import -alias tomcat -keystore ks.store -storepass <password> -file <your_certificate_filename> The password is created at installation time and stored in the secure storage. Thus, only applications with access can read the password. You can read password using Java: jar -xf /opt/sap/scc/dropins/scc/plugins/com.sap.scc.tomcat.utils*.jar lib/ libsapsecstore4j.so java -cp /opt/sap/scc/dropins/scc/plugins/com.sap.scc.tomcat.utils*.jar - Djava.library.path=./lib/ com.sap.mw.scc.util.SecStoreAccess -show You might need to adapt the configuration if you want to use another key storage file or change the current configuration (HTTPS port, authentication type, SSL protocol, and so on). You can find the SSL configuration in the Connector section of the file: ● Microsoft Windows OS: <install_dir>config_masterorg.eclipse.gemini.web.tomcat default-server.xml ● Linux OS: /opt/sap/scc/config_master/org.eclipse.gemini.web.tomcat/default- server.xml Note We recommend that you do not modify the configuration unless you have expertise in this area. <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="config/ks.store" keystorePass="${jks.password}" keyPass="$ {jks.password}" keyAlias="tomcat" truststoreFile="config/ks.store" truststorePass="${jks.password}" clientAuth="want" sslProtocol="TLS" compression="on" compressionMinSize="1024" noCompressionUserAgents="gozilla,traviata,*MSIE 6.*" compressableMimeType="text/html,text/xml,text/plain,text/javascript,text/ css,text/json,application/x-javascript,application/javascript,application/json"/> 310 PUBLIC SAP BTP Connectivity Connectivity
- 311. Related Information For more information about configuring SSL, see http:/ /tomcat.apache.org/tomcat-7.0-doc/ssl- howto.html#SSL_and_Tomcat . 1.2.2 Configuration Configure the Cloud Connector to make it operational for connections between your SAP BTP applications and on-premise systems. Topic Description Initial Configuration [page 312] After installing the Cloud Connector and starting the Cloud Connector daemon, you can log on and perform the required configuration to make your Cloud Connector operational. Managing Subaccounts [page 328] How to connect SAP BTP subaccounts to your Cloud Connector. Authenticating Users against On-Premise Systems [page 339] Basic authentication and principal propagation (user propa gation) are the authentication types currently supported by the Cloud Connector. Configure Access Control [page 369] Configure access control or copy the complete access con trol settings from another subaccount on the same Cloud Connector. Configuration REST APIs [page 394] Configure a newly installed Cloud Connector (initial configu- ration, subaccounts, access control) using the configuration REST API. Configure an On-Premise User Store [page 480] Configure applications running on SAP BTP to use your cor porate LDAP server as a user store. Using Service Channels [page 482] Service channels provide access from an external network to certain services on SAP BTP, which are not exposed to direct access from the Internet. Configure Trust [page 490] Set up an allowlist for trusted cloud applications and a trust store for on-premise systems in the Cloud Connector. Connect DB Tools to SAP HANA via Service Channels [page 486] How to connect database, BI, or replication tools running in the on-premise network to a HANA database on SAP BTP using the service channels of the Cloud Connector. Configure Domain Mappings for Cookies [page 493] Map virtual and internal domains to ensure correct handling of cookies in client/server communication. Configure Solution Management Integration [page 494] Activate Solution Management reporting in the Cloud Connector. Configure Tunnel Connections [page 496] Adapt connectivity settings that control the throughput by choosing the appropriate limits (maximal values). Configure the Java VM [page 497] Adapt the JVM settings that control memory management. SAP BTP Connectivity Connectivity PUBLIC 311
- 312. Topic Description Configuration Backup [page 498] Backup and restore your Cloud Connector configuration. 1.2.2.1 Initial Configuration After installing and starting the Cloud Connector, log on to the administration UI and perform the required configuration to make your Cloud Connector operational. Tasks Prerequisites [page 312] Log on to the Cloud Connector [page 313] Change your Password and Choose Installation Type [page 314] Set up Connection Parameters and HTTPS Proxy [page 315] Establish Connections to SAP BTP [page 318] Prerequisites ● You have assigned one of these roles/role collections to the subaccount user that you use for initial Cloud Connector setup, depending on the SAP BTP environment in which your subaccount is running: Note For the Cloud Foundry environment, you must know on which cloud management tools feature set (A or B) your account is running. For more information on feature sets, see Cloud Management Tools — Feature Set Overview. Environment Required Roles/Role Collections More Information Cloud Foundry [feature set A] The user must be a member of the global account that the subaccount belongs to. Alternatively, you can assign the user as Security Administrator. Add Members to Your Global Account Managing Security Administrators in Your Subaccount [Feature Set A] 312 PUBLIC SAP BTP Connectivity Connectivity
- 313. Environment Required Roles/Role Collections More Information Cloud Foundry [feature set B] Assign at least one of these default role collections (all of them including the role Cloud Connector Administrator): ○ Subaccount Administrator ○ Cloud Connector Administrator ○ Connectivity and Destination Administrator Alternatively, you can assign a custom role collection to the user that in cludes the role Cloud Connector Administrator. Default Role Collections [Feature Set B] [page 13] Role Collections and Roles in Global Accounts and Subaccounts [Feature Set B] Neo Assign at least one of these default roles: ○ Cloud Connector Admin ○ Administrator Alternatively, you can assign a custom role to the user that includes the per mission manageSCCTunnels. Managing Member Authorizations in the Neo Environment After establishing the Cloud Connector connection, this user is not needed any more, since it serves only for initial connection setup. You may revoke the corresponding role assignment then and remove the user from the Members list. Note If the Cloud Connector is installed in an environment that is operated by SAP, SAP provides a user that you can add as member in your SAP BTP subaccount and assign the required role. ● We strongly recommend that you read and follow the steps described in Recommendations for Secure Setup [page 299]. For operating the Cloud Connector securely, see also Security Guidelines [page 563]. Back toTasks [page 312] Log on to the Cloud Connector To administer the Cloud Connector, you need a Web browser. To check the list of supported browsers, see Prerequisites and Restrictions → section Browser Support. 1. In a Web browser, enter: https://<hostname>:<port> SAP BTP Connectivity Connectivity PUBLIC 313
- 314. ○ <hostname> refers to the machine on which the Cloud Connector is installed. If installed on your machine, you can simply enter localhost. ○ <port> is the Cloud Connector port specified during installation (the default port is 8443). 2. On the logon screen, enter Administrator / manage (case sensitive) for <User Name> / <Password>. Back toTasks [page 312] Change your Password and Choose Installation Type 1. When you first log in, you must change the password before you continue, regardless of the installation type you have chosen. 2. Choose between master and shadow installation. Use Master if you are installing a single Cloud Connector instance or a main instance from a pair of Cloud Connector instances. See Install a Failover Instance for High Availability [page 508]. 3. You can edit the password for the Administrator user from Configuration in the main menu, tab User Interface, section Authentication: Note User name and password cannot be changed at the same time. If you want to change the user name, you must enter only the current password in a first step. Do not enter values for <New Password> or <Repeat New Password> when changing the user name. To change the password in second step, enter the old password, the new one, and the repeated (new) password, but leave the user name unchanged. 314 PUBLIC SAP BTP Connectivity Connectivity
- 315. Back toTasks [page 312] Set up Connection Parameters and HTTPS Proxy When logging in for the first time, the following screen is displayed every time you choose an option from the main menu that requires a configured subaccount: If your internal landscape is protected by a firewall that blocks any outgoing TCP traffic, you must specify an HTTPS proxy that the Cloud Connector can use to connect to SAP BTP. Normally, you must use the same proxy settings as those being used by your standard Web browser. The Cloud Connector needs this proxy for two operations: ● Download the correct connection configuration corresponding to your subaccount ID in SAP BTP. ● Establish the SSL tunnel connection from the Cloud Connector user to your SAP BTP subaccount. Note If you want to skip the initial configuration, you can click the icon in the upper right corner. You might need this in case of connectivity issues shown in your logs. You can add subaccounts later as described in Managing Subaccounts [page 328]. The Cloud Connector collects the following required information for your subaccount connection: 1. For <Region>, specify the SAP BTP region that should be used. You can choose it from the drop-down list, see Regions. Note You can also configure a region yourself, if it is not part of the standard list. Either insert the region host manually, or create a custom region, as described in Configure Custom Regions [page 339]. SAP BTP Connectivity Connectivity PUBLIC 315
- 316. 2. For <Subaccount>, <Subaccount User> and <Password>, enter the values you obtained when you registered your subaccount on SAP BTP. Note For a subaccount in the Cloud Foundry environment, you must enter the subaccount ID as <Subaccount>, rather than its actual (technical) name. For information on getting the subaccount ID, see Find Your Subaccount ID (Cloud Foundry Environment) [page 338]. As <Subaccount User> you must provide your Login E-mail instead of a user ID. The user must be a member of the global account the subaccount belongs to. You can also add a new subaccount user with the role Cloud Connector Admin in the SAP BTP cockpit and use the new user and password. For the Neo environment, see Add Members to Your Neo Subaccount. For the Cloud Foundry environment, see Add Org Members Using the Cockpit. Tip When using SAP Cloud Identity Services - Identity Authentication (IAS) as platform identity provider with two-factor authentication for your subaccount, you can simply append the required token to the regular password. Tip For a subaccount in the Cloud Foundry environment, the Cloud Connector supports the use of a custom identity provider (IDP) via single sign-on (SSO) passcode. For more information, see Use a Custom IDP for Subaccount Configuration [page 324]. 3. (Optional) You can define a <Display Name> that lets you easily recognize a specific subaccount in the UI compared to the technical subaccount name. 4. (Optional) You can define a <Location ID> identifying the location of this Cloud Connector for a specific subaccount. As of Cloud Connector release 2.9.0, the location ID is used as routing information and therefore you can connect multiple Cloud Connectors to a single subaccount. If you don't specify any value for <Location ID>, the default is used, which represents the behavior of previous Cloud Connector versions. The location ID must be unique per subaccount and should be an identifier that can be used in a URI. To route requests to a Cloud Connector with a location ID, the location ID must be configured in the respective destinations. Note Location IDs provided in older versions of the Cloud Connector are discarded during upgrade to ensure compatibility for existing scenarios. 5. Enter a suitable proxy host from your network and the port that is specified for this proxy. If your network requires an authentication for the proxy, enter a corresponding proxy user and password. You must specify a proxy server that supports SSL communication (a standard HTTP proxy does not suffice). Note These settings strongly depend on your specific network setup. If you need more detailed information, please contact your local system administrator. 316 PUBLIC SAP BTP Connectivity Connectivity
- 317. 6. (Optional) You can provide a <Description> (free-text) of the subaccount that is shown when choosing the Details icon in the Actions column of the Subaccount Dashboard. It lets you identify the particular Cloud Connector you use. 7. Choose Save. The Cloud Connector now starts a handshake with SAP BTP and attempts to establish a secure SSL tunnel to the server that hosts the subaccount in which your on-demand applications are running. However, no requests are yet allowed to pass from the cloud side to any of your internal back-end systems. To allow your on-demand applications to access specific internal back-end systems, proceed with the access configuration described in the next section. Note The internal network must allow access to the port. Specific configuration for opening the respective port(s) depends on the firewall software used. The default ports are 80 for HTTP and 443 for HTTPS. For RFC communication, you must open a gateway port (default: 33+<instance number> and an arbitrary message server port. For a connection to a HANA Database (on SAP BTP) via JDBC, you must open an arbitrary outbound port in your network. Mail (SMTP) communication is not supported. ● If you later want to change your proxy settings (for example, because the company firewall rules have changed), choose Configuration from the main menu and go to the Cloud tab, section HTTPS Proxy. Some proxy servers require credentials for authentication. In this case, you must provide the relevant user/ password information. ● If you want to change the description for your Cloud Connector, choose Configuration from the main menu, go to the Cloud tab, section Connector Info and edit the description: SAP BTP Connectivity Connectivity PUBLIC 317
- 318. Back toTasks [page 312] Establish Connections to SAP BTP As soon as the initial setup is complete, the tunnel to the cloud endpoint is open, but no requests are allowed to pass until you have performed the Access Control setup, see Configure Access Control [page 369]. To manually close (and reopen) the connection to SAP BTP, choose your subaccount from the main menu and select the Disconnect button (or the Connect button to reconnect to SAP BTP). ● The green icon next to Region Host indicates that it is valid and can be reached. ● If an HTTPS Proxy is configured, its availability is shown the same way. In the screenshot, the grey diamond icon next to HTTPS Proxy indicates that connectivity is possible without proxy configuration. In case of a timeout or a connectivity issue, these icons are yellow (warning) or red (error), and a tooltip shows the cause of the problem. Initiated By refers to the user that has originally established the tunnel. During normal operations, this user is no longer needed. Instead, a certificate is used to open the connection to a subaccount. ● The status of the certificate is shown next to Subaccount Certificate. It is shown as valid (green icon), if the expiration date is still far in the future, and turns to yellow if expiration approaches according to your alert settings. It turns red as soon as it has expired. This is the latest point in time, when you should Update the Certificate for Your Subaccount [page 335]. 318 PUBLIC SAP BTP Connectivity Connectivity
- 319. Note When connected, you can monitor the Cloud Connector also in the Connectivity section of the SAP BTP cockpit. There, you can track attributes like version, description and high availability set up. Every Cloud Connector configured for your subaccount automatically appears in the Connectivity section of the cockpit. Back toTasks [page 312] Related Information Managing Subaccounts [page 328] Initial Configuration (HTTP) [page 319] Initial Configuration (RFC) [page 321] Configuring the Cloud Connector for LDAP [page 323] Managing Member Authorizations in the Neo Environment Use a Custom IDP for Subaccount Configuration [page 324] 1.2.2.1.1 Initial Configuration (HTTP) Configure the Cloud Connector for HTTP communication. Installation of a System Certificate for Mutual Authentication To set up a mutual authentication between the Cloud Connector and any backend system it connects to, you can import an X.509 client certificate into the Cloud Connector. The Cloud Connector then uses the so-called system certificate for all HTTPS requests to backends that request or require a client certificate. The CA that signed the Cloud Connector's client certificate must be trusted by all backend systems to which the Cloud Connector is supposed to connect. You must provide the system certificate as PKCS#12 file containing the client certificate, the corresponding private key and the CA root certificate that signed the client certificate (plus potentially the certificates of any intermediate CAs, if the certificate chain is longer than 2). Procedure From the left panel, choose Configuration. On the tab On Premise, choose System Certificate Import a certificate to upload a certificate and provide its password: SAP BTP Connectivity Connectivity PUBLIC 319
- 320. A second option is to start a certificate signing request procedure as described for the UI certificate in Recommended: Exchange UI Certificates in the Administration UI [page 303] and upload the resulting signed certificate. As of version 2.10, there is a third option - generating a self-signed certificate. It might be useful if no CA is needed, for example, in a demo setup or if you want to use a dedicated CA. For this option, choose Create and import a self-signed certificate: 320 PUBLIC SAP BTP Connectivity Connectivity
- 321. If a system certificate has been imported successfully, its distinguished name, the name of the issuer, and the validity dates are displayed: If a system certificate is no longer required, you can delete it. To do this, use the respective button and confirm deletion. If you need the public key for establishing trust with a server, you can simply export the full chain via the Export button. Related Information Configure Access Control (HTTP) [page 370] 1.2.2.1.2 Initial Configuration (RFC) Configure a Secure Network Connection (SNC) to set up the Cloud Connector for RFC communication to an ABAP backend system. SAP BTP Connectivity Connectivity PUBLIC 321
- 322. SNC Configuration for Mutual Authentication To set up a mutual authentication between Cloud Connector and an ABAP backend system (connected via RFC), you can configure SNC for the Cloud Connector. It will then use the associated PSE for all RFC SNC requests. This means that the SNC identity, represented by this PSE, must: ● Be trusted by all backend systems to which the Cloud Connector is supposed to connect ● Play the role of a trusted external system by adding the SNC name of the Cloud Connector to the SNCSYSACL table. You can find more details in the SNC configuration documentation for the release of your ABAP system. Prerequisites You have configured your ABAP system(s) for SNC. For detailed information on configuring SNC for an ABAP system, see also Configuring SNC on AS ABAP. In order to establish trust for Principal Propagation, follow the steps described in Configure Principal Propagation for RFC [page 354]. Configuration Steps 1. Logon to the Cloud Connector 2. Choose Configuration from the main menu and go to tab On Premise, section SNC. 3. Enter the corresponding values in the fields Library Name, My Name, and Quality of Protection 4. Press Save. Example: ○ Library Name: Provides the location of the SNC library you are using for the Cloud Connector. Note Bear in mind that you must use one and the same security product on both sides of the communication. 322 PUBLIC SAP BTP Connectivity Connectivity
- 323. ○ My Name: The SNC name that identifies the Cloud Connector. It represents a valid scheme for the SNC implementation that is used. ○ Quality of Protection: Determines the level of protection that you require for the connectivity to the ABAP systems. Note When using CommonCryptoLibrary as SNC implementation, note 1525059 will help you to configure the PSE to be associated with the user running the Cloud Connector process. Related Information Configure Principal Propagation for RFC [page 354] 1.2.2.1.3 Configuring the Cloud Connector for LDAP Configure the Cloud Connector to support LDAP in different scenarios (cloud applications using LDAP or Cloud Connector authentication). Prerequisites You have installed the Cloud Connector and done the basic configuration: Installation [page 273] Initial Configuration [page 312] Steps When using LDAP-based user management, you have to confgure the Cloud Connector to support this feature. Depending on the scenario, you need to perform the following steps: Scenario 1: Cloud applications using LDAP for authentication. Configure the destination of the LDAP server in the Cloud Connector: Configure Access Control (LDAP) [page 383]. Scenario 2: Internal Cloud Connector user management. Activate LDAP user management in the Cloud Connector: Use LDAP for Authentication [page 503]. SAP BTP Connectivity Connectivity PUBLIC 323
- 324. 1.2.2.1.4 Use a Custom IDP for Subaccount Configuration Enable custom identity provider (IDP) authentication to configure a Cloud Foundry subaccount in the Cloud Connector by using a one-time passcode. Content Context [page 324] Get the URL [Feature Set A] [page 327] Get the URL [Feature Set B] [page 328] Get the One-Time Passcode [page 328] Context For a subaccount in the Cloud Foundry environment that uses a custom IDP, you can choose this IDP for authentication instead of the (default) SAP ID service when configuring the subaccount in the Cloud Connector. Using custom IDP authentication, you can perform the following operations in the Cloud Connector: Operation Description Set up Connection Parameters and HTTPS Proxy [page 315] Add an initial subaccount to a fresh Cloud Connector instal lation. Managing Subaccounts [page 328] Add additonal subaccounts to an existing Cloud Connector installation. Update the Certificate for a Subaccount [page 335] Refresh a subaccount certificate's validity period. To enable custom IDP authentication, for each of these operations you must enter the marker value $SAP-CP- SSO-PASSCODE$ in the <Subaccount User> or <User Name> field, and a one-time generated passcode (known as temporary authentication code) in the <Password> field: ● When adding the initial subaccount to a fresh Cloud Connector installation, enter the user name $SAP- CP-SSO-PASSCODE$ and the passcode on the Cloud Connector's Define Subaccount screen (see also Set up Connection Parameters and HTTPS Proxy [page 315]): 324 PUBLIC SAP BTP Connectivity Connectivity
- 325. ● When adding one ore more additonal subaccount(s) to an existing Cloud Connector installation, provide the user name $SAP-CP-SSO-PASSCODE$ and the passcode via the Connector screen (see also Managing Subaccounts [page 328]): SAP BTP Connectivity Connectivity PUBLIC 325
- 326. ● To refresh a subaccount certificate, enter the user name $SAP-CP-SSO-PASSCODE$ and the passcode via the corresponding <Subaccount> screen (see also Update the Certificate for a Subaccount [page 335]): To retrieve the one-time generated passcode, you must use the correct login URL for single sign-on (SSO) to access your custom IDP. The procedure to get this URL depends on the SAP BTP feature set you are using. Note To choose the right procedure, you must know on which cloud management tools feature set (A or B) your SAP BTP account is running. For more information on feature sets, see Cloud Management Tools — Feature Set Overview. 326 PUBLIC SAP BTP Connectivity Connectivity
- 327. Next Step Get the URL [Feature Set A] [page 327] Get the URL [Feature Set B] [page 328] Caution Mind the respective user rights described in the prerequisites for Initial Configuration [page 312] and Managing Subaccounts [page 328]. For feature set A, it is mandatory to be a subaccount Security Administrator, not only a global account member. Back to Content [page 324] Get the URL [Feature Set A] Choose one of the following options: Option 1: Assemble the URL The URL pattern is https:/ /login.cf.<btp-region-host>/passcode. 1. Get the SAP BTP region host, for example, eu10.hana.ondemand.com. 2. Assemble the final URL to be used, in this case: https:/ /login.cf.eu10.hana.ondemand.com/passcode. Option 2: Get the URL Using the Cloud Foundry CLI Use the Cloud Foundry CLI to perform the following steps: 1. Execute the command cf api to navigate to the SAP BTP region. 2. Execute cf login --sso to get the URL. Sample Code $ cf api api.cf.eu10.hana.ondemand.com Setting api endpoint to api.cf.eu10.hana.ondemand.com... OK api endpoint: https://api.cf.eu10.hana.ondemand.com api version: 2.156.0 $ cf login --sso API endpoint: https://api.cf.eu10.hana.ondemand.com Temporary Authentication Code ( Get one at https:// login.cf.eu10.hana.ondemand.com/passcode ): Next Step Get the One-Time Passcode [page 328] Back to Content [page 324] SAP BTP Connectivity Connectivity PUBLIC 327
- 328. Get the URL [Feature Set B] Choose one of the following options: Option 1: Assemble the URL The URL pattern is https:/ /<subdomain>.authentication.<btp-XSUAA-host>/passcode. 1. Get the SAP BTP region host, for example, eu10.hana.ondemand.com. 2. Assemble the final URL to be used, in this case: https:/ / mysubdomain.authentication.eu10.hana.ondemand.com/passcode. Option 2: Get the URL Using the Connectivity Service Instance Credentials 1. Choose one of these steps to obtain the URL: ○ Create and Bind a Connectivity Service Instance [page 159] ○ Create a service key 2. Get the value of the token_service_url attribute. 3. Append /passcode at the end of the obtained URL. Next Step Get the One-Time Passcode [page 328] Back to Content [page 324] Get the One-Time Passcode 1. Open the resulting URL in your browser to get the one-time passcode via SSO: ○ If there is an active user session, the passcode is generated automatically and returned right away. ○ If there is no active user session, you are asked to log on to the IDP manually. If several IDPs are configured, you can choose one from the available options. 2. Use the passcode to proceed with the subaccount configuration in the Cloud Connector UI. Back to Content [page 324] 1.2.2.2 Managing Subaccounts Add and connect your SAP BTP subaccounts to the Cloud Connector. 328 PUBLIC SAP BTP Connectivity Connectivity
- 329. Note This topic refers to subaccount management in the Cloud Connector. If you are looking for information about managing subaccounts on SAP BTP (Cloud Foundry or Neo environment), see ● Account Administration (Cloud Foundry environment) ● Administration and Operations, Neo Environment Context As of version 2.2, you can connect to several subaccounts within a single Cloud Connector installation. Those subaccounts can use the Cloud Connector concurrently with different configurations. By selecting a subaccount from the drop-down box, all tab entries show the configuration, audit, and state, specific to this subaccount. In case of audit and traces, cross-subaccount info is merged with the subaccount-specific parts of the UI. Note We recommend that you group only subaccounts with the same qualities in a single installation: ● Productive subaccounts should reside on a Cloud Connector that is used for productive subaccounts only. ● Test and development subaccounts can be merged, depending on the group of users that are supposed to deal with those subaccounts. However, the preferred logical setup is to have separate development and test installations. Prerequisites You have assigned one of these roles/role collections to the subaccount user that you use for initial Cloud Connector setup, depending on the SAP BTP environment in which your subaccount is running: Note For the Cloud Foundry environment, you must know on which cloud management tools feature set (A or B) your account is running. For more information on feature sets, see Cloud Management Tools — Feature Set Overview. SAP BTP Connectivity Connectivity PUBLIC 329
- 330. Environment Required Roles/Role Collections More Information Cloud Foundry [feature set A] The user must be a member of the global account that the subaccount be longs to. Alternatively, you can assign the user as Security Administrator. Add Members to Your Global Account Managing Security Administrators in Your Subaccount [Feature Set A] Cloud Foundry [feature set B] Assign at least one of these default role collections (all of them including the role Cloud Connector Administrator): ● Subaccount Administrator ● Cloud Connector Administrator ● Connectivity and Destination Administrator Alternatively, you can assign a custom role collection to the user that includes the role Cloud Connector Administrator. Default Role Collections [Feature Set B] [page 13] Role Collections and Roles in Global Ac counts and Subaccounts [Feature Set B] Neo Assign at least one of these default roles: ● Cloud Connector Admin ● Administrator Alternatively, you can assign a custom role to the user that includes the per mission manageSCCTunnels. Managing Member Authorizations in the Neo Environment After establishing the Cloud Connector connection, this user is not needed any more, since it serves only for initial connection setup. You may revoke the corresponding role assignment then and remove the user from the Members list. Note If the Cloud Connector is installed in an environment that is operated by SAP, SAP provides a user that you can add as member in your SAP BTP subaccount and assign the required role. Subaccount Dashboard In the subaccount dashboard (choose your Subaccount from the main menu), you can check the state of all subaccount connections managed by this Cloud Connector at a glance. 330 PUBLIC SAP BTP Connectivity Connectivity
- 331. In the screenshot above, the test1 subaccount is already connected, but has no active resources exposed. The test2 subaccount is currently disconnected. The dashboard also lets you disconnect or connect the subaccounts by choosing the respective button in the Actions column. If you want to connect an additional subaccount to your on-premise landscape, choose the Add Subaccount button. A dialog appears, which is similar to the Initial Configuration operation when establishing the first connection. SAP BTP Connectivity Connectivity PUBLIC 331
- 332. Procedure 1. The <Region> field specifies the SAP BTP region that should be used, for example, Europe (Rot). Choose the one you need from the drop-down list. Note You can also configure a region yourself, if it is not part of the standard list. Either insert the region host manually, or create a custom region, as described in Configure Custom Regions [page 339]. 2. For <Subaccount> and <Subaccount User> (user/password), enter the values you obtained when you registered your account on SAP BTP. Note If your subaccount is on Cloud Foundry, you must enter the subaccount ID as <Subaccount>, rather than its actual (technical) name. For information on getting the subaccount ID, see Find Your Subaccount ID (Cloud Foundry Environment) [page 338]. As <Subaccount User> you must provide your Login E-mail instead of a user ID. For the Neo environment, enter the subaccount's technical name in the field <Subaccount>, not the subaccount ID. Alternatively, you can add a new subaccount user in the SAP BTP cockpit, assign the required authorization (see section Prerequisites above), and use the new user and password. Tip When using SAP Cloud Identity Services - Identity Authentication (IAS) as platform identity provider with two-factor authentication for your subaccount, you can simply append the required token to the regular password. Tip For a subaccount in the Cloud Foundry environment, the Cloud Connector supports the use of a custom identity provider (IDP) via single sign-on (SSO) passcode. For more information, see Use a Custom IDP for Subaccount Configuration [page 324]. 3. (Optional) You can define a <Display Name> that allows you to easily recognize a specific subaccount in the UI compared to the technical subaccount name. 4. (Optional) You can define a <Location ID> that identifies the location of this Cloud Connector for a specific subaccount. As of Cloud Connector release 2.9.0, the location ID is used as routing information and therefore you can connect multiple Cloud Connectors to a single subaccount. If you don't specify any value for <Location ID>, the default is used, which represents the behavior of previous Cloud Connector versions. The location ID must be unique per subaccount and should be an identifier that can be used in a URI. To route requests to a Cloud Connector with a location ID, the location ID must be configured in the respective destinations. 5. (Optional) You can provide a <Description> of the subaccount that is shown when clicking on the Details icon in the Actions column. 6. Choose Save. 332 PUBLIC SAP BTP Connectivity Connectivity
- 333. Next Steps ● To modify an existing subaccount, choose the Edit icon and change the <Display Name>, <Location ID> and/or <Description>. ● You can also delete a subaccount from the list of connections.The subaccount will be disconnected and all configurations will be removed from the installation. Related Information Managing Member Authorizations in the Neo Environment Copy a Subaccount Configuration [page 333] Update the Certificate for a Subaccount [page 335] Configure a Disaster Recovery Subaccount [page 336] Find Your Subaccount ID (Cloud Foundry Environment) [page 338] Configure Custom Regions [page 339] 1.2.2.2.1 Copy a Subaccount Configuration Copy an existing subcaccount configuration in the Cloud Connector to another subaccount. You can copy the configuration of a subaccount's Cloud To On-Premise and On-Premise To Coud sections to a new subaccount, by using the export and import functions in the Cloud Connector administration UI. SAP BTP Connectivity Connectivity PUBLIC 333
- 334. Note Principal propagation configuration (section Cloud To On-Premise) is not exported or imported, since it contains subaccount-specific data. Procedure: Export an Existing Configuration 1. In the Cloud Connector administration UI, choose your subaccount from the navigation menu. 2. To export the existing configuration, choose the Export button in the upper right corner. The configuration is downloadad as a zip file to your local file system. Procedure: Import an Existing Configuration 1. From the navigation menu, choose the subaccount to which you want to copy an existing configuration. 2. To import an existing configuration, choose the Import button in the upper right corner. 3. Select one of the following sources: 1. File, if you want to copy the configuration from a previously downloaded zip file. 2. Subaccount, if you want to copy the configuration directly from another existing subaccount. 334 PUBLIC SAP BTP Connectivity Connectivity
- 335. 1.2.2.2.2 Update the Certificate for a Subaccount Certificates used by the Cloud Connector are issued with a limited validity period. To prevent a downtime while refreshing the certificate, you can update it for your subaccount directly from the administration UI. Prerequisites You must have the required subaccount authorizations on SAP BTP to update certificates for your subaccount. See: ● Connectivity: Technical Roles (Cloud Foundry environment) ● Connectivity: User Roles (Neo environment) Procedure Proceed as follows to update your subaccount certificate: 1. From the main menu, choose your subaccount. 2. Choose the Certificate button. A dialog opens, requesting a user name and password. 3. Enter <User Name> and <Password> and choose OK. The certificate assigned to your subaccount is refreshed. Note In the Cloud Foundry environment, you must provide your Login E-mail instead of a user ID as <User Name>. SAP BTP Connectivity Connectivity PUBLIC 335
- 336. 4. If you have configured a disaster recovery subaccount, go to section Disaster Recovery Subaccount below and choose Refresh Disaster Recovery Certificate. 5. Enter <User Name> and <Password> as in step 3 and choose OK. 1.2.2.2.3 Configure a Disaster Recovery Subaccount Configure a subaccount as backup for disaster recovery. Each subaccount (except trial accounts) can optionally have a disaster recovery subaccount. Prerequisite is that you are using the enhanced disaster revovery, see What is Enhanced Disaster Recovery. The disaster recovery subaccount is intended to take over if the region host of its associated original subaccount faces severe issues. A disaster recovery account inherits the configuration from its original subaccount except for the region host. The user can, but does not have to be the same. Procedure 1. From the main menu, choose your subaccount. 2. In section Disaster Recovery Subaccount, choose Configure disaster recovery subaccount. 3. In the configuration dialog, select an appropriate <Region Host> from the drop-down list. Note The selected region host must be different from the region host of the original subaccount. 4. (Optional) You can adjust the <Subaccount User>. 5. Enter the <Password> for the subaccount user. 6. If configured, enter a <Location ID>. 7. Choose Save. 336 PUBLIC SAP BTP Connectivity Connectivity
- 337. Note The technical subaccount name, the display name, and the location ID must remain the same. They are set automatically and cannot be changed. Note You cannot choose another original subaccount nor a trial subaccount to become a disaster recovery subaccount. Note If you want to change a disaster recovery subaccount, you must delete it first and then configure it again. To switch from the original subaccount to the disaster recovery subaccount, choose Employ disaster recovery subaccount. The disaster recovery subaccount then becomes active, and the original subaccount is deactivated. You can switch back to the original subaccount as soon as it is available again. Note As of Cloud Connector 2.11, the cloud side informs about a disaster by issuing an event. In this case, the switch is performed automatically. Related Information Convert a Disaster Recovery Subaccount into a Standard Subaccount [page 338] SAP BTP Connectivity Connectivity PUBLIC 337
- 338. 1.2.2.2.3.1 Convert a Disaster Recovery Subaccount into a Standard Subaccount Convert a disaster recovery sucaccount into a standard subaccount if the former primary subaccount's region cannot be recovered. Disaster recovery subaccounts that were switched to disaster recovery mode can be elevated to standard subaccounts if a disaster recovery region replaces an original region that is not expected to recover. If a disaster recovery subaccount should be used as primary subaccount, you can convert it by choosing the button Discard original subaccount and replace it with disaster recovery subaccount. 1.2.2.2.4 Find Your Subaccount ID (Cloud Foundry Environment) Get your subaccount ID to configure the Cloud Connector in the Cloud Foundry environment. Note For the Beta version, the cloud cockpit is not yet available. In order to set up your subaccount in the Cloud Connector, you must know the subaccount ID. Follow these steps to acquire it: 1. Open the SAP BTP cockpit. 2. Navigate to the subaccount list of the global account containing your subaccount: choose Home <Your Global Account> Subaccounts . 3. Find your subaccount in the list. 4. Choose the Info icon in the subaccount tile to display the subaccount ID: 338 PUBLIC SAP BTP Connectivity Connectivity
- 339. 1.2.2.2.5 Configure Custom Regions Configure regions that are not available in the standard selection. If you want to use a custom region for your subaccount, you can configure regions in the Cloud Connector, which are not listed in the selection of standard regions. To add a custom region, do the following: 1. From the Cloud Connector main menu, choose Configuration Cloud and go to the Custom Regions section. 2. To add a region to the list, choose the Add icon. 3. In the Add Region dialog, enter the <Region> and <Region Host> you want to use. 4. Choose Save. 5. To edit a region from the list, select the corresponding line and choose the Edit icon. 1.2.2.3 Authenticating Users against On-Premise Systems Authentication types supported by the Cloud Connector. Currently, the Cloud Connector supports basic authentication and principal propagation (user propagation) as user authentication types towards internal systems. The destination configuration of the used cloud application defines which of these types is used for the actual communication to an on-premise system through the Cloud Connector, see Managing Destinations [page 38]. ● To use basic authentication, configure an on-premise system to accept basic authentication and to provide one or multiple service users. No additional steps are necessary in the Cloud Connector for this authentication type. SAP BTP Connectivity Connectivity PUBLIC 339
- 340. ● To use principal propagation, you must explicitly configure trust to those cloud entities from which user tokens are accepted as valid. You can do this in the Trust view of the Cloud Connector, see Set Up Trust for Principal Propagation [page 341]. Related Information Configuring Principal Propagation [page 340] 1.2.2.3.1 Configuring Principal Propagation Use principal propagation to simplify the access of SAP BTP users to on-premise systems. Tasks in this section: Task Description Set Up Trust for Principal Propagation [page 341] Configure a trusted relationship in the Cloud Connector to support principal propagation. Principal propagation lets you forward the logged-on identity in the cloud to the internal system without requesting a password. Configure a CA Certificate for Principal Propagation [page 344] Install and configure an X.509 certificate to enable support for principal propagation. Configuring Principal Propagation to an ABAP System [page 347] Learn more about the different types of configuring and sup porting principal propagation for a particular AS ABAP. Configure a Subject Pattern for Principal Propagation [page 359] Define a pattern identifying the user for the subject of the generated short-lived X.509 certificate, as well as its valid ity period. Configure a Secure Login Server [page 361] Configuration steps for Java Secure Login Server (SLS) sup port. Configure Kerberos [page 365] The Cloud Connector lets you propagate users authenti cated in SAP BTP via Kerberos against back-end systems. It uses the Service For User and Constrained Delegation pro tocol extension of Kerberos. Configuring Principal Propagation to SAP NetWeaver AS for Java [page 367] Find step-by-step instructions on how to configure principal propagation to an application server Java (AS Java). Related Information 340 PUBLIC SAP BTP Connectivity Connectivity
- 341. Principal Propagation [page 121] (Cloud Foundry environment) Principal Propagation (Neo environment) 1.2.2.3.1.1 Set Up Trust for Principal Propagation Establish trust to an identiy provider to support principal propagation. Tasks Configure Trusted Entities in the Cloud Connector [page 341] Configure an On-Premise System for Principal Propagation [page 342] Trust Cloud Applications in the Cloud Connector [page 343] Set up a Trust Store [page 343] Configure Trusted Entities in the Cloud Connector You perform trust configuration to support principal propagation. By default, your Cloud Connector does not trust any entity that issues tokens for principal propagation. Therefore, the list of trusted identity providers is empty by default. If you decide to use the principal propagation feature, you must establish trust to at least one identiy provider. Currently, SAML2 identity providers are supported. You can configure trust to one or more SAML2 IdPs per subaccount. After you've configured trust in the cockpit for your subaccount, for example, to your own company's identity provider(s), you can synchronize this list with your Cloud Connector. As of Cloud Connector 2.4, you can also trust HANA instances and Java applications to act as identity providers. From your subaccount menu, choose Cloud to On-Premise and go to the Principal Propagation tab. Choose the Synchronize button to store the list of existing identity providers locally in your Cloud Connector. Select an entry to see its details: SAP BTP Connectivity Connectivity PUBLIC 341
- 342. ● Name: the name associated with the identity provider. ● Description: descriptive information about this entry. ● Type: type of the trusted entity. ● Trusted: indicates whether the entry is trusted for principal propagation. ● Actions: Choose the Show Certificate Information icon to display detail information for the corresponding entry. The Cloud Connector runtime will use the certificate associated with the entry to verify that the assertion used for principal propagation was issued by a trusted entity. You can decide for each entry, whether to trust it for the principal propagation use case by choosing Edit and (de)selecting the Trusted checkbox. Note Whenever you update the SAML IdP configuration for a subaccount on cloud side, you must synchronize the trusted entities in theCloud Connector. Otherwise the validation of the forwarded SAML assertion will fail with an exception containing an exception message similar to this: Caused by: com.sap.engine.lib.xml.signature.SignatureException: Unable to validate signature -> java.security.SignatureException: Signature decryption error: javax.crypto.BadPaddingException: Invalid PKCS#1 padding: encrypted message and modulus lengths do not match!. Back to Tasks [page 341] Configure an On-Premise System for Principal Propagation Set up principal propagation from SAP BTP to your internal system that is used in a hybrid scenario. Note As a prerequisite for principal propagation for RFC, the following cloud application runtime versions are required: ● for Java Web: 1.51.8 or higher ● for Java EE 6 Web Profile: 2.31.11 or higher ● other runtimes support it with any version 1. Set up trust to an entity that is issuing an assertion for the logged-on user (see section above). 2. Set up the system identity for the Cloud Connector. ○ For HTTPS, you must import a system certificate into your Cloud Connector. ○ For RFC, you must import an SNC PSE into your Cloud Connector. 3. Configure the target system to trust the Cloud Connector. There are two levels of trust: 1. First, you must allow the Cloud Connector to identify itself with its system certificate (for HTTPS), or with the SNC PSE (for RFC). 2. Then, you must allow this identity to propagate the user accordingly: 342 PUBLIC SAP BTP Connectivity Connectivity
- 343. ○ For HTTPS, the Cloud Connector forwards the true identity in a short-lived X.509 certificate in an HTTP header named SSL_CLIENT_CERT. The system must use this certificate for logging on the real user. The SSL handshake, however, is performed through the system certificate. ○ For RFC, the Cloud Connector forwards the true identity as part of the RFC protocol. For more information, see Configuring Principal Propagation to an ABAP System [page 347]. 4. Configure the user mapping in the target system. The X.509 certificate contains information about the cloud user in its subject. Use this information to map the identity to the appropriate user in this system. This step applies for both HTTPS and RFC. Note If you have the following scenario: Application1->AppToAppSS0->Application2->Principal Propagation->On premise Backend System you must mark Application2 as trusted by the Cloud Connector in tab Principal Propagation, section Trust Configuration. If you use an identity provider that issues unsigned assertions, you must mark all relevant applications as trusted by the Cloud Connector in tab Principal Propagation, section Trust Configuration. Back to Tasks [page 341] Trust Cloud Applications in the Cloud Connector Configure an allowlist for trusted cloud applications, see Configure Trust [page 490]. Back to Tasks [page 341] Set up a Trust Store Configure a trust store that acts as an allowlist for trusted on-premise systems. See Configure Trust [page 490]. Back to Tasks [page 341] Related Information Principal Propagation [page 121] (Cloud Foundry) Principal Propagation (Neo) SAP BTP Connectivity Connectivity PUBLIC 343
- 344. 1.2.2.3.1.2 Configure a CA Certificate for Principal Propagation Install and configure an X.509 certificate to enable support for principal propagation in the Cloud Connector. Supported CA Mechanisms You can enable support for principal propagation with X.509 certificates by performing either of the following procedures: ● Using a Local CA in the Cloud Connector. Note Prior to version 2.7.0, this was the only option and the system certificate was acting both as client certificate and CA certificate in the context of principal propagation. ● Using a Secure Login Server and delegate the CA functionality to it. The Cloud Connector uses the configured CA approach to issue short-lived certificates for logging on the same identity in the back end that is logged on in the cloud. For establishing trust with the back end, the respective configuration steps are independent of the approach that you choose for the CA. Install a local CA Certificate To issue short-lived certificates that are used for principal propagation to a back-end system, you can import an X.509 client certificate into the Cloud Connector. This CA certificate must be provided as PKCS#12 file containing the (intermediate) certificate, the corresponding private key, and the CA root certificate that signed the intermediate certificate (plus the certificates of any other intermediate CAs, if the certificate chain includes more than those two certificates). Use either of the following options to install a local CA certificate: ● Option 1: Choose the PKCS#12 file from the file system, using the file upload dialog. For the import process, you must also provide the file password. ● Option 2: Start a Certificate Signing Request (CSR) procedure like for the UI certificate, see Recommended: Exchange UI Certificates in the Administration UI [page 303]. ● Option 3: (As of version 2.10) Generate a self-signed certificate, which might be useful in a demo setup or if you need a dedicated CA. In particular for this option, it is useful to export the public key of the CA via the button Download certificate in DER format. Note The CA certificate should have the KeyUsage attribute keyCertSign. Many systems verify that the issuer of a certificate includes this attribute and deny a client certificate without this attribute. When using the CSR procedure, the attribute is requested for the CA certificate. Also, when generating a self-signed certificate, this attribute is added automatically. 344 PUBLIC SAP BTP Connectivity Connectivity
- 345. Choose Import a certificate for option 1: Choose Generate a certificate signing request for option 2: Choose Create and import a self-signed certificate if you want to use option 3: After successful import of the CA certificate, its distinguished name, the name of the issuer, and the validity dates are shown: SAP BTP Connectivity Connectivity PUBLIC 345
- 346. If a CA certificate is no longer required, you can delete it. Use the respective Delete button and confirm the deletion. Configure a CA Hosted by a Secure Login Server If you want to delegate the CA functionality to a Secure Login Server, choose the CA using Secure Login Server option and configure the Secure Login Server as follows, after having configured the Secure Login server as described in Configure a Secure Login Server [page 361]. Enter the following: ● <Host Name>: The host, on which your Secure Login Server (SLS) is installed. ● <Profiles Port>: The profiles port must be provided only when your Secure Login Server is configured to not allow to fetch profiles via the privileged authentication port. In this case, you can provide here the port that is configured for that functionality. ● <Authentication Port>: The port, over which the Cloud Connector is requesting the short-lived certificates from SLS. Choose Next. Note For this privileged port, a client certificate authentication is required, for which the Cloud Connector system certificate is used. ● <Profile>: The Secure Login Server profile that allows to issue certificates as needed for principal propagation with the Cloud Connector. Choose Finish to store the configuration. 346 PUBLIC SAP BTP Connectivity Connectivity
- 347. Related Information Configure a Secure Login Server [page 361] Initial Configuration (HTTP) [page 319] Initial Configuration (RFC) [page 321] 1.2.2.3.1.3 Configuring Principal Propagation to an ABAP System Learn more about the different types of configuring and supporting principal propagation for a particular AS ABAP. Task Description Configure Principal Propagation for HTTPS [page 347] Step-by-step instructions to configure principal propagation to an ABAP server for HTTPS. Configure Principal Propagation via SAP Web Dispatcher [page 351] Set up a trust chain to use principal propagation to an ABAP server for HTTPS via SAP Web Dispatcher. Configure Principal Propagation for RFC [page 354] Step-by-step instructions to configure principal propagation to an ABAP server for RFC. Rule-Based Mapping of Certificates [page 358] Map short-lived certificates to users in the ABAP server. 1.2.2.3.1.3.1 Configure Principal Propagation for HTTPS Find step-by-step instructions to configure principal propagation to an ABAP server for HTTPS. Example Data The following data are used in this example: ● System certificate was issued by: CN=MyCompany CA, O=Trust Community, C=DE. ● It has the subject: CN=SCC, OU=HCP Scenarios, O=Trust Community, C=DE. ● The short-lived certificate has the subject CN=P1234567890, where P1234567890 is the platform user. Tasks Prerequisites [page 348] SAP BTP Connectivity Connectivity PUBLIC 347
- 348. Configure an ABAP System to Trust the Cloud Connector's System Certificate [page 348] Map Short-Lived Certificates to Users [page 350] Access ICF Services [page 350] Prerequisites To perform the following steps, you must have the corresponding authorizations in the ABAP system for the transactions mentioned below (administrator role according to your specific authorization management) as well as an administrator user for the Cloud Connector. Back to Tasks [page 347] Back to Example Data [page 347] 1. Configure an ABAP System to Trust the Cloud Connector's System Certificate This step includes two sub-steps: Configure the ABAP system to trust the Cloud Connector's system certificate [page 348] Configure the Internet Communication Manager (ICM) to trust the system certificate for principal propagation [page 349] Configure the ABAP system to trust the Cloud Connector's system certificate: 1. Open the Trust Manager (transaction STRUST). 2. Double-click the SSL-Server Standard folder in the menu tree on the left. 3. In the displayed screen, click the Import certificate button. 4. In the dialog window, choose the certificate file representing the public key of the issuer of the system certificate, for example, in DER format. Typically, this is a CA certificate. If you decide to use a self-signed system certificate, it is the system certificate itself. 5. The details of this certificate are shown in the section above. Using the example certificate data, you would see CN=MyCompany CA, O=Trust Community, C=DE as subject. 6. If you are sure that you are importing the correct certificate, you can integrate the certificate into the certificate list by choosing the Add to Certificate List button. 7. Now, the CA certificate (CN=MyCompany CA, O=Trust Community, C=DE) is part of the certificate list. Back to Step [page 348] 348 PUBLIC SAP BTP Connectivity Connectivity
- 349. Configure the Internet Communication Manager (ICM) to trust the system certificate for principal propagation: 1. Open the Profile Editor (transaction RZ10). 2. Select the profile you want to edit, for example, the DEFAULT profile. 3. Select the Extended maintenance radio button and choose the Change button. 4. Create the following parameter: icm/trusted_reverse_proxy_<x> = SUBJECT="<subject>", ISSUER="<issuer>". ○ Select a free index for <x>. ○ <subject> is the subject of the system certificate (example data: CN=SCC, OU=BTP Scenarios, O=Trust Community, C=DE). ○ <issuer> is the issuer of the system certificate (example data: CN=MyCompany CA, O=Trust Community, C=DE ). ○ Example: icm/trusted_reverse_proxy_2 = SUBJECT=" CN=SCC, OU=BTP Scenarios, O=Trust Community, C=DE ", ISSUER=" CN=MyCompany CA, O=Trust Community, C=DE ". Note If your ABAP system uses kernel 7.42 or lower, see SAP note 2052899 or set the following two parameters: ○ icm/HTTPS/trust_client_with_issuer: this is the issuer of the system certificate (example data: CN=MyCompany CA, O=Trust Community, C=DE). ○ icm/HTTPS/trust_client_with_subject: this is the subject of the system certificate (example data: CN=SCC, OU=HCP Scenarios, O=Trust Community, C=DE). Caution Make sure that icm/HTTPS/verify_client is set to either 1 (request certificate) or 2 (require certificate). If the parameter is set to 0, trust cannot be established. 5. Save the profile. 6. Open the ICM Monitor (transaction SMICM) and restart the ICM by choosing Administration ICM Exit Hard Global . 7. Verify that the two profile parameters have been taken over by ICM by choosing Goto Parameters Display . Note If you have an SAP Web Dispatcher installed in front of the ABAP system, trust must be added in its configuration files with the same parameters as for the ICM. Also, you must add the system certificate of the Cloud Connector to the trust list of the Web dispatcher Server PSE. For more information, see Configure Principal Propagation via SAP Web Dispatcher [page 351]. Caution When using principal propagation with X.509 certificates, you cannot use the strict mode in certificate block management (transaction code: CRCONFIG) for the CRL checks within profile SSL_SERVER. SAP BTP Connectivity Connectivity PUBLIC 349
- 350. Back to Step [page 348] Back to Tasks [page 347] Back to Example Data [page 347] 2. Map Short-Lived Certificates to Users For systems later than SAP NetWeaver 7.3 EHP1 (7.31), you can use rule-based certificate mapping, which is the recommended way to create the required user mappings. For more information, see Rule-Based Mapping of Certificates [page 358]. In older releases (for which this feature does not exist yet), you can do this manually in the system as described below, or use an identity management solution generating the mapping table for a more comfortable approach. 1. Open Assignment of External ID to Users (transaction EXTID_DN). 2. Switch to the edit mode. 3. Create a new entry. Specify the subject of the certificate as External ID. When using the example data, this is CN=P1234567890. In the User field, provide the appropriate ABAP user, for example JOHNSMITH. 4. Choose Activate. 5. Save the mapping. 6. Repeat the previous steps for all users that should be supported for the scenario. Back to Tasks [page 347] Back to Example Data [page 347] 3. Access ICF Services To access the required ICF services for your scenario in the ABAP system, choose one of the following procedures: ● To access ICF services via certificate logon, choose the principal type X.509 Certificate (general usage) in the corresponding system mapping. This setting lets you use the system certificate for trust as well as for user authentication. For details, see Configure Access Control (HTTP) [page 370], step 7. Additionally, make sure that all required ICF services allow Logon Through SSL Certificate as logon method. ● To access ICF services via the logon method Basic Authentication (logon with user/password) and principal propagation, choose the principal type X.509 Certificate (strict usage) in the corresponding system mapping. This setting lets you use the system certificate for trust, but prevents its usage for user authentication. For details, see Configure Access Control (HTTP) [page 370], step 7. Additionally, make sure that all required ICF services allow Basic Authentication and Logon Through SSL Certificate as logon methods. 350 PUBLIC SAP BTP Connectivity Connectivity
- 351. ● If some of the ICF services require Basic Authentication, while others should be accessed via system certificate logon, proceed as follows: 1. In the Cloud Connector sytem mapping, choose the principal type X.509 Certificate (general usage) as described above. 2. In the ABAP system, choose transaction code SICF and go to Maintain Services. 3. Select the service that requires Basic Authentication as logon method. 4. Double-click the service and go to tab Logon Data. 5. Switch to Alternative Logon Procedure and ensure that the Basic Authentication logon procedure is listed before Logon Through SSL Certificate. Note If you are using SAP Web Dispatcher for communication, you must configure it to forward the SSL certficate to the ABAP backend system, see Forward SSL Certificates for X.509 Authentication (SAP Web Dispatcher documentation). Back to Tasks [page 347] Back to Example Data [page 347] Related Information Configure Principal Propagation via SAP Web Dispatcher [page 351] Rule-Based Mapping of Certificates [page 358] Configure a Subject Pattern for Principal Propagation [page 359] Set Up Trust for Principal Propagation [page 341] Principal Propagation [page 121] (Cloud Foundry environment) Principal Propagation (Neo environment) 1.2.2.3.1.3.1.1 Configure Principal Propagation via SAP Web Dispatcher Set up a trust chain to use principal propagation to an ABAP System for HTTPS via SAP Web Dispatcher. Concept SAP BTP Connectivity Connectivity PUBLIC 351
- 352. If you are using an intermediate SAP Web Dispatcher to connect to your ABAP backend system, you must set up a trust chain between the involved components Cloud Connector, SAP Web Dispatcher, and ABAP backend system. Before configuring the ABAP system (see Configure Principal Propagation for HTTPS [page 347]), in a first step you must configure SAP Web Dispatcher to accept and forward user principals propagated from a cloud account to an ABAP backend. To do this, follow the step-by-step instructions below. Example Data The following data and setup is used for this scenario: ● System certificate was issued by CN=MyCompany CA, O=Trust Community, C=DE ● It has the subject CN=SCC, OU=BTP Scenarios, O=Trust Community, C=DE Tasks ● Prerequisites [page 352] ● Configure the SAP Web Dispatcher to Trust the Cloud Connector's System Certificate [page 353] ● Next Steps [page 354] Prerequisites ● Your SAP Web Dispatcher version is 7.53 or higher. See SAP note 908097 for information on recommended SAP Web Dispatcher versions. ● Make sure your SAP Web Dispatcher supports SSL. See Configure SAP Web Dispatcher to Support SSL. ● Ensure that SSL client certificates can be used for authentication in the backend system. See How to Configure SAP Web Dispatcher to Forward SSL Certificates for X.509 Authentication for step-by-step instructions. Back to Tasks [page 352] Back to Concept [page 351] 352 PUBLIC SAP BTP Connectivity Connectivity
- 353. Configure SAP Web Dispatcher to Trust the Cloud Connector's System Certificate To allow Cloud Connector client certificates for authentication in the backend system, perform the following two steps: 1. Configure SAP Web Dispatcher to trust the Cloud Connector's system certificate: 1. To import the system certificate to SAP Web Dispatcher, open the SAP Web Dispatcher administration interface in your browser. Note The interface is usually configured on /sap/wdisp/admin. 2. In the menu, navigate to SSL and Trust Configuration and select PSE Management. 3. In the Manage PSE section, select SAPSSLS.pse from the drop-down list. By default, SAPSSLS.pse contains the server certificate and the list of trusted clients that SAP Web Dispatcher trusts as a server. 4. In the Trusted Certificates section, choose Import Certificate. 5. Enter the certificate as base64-encoded into the text box. The procedure to export your certificate in such a format is described in Forward SSL Certificates for X.509 Authentication, step 1. Note Typically, this is a CA certificate. If you are using a self-signed system certificate, it's the system certificate itself. 6. Choose Import. 7. The certificate details are now shown in section Trusted Certificates. 2. Configure SAP Web Dispatcher to trust the Cloud Connector's system certificate for principal propagation: ○ Create or edit the following parameter in SAP Web Dispatcher: icm/trusted_reverse_proxy_<x> = SUBJECT="<subject>", ISSUER="<issuer>" ○ Select a free index for <x>. ○ <subject>: Subject of the system certificate (example data: CN=SCC, OU=BTP Scenarios, O=Trust Community, C=DE) ○ <issuer>: Issuer of the system certificate (example data: CN=MyCompany CA, O=Trust Community, C=DE) Example: icm/trusted_reverse_proxy_0 = SUBJECT="CN=SCC, OU=BTP Scenarios, O=Trust Community, C=DE", ISSUER="CN=MyCompany CA, O=Trust Community, C=DE" ○ [Deprecated] Create or edit the following two parameters in SAP Web Dispatcher: Note Use the parameters below (instead of icm/trusted_reverse_proxy_<x>) only if your kernel release does not yet support parameter icm/trusted_reverse_proxy_<x>. ○ icm/HTTPS/trust_client_with_issuer: Issuer of the system certificate (example data: CN=MyCompany CA, O=Trust Community, C=DE) SAP BTP Connectivity Connectivity PUBLIC 353
- 354. ○ icm/HTTPS/trust_client_with_subject: Subject of the system certificate (example data: CN=SCC, OU=BTP Scenarios, O=Trust Community, C=DE ) Note Make sure icm/HTTPS/verify_client is set to 1 (request certificate) or 2 (require certificate). If set to 0, trust cannot be established. The default value is 1, so it is OK if the parameter is not set at all. Back to Tasks [page 352] Back to Concept [page 351] Next Steps Now you can proceed with: ● Step 1 of the basic principal propagation setup for HTTPS, see Configure an ABAP System to Trust the Cloud Connector's System Certificate [page 348]. However, when using SAP Web Dispatcher, the ABAP backend must trust the SAP Web Dispatcher instead of the Cloud Connector, see Forward SSL Certificates for X.509 Authentication, step 2 for details. Then perform the remaining steps of the basic principal propagation setup for HTTPS as described here: ● Map Short-Lived Certificates to Users [page 350] ● Access ICF Services [page 350] Back to Tasks [page 352] Back to Concept [page 351] 1.2.2.3.1.3.2 Configure Principal Propagation for RFC Find step-by-step instructions to configure principal propagation to an ABAP server for RFC. Configuring principal propagation for RFC requires an SNC (Secure Network Communications) connection. To enable SNC, you must configure the ABAP system and the Cloud Connector accordingly. The following example provides step-by-step instructions for the SNC setup. Note It is important that you use the same SNC implementation on both communication sides. Contact the vendor of your SNC solution to check the compatibility rules. 354 PUBLIC SAP BTP Connectivity Connectivity
- 355. Example Data The following data and setup is used: Note The parameters provided in this example are based on an SNC implementation that uses the SAP Cryptographic Library. Other vendors' libraries may require different values. ● An SNC identity has been generated and installed on the Cloud Connector host. Generating this identity for the SAP Cryptographic Library is typically done using the tool SAPGENPSE. For more information, see Configuring SNC for SAPCRYPTOLIB Using SAPGENPSE. ● The ABAP system is configured properly for SNC. Note For the latest system releases, you can use the SSO wizard to configure SNC (transaction code: SNCWIZARD). System prerequisites are described in SAP note 2015966 . ● The Cloud Connector system identity's SNC name is p:CN=SCC, OU=SAP CP Scenarios, O=Trust Community, C=DE. ● The ABAP system's SNC identity name is p:CN=SID, O=Trust Community, C=DE. This value can typically be found in the ABAP system instance profile parameter snc/identity/as and hence is provided per application server. ● When using the SAP Cryptographic Library, the ABAP system's SNC identity and the Cloud Connector's system identity should be signed by the same CA for mutual authentication. ● The example short-lived certificate has the subject CN=P1234567, where P1234567 is the SAP BTP application user. Tasks 1. Configure the ABAP System [page 355] 2. Map Short-Lived Certificates to Users [page 356] 3. Configure the Cloud Connector [page 356] 1. Configure the ABAP System to Trust the Cloud Connector's System SNC identity 1. Open the SNC Access Control List for Systems (transaction SNC0). 2. As the Cloud Connector does not have a system ID, use an arbitray value for <System ID> and enter it together with its SNC name: p:CN=SCC, OU=SAP CP Scenarios, O=Trust Community, C=DE. 3. Save the entry and choose the Details button. SAP BTP Connectivity Connectivity PUBLIC 355
- 356. 4. In the next screen, activate the checkboxes for Entry for RFC activated and Entry for certificate activated. 5. Save your settings. Back to Tasks [page 355] Back to Example Data [page 355] 2. Map Short-Lived Certificates to Users You can do this manually in the system as described below or use an identity management solution for a more comfortable approach. For example, for large numbers of users the rule-based certificate mapping is a good way to save time and effort. See Rule-Based Certificate Mapping. 1. Open Assignment of External ID to Users (transaction EXTID_DN). 2. Switch to the edit mode. 3. Create a new entry. Specify the subject of the certificate as External ID. Using the example data, this is CN=P1234567. In the <User> field, provide an appropriate ABAP user, for example JOHNDOE. 4. Save the mapping. 5. Repeat the previous steps for all users that should be supported for the scenario. Back to Tasks [page 355] Back to Example Data [page 355] 3. Configure the Cloud Connector Prerequisites [page 356] Set up the Cloud Connector to Use the SNC Implementation [page 357] Create an RFC Hostname Mapping [page 357] Prerequisites ● The required security product for the SNC flavor that is used by your ABAP back-end systems, is installed on the Cloud Connector host. ● The Cloud Connector's system SNC identity is associated with the operating system user under which the Cloud Connector process is running. Note SAP note 2642538 provides a description how you can associate an SNC identity of the SAP Cryptographic Library with a user running an external program that uses JCo. If you use the SAP Cryptographic Library as SNC implementation, perform the corresponding steps for the Cloud Connector. When using a different product, contact the SNC library vendor for details. Back to Step [page 356] 356 PUBLIC SAP BTP Connectivity Connectivity
- 357. Set up the Cloud Connector to Use the SNC Implementation 1. In the Cloud Connector UI, choose Configuration from the main menu, select the On Premise tab, and go to the SNC section. 2. Provide the fully qualified name of the SNC library (the security product's shared library implementing the GSS API), the SNC name of the above system identity, and the desired quality of protection by choosing the Edit icon. For more information, see Initial Configuration (RFC) [page 321]. Note The example in Initial Configuration (RFC) [page 321] shows the library location if you use the SAP Secure Login Client as your SNC security product. In this case (as well as for some other security products), SNC My Name is optional, because the security product automatically uses the identity associated with the current operating system user under which the process is running, so you can leave that field empty. (Otherwise, in this example it should be filled with p:CN=SCC, OU=SAP CP Scenarios, O=Trust Community, C=DE.) We recommend that you enter Maximum Protection for <Quality of Protection>, if your security solution supports it, as it provides the best protection. 3. Choose Save and Close. Back to Step [page 356] Create an RFC Hostname Mapping 1. In the Access Control section of the Cloud Connector, create a hostname mapping corresponding to the cloud-side RFC destination. See Configure Access Control (RFC) [page 377]. 2. Make sure you choose RFC SNC as <Protocol> and ABAP System as <Back-end Type>. In the <SNC Partner Name> field, enter the ABAP system's SNC identitiy name, for example, p:CN=SID, O=Trust Community, C=DE. 3. Save your mapping. Back to Step [page 356] Back to Tasks [page 355] Back to Example Data [page 355] Related Information Secure Network Communications (SNC) Using the SAP Cryptographic Library for SNC Rule-Based Mapping of Certificates [page 358] Principal Propagation [page 121] (Cloud Foundry environment) Principal Propagation (Neo environment) SAP BTP Connectivity Connectivity PUBLIC 357
- 358. 1.2.2.3.1.3.3 Rule-Based Mapping of Certificates Learn how to efficiently map short-lived certificates to users in the ABAP server. To perform rule-based mapping of certificates in the ABAP server, proceed as follows: 1. Enter a dynamic parameter using transaction RZ11. 1. Enter the login/certificate_mapping_rulebased parameter. 2. Choose the Change Value button. 3. Enter the value 1. 4. Save the value. Note If dynamic parameters are disabled, enter the value using transaction RZ10 and restart the whole ABAP system. 2. Configure rule-based mapping 1. To create a sample certificate with the Cloud Connector, logon to the Cloud Connector UI and from the main menu, choose Configuration. In the System Certificate section, enter a sample CN name and download the sample certificate to the Downloads folder of your machine. 2. To import the sample certificate into the ABAP server, choose transaction CERTRULE and selectImport certificate. Note To access transaction CERTRULE, you need the corresponding authorizations (see: Assign Authorization Objects for Rule-based Mapping [page 359]). 3. To create explicit rule mappings, choose the Rule button. 4. Choose Save. Note When you save the changes and return to transaction CERTRULE, the sample certificate which you imported in Step 2b will not be saved. This is just a sample editor view to see the sample certificates and mappings. Related Information Rule-Based Certificate Mapping 358 PUBLIC SAP BTP Connectivity Connectivity
- 359. 1.2.2.3.1.3.3.1 Assign Authorization Objects for Rule-based Mapping Assign authorizations to access transaction CERTRULE. To access transaction CERTRULE, you need the following authorizations: ● CC control center: System administration (S_RZL_ADM) ○ Activity 03 grants display authorizations. ○ Activity 01 grants change authorizations. ● User Master Maintenance: User Groups (S_USER_GRP) ○ Activity 03 grants display authorizations. ○ Activity 02 grants change authorizations. ○ Class: enter the names of user groups for which the administrator can maintain explicit mappings. To assign these authorization objects, proceed as follows: 1. Create a Single Role using transaction PFCG. 2. To add the authorization objects S_RZL_ADM and S_USER_GRP, go to the Authorizations tab, choose Change Authorization data and select the Manually button . 3. To generate the profile, choose Generate and save the changes. 4. In the User tab, enter the user who should execute the transaction CERTRULE. 5. To match the generated profile to the users, choose User comparison . 1.2.2.3.1.4 Configure a Subject Pattern for Principal Propagation Define a pattern identifying the user for the subject of the generated short-lived X.509 certificate, as well as its validity period. Configure a Subject Pattern To configure such a pattern, choose Configuration On Premise and press the Edit icon in section Principal Propagation: SAP BTP Connectivity Connectivity PUBLIC 359
- 360. Subject Pattern Details Use either of the following procedures to define the subject's distinguished name (DN), for which the certificate will be issued: ● Enter the values in the subject pattern fields manually. ● Use the selection menu of the corresponding field to enter a predefined parameter (constant). Using the selection menu, you can assign values for the following parameters: ● ${name} ● ${mail} ● ${display_name} ● ${login_name} (as of Cloud Connector version 2.8.1.1) Note If the token provided by the Identity Provider contains additional values that are stored in attributes with different names, but you still want to use it for the subject pattern, you can edit the variable name to place the corresponding attribute value in the subject accordingly. For example, provide ${email}, if a SAML assertion uses email instead of providing mail. When using a subaccount in the Cloud Foundry environment: As of version 2.12.5, the Cloud Connector also offers direct access to custom variables injected in the JWT (JSON Web token) by SAP BTP Authorization & Trust Management that were taken over from a SAML assertion. The values for these variables are provided by the trusted Identiy Provider in the token which is passed to the Cloud Connector and specifies the user that has logged on to the cloud application. By default, the following attributes are provided: ● <CN>: (common name) – the name of the certificate owner ● <EMAIL>: (e-mail address) - the e-mail address of the certificate owner ● <L>: (locality) – the certificate owner's location ● <O>: (organization) – the certificate owner's organization or company 360 PUBLIC SAP BTP Connectivity Connectivity
- 361. ● <OU>: (name of organizational unit) – the organizational unit to which the certificate owner belongs ● <ST>: (state of residence) – the state in which the certificate issuer resides ● <C>: (country of residence) – the country in which the certificate owner resides ● <Expiration Tolerance (h)>: The length of time in hours, that an application can use a principal issued for a user after the token from cloud side has expired. ● <Certificate Validity (min)>: The length of time in minutes, that a certificate generated for principal propagation can authenticate against the back end. You can reuse a previously generated certificate to improve performance. Sample Certificate By choosing Generate Sample Certificate you can create a sample certificate that looks like one of the short- lived certificates created at runtime. You can use this certificate to, for example, generate user mapping rules in the target system, via transaction CERTRULE in an ABAP system. If your subject pattern contains variable fields, a wizard lets you provide meaningful values for each of them and eventually you can save the sample certificate in DER format. Related Information Server Certificate Authentication [page 65] 1.2.2.3.1.5 Configure a Secure Login Server Configuration steps for Java SLS support. SAP BTP Connectivity Connectivity PUBLIC 361
- 362. Content Overview [page 362] Requirements [page 363] Implementation [page 363] Overview The Cloud Connector can use on-the-fly generated X.509 user certificates to log in to on-premise systems if the external user session is authenticated (for example by means of SAML). If you do not want to use the built- in certification authority (CA) functionality of the Cloud Connector (for example because of security considerations), you can connect SAP SSO 2.0 Secure Login Server (SLS). SLS is a Java application running on AS JAVA 7.20 or higher, which provides interfaces for certificate enrollment. SLS supports the following formats: ● HTTPS ● REST ● JSON ● PKCS#10/PKCS#7 Note Any enrollment requires a successful user or client authentication, which can be a single, multiple or even a multi factor authentication. The following schemes are supported: ● LDAP/ADS ● RADIUS ● SAP SSO OTP ● ABAP RFC ● Kerberos/SPNego ● X.509 TLS Client Authentication SLS lets you define arbitrary enrollment profiles, each with a unique profile UID in its URL, and with a configurable authentication and certificate generation. Back to Content [page 362] 362 PUBLIC SAP BTP Connectivity Connectivity
- 363. Requirements For user certification, SLS must provide a profile that adheres to the following: ● Cloud Connector client authentication by its X.509 service certificate ● Cloud Connector service certificate and SLS may live in different PKIs ● Cloud Connector hands over the full user´s certificate subject name With SAP SSO 2.0 SP06, SLS provides the following required features: ● TLS Client Authentication-based enrollment with SecureLoginModuleUserDelegationWithSSL (available since SP04) ● multi-PKI support is implemented by all standard components of Application Server (AS) JAVA, AS ABAP, HANA, by importing trusted root CA certificates ● SLS allows PKCS10:SUBJECT in a profile´s certificate configuration (SP06) Back to Content [page 362] Implementation INSTALLATION Follow the standard installation procedures for SLS. This includes the initial setup of a PKI (public key infrastructure). Note SLS allows you to set up one or more own PKIs with Root CA, User CA, and so on. You can also import CAs as PKCS#12 file or use a hardware security module (HSM) as "External User CA". Note You should only use HTTPS connections for any communication with SLS. AS JAVA / ICM supports TLS, and the default configuration comes with a self-signed sever certificate. You may use SLS to replace this certificate by a PKI certificate. CONFIGURATION SSL Ports 1. Open the NetWeaver Administrator, choose Configuration SSL and define a new port with Client Authentication Mode = REQUIRED. Note You may also define another port with Client Authentication Mode = Do not request if you did not do so yet. 2. Import the root CA of the PKI that issued your Cloud Connector service certificate. SAP BTP Connectivity Connectivity PUBLIC 363
- 364. 3. Save the configuration and restart the Internet Communication Manager (ICM). Authentication Policy 1. Open the NetWeaver Administrator (NWA, https:/ /<host:port>/nwa). 2. From the top-level menu, choose Configuration Authentication and Single Sign-On . 3. In the Policy Configuration table, switch to Type = Custom. 4. Choose Add to create a new policy and assign it a name, for example, SecureLoginCloudConnector. 5. Open Edit mode. 6. In the Details section of the authentication configuration, choose Authentication Stack Login Modules and add SecureLoginModuleUserDelegationWithSSL. 7. In <Rule1.subjectName> and <Rule1.issuerName>, enter the respective certificate names of your Cloud Connector service certificate. 8. In the Details section of the authentication configuration, choose Properties and add the property UserNameMapping with value VirtualUser. 9. Save the policy. Client Authentication Profile 1. Open the SLS Administration Console (SLAC, https:/ /host:port/slac). 2. From the top-level menu, choose Profile Management Authentication Profiles . 3. Create a new profile with Client Type = Secure Login Client and assign it a name, for example, Cloud Connector User Certificates. 4. Choose User Authentication Use Policy Configuration and select Policy Configuration Name = SecureLoginCloudConnector. 5. Edit all required fields in the wizard according to your requirements. 6. Save your entries. 7. Select the new profile and open Edit mode. 8. Choose Certificate Configuration Certificate Name and Alternative Names and set Appendix Subject Name = (PKCS10:SUBJECT). 9. Leave all other fields in Certificate Name and Alternative Names empty. 10. On the Enrollment Configuration page, make sure that the <Enrollment URL> has the correct value, otherwise edit and fix it: 1. full DNS name 2. port with TLS Client Authentication (see port number in NWA SSL Configuration). 11. Save your entries. User Profile Group 1. Open the SLS Administration Console (SLAC, https:/ /host:port/slac). 2. Go to the top level menu and choose Profile Management User Profile Groups . 3. Create a new profile group, make sure the <Policy URL> has the correct value: 1. Full DNS name 2. Port without TLS Client Authentication (see port number in NWA SSL Configuration). 4. In tab Profiles, add the profile Cloud Connector User Certificates. 5. Save your entries. Root CA Certificate 364 PUBLIC SAP BTP Connectivity Connectivity
- 365. 1. Open SLS Administration Console (SLAC, https:/ /host:port/slac). 2. Go to the top level menu and choose Certificate Management. 3. Select the Root CA certificate you are using in your profile. 4. Choose Export entry X.509 Certificate and download the certificate file. Cloud Connector Follow the standard installation procedure of the Cloud Connector and configure SLS support: 1. Enter the policy URL that points to the SLS user profile group. 2. Select the profile, for example, Cloud Connector User Certificates. 3. Import the Root CA certificate of SLS into the Cloud Connector´s Trust Store. On-Premise Target Systems Follow the standard configuration procedure for Cloud Connector support in the corresponding target system and configure SLS support. To do so, import the Root CA certificate of SLS into the system´s truststore: ● AS ABAP: choose transaction STRUST and follow the steps in Maintaining the SSL Server PSE's Certificate List. ● AS Java: open the Netweaver Administrator and follow the steps described in Configuring the SSL Key Pair and Trusted X.509 Certificates. Back to Content [page 362] 1.2.2.3.1.6 Configure Kerberos Context The Cloud Connector allows you to propagate users authenticated in SAP BTP via Kerberos against backend systems. It uses the Service For User and Constrained Delegation protocol extension of Kerberos. Note This feature is not supported for ABAP backend systems. In this case, you can use the certificate-based principal propagation, see Configure a CA Certificate for Principal Propagation [page 344]. The Key Distribution Center (KDC) is used for exchanging messages in order to retrieve Kerberos tokens for a certain user and backend system. For more information, see Kerberos Protocol Extensions: Service for User and Constrained Delegation Protocol . SAP BTP Connectivity Connectivity PUBLIC 365
- 366. 1. An SAP BTP application calls a backend system via the Cloud Connector. 2. The Cloud Connector calls the KDC to obtain a Kerberos token for the user propagated from the Cloud Connector. 3. The obtained Kerberos token is sent as a credential to the backend system. Procedure 1. Choose Configuration from the main menu. 2. From the Kerberos section of the On Premise tab, choose Edit. 3. Enter the name of your Kerberos realm. 4. Upload a KEYTAB file that contains the secret keys of your service user. The KEYTAB file should contain the rc4-hmac key for your user. 5. Enter the name of the service user to be used for communication with the KDC. This user should be allowed to request Kerberos tokens for other users for the backend systems that you are going to access. 6. In the <KDC Hosts> field (press Add to display the field), enter the host name of your KDC using the format <host>:<port>. The port is optional; if you leave it empty, the default, 88, is used. 7. Choose Save. 366 PUBLIC SAP BTP Connectivity Connectivity
- 367. Example You have a backend system protected with SPNego authentication in your corporate network. You want to call it from a cloud application while preserving the identity of a cloud-authenticated user. Define the following: ● A connectivity destination in SAP BTP, with ProxyType = OnPremise. ● A system mapping made in the Cloud Connector. (Choose Cloud to On Premise from your subaccount menu, Go to tab Access Control Add , and for Principal Type, select Kerberos.) ● Kerberos configuration in the Cloud Connector, where the service user is allowed to delegate calls for your backend host service. Result: When you now call a backend system, the Cloud Connector obtains an SPNego token from your KDC for the cloud-authenticated user. This token is sent along with the request to the back end, so that it can authenticate the user and the identity to be preserved. Related Information Set Up Trust for Principal Propagation [page 341] 1.2.2.3.1.7 Configuring Principal Propagation to SAP NetWeaver AS for Java Find step-by-step instructions on how to set up an application server for Java (AS Java) to enable principal propagation for HTTPS. Prerequisites To perform the following steps, you must have the corresponding administrator authorizations in AS Java (SAP NetWeaver Administrator) as well as an administrator user for the Cloud Connector. SAP BTP Connectivity Connectivity PUBLIC 367
- 368. Configure AS Java to Trust the Cloud Connector's System Certificate Procedure 1. Go to SAP NetWeaver Administrator Certificates and Keys and import the Cloud Connector's system certificate into the Trusted CAs keystore view. See Importing Certificate and Key From the File System. 2. Configure the Internet Communication Manager (ICM) to trust the system certificate for principal propagation. a. Add a new SSL access point. See Adding New SSL Access Points. b. Generate a certificate signing request and send it to the CA of your choice. See Configuration of the AS Java Keystore Views for SSL. c. Import the certificates and save the configuration. Import the certificate signing response, the root X.509 certificate of the trusted CA, and the Cloud Connector's system certificate into the new SSL access point from step 2a. Save the configuration and restart the ICM. See Configuring the SSL Key Pair and Trusted X.509 Certificates. d. Test the SSL connection. See Testing the SSL Connection. Define Rules for User Mapping Procedure 1. Add the ClientCertLoginModule to the policy configuration that the Cloud Connector connects to. See Configuring the Login Module on the AS Java. 2. Define the rules to map users authenticated with their certificate to users that exist in the User Management Engine. See Using Rules for User Mapping in Client Certificate Login Module. ○ To map the user ID of the certificate’s subject name field to users, see Using Rules Based on Client Certificate Subject Names. ○ To map the user ID based on rules for the certificate V3 extension SubjectAlternativeName, see Using Rules Based on Client Certificate V3 Extensions. ○ To use client certificate filters, see Defining Rules for Filtering Client Certificates. Related Information Configuring Transport Layer Security on SAP NetWeaver AS for Java Using X.509 Client Certificates Configure Principal Propagation for HTTPS [page 347] 368 PUBLIC SAP BTP Connectivity Connectivity
- 369. 1.2.2.4 Configure Access Control Specify the backend systems that can be accessed by your cloud applications. To allow your cloud applications to access a certain backend system on the intranet, you must specify this system in the Cloud Connector. The procedure is specific to the protocol that you are using for communication. Find the detailed configuration steps for each communication protocol here: Configure Access Control (HTTP) [page 370] Configure Access Control (RFC) [page 377] Configure Access Control (LDAP) [page 383] Configure Access Control (TCP) [page 386] Copy Access Control Settings When you add new subaccounts, you can copy the complete access control settings from another subaccount on the same Cloud Connector. You can also do it any time later by using the import/export mechanism provided by the Cloud Connector. Export Access Control Settings 1. From your subaccount menu, choose Cloud To On-Premise and select the tab Access Control. 2. To store the current settings in a ZIP file, choose Download icon in the upper-right corner. 3. You can later import this file into a different Cloud Connector. Import Access Control Settings There are two locations from which you can import access control settings: ● A file that was previously exported from a Cloud Connector ● A different subaccount on the same Cloud Connector SAP BTP Connectivity Connectivity PUBLIC 369
- 370. Two additional options define the behavior of the import: ● Overwrite: Select this checkbox if you want to replace existing system mappings with imported ones. Do not select this checkbox if you want to keep existing mappings and only import the ones that are not yet available (default). Note A system mapping is uniquely identified by the combination of virtual host and port. ● Include Resources: When this checkbox is selected (default), the resources that belong to an imported system are also imported. Otherwise no resources are imported, that is, imported system mappings do not expose any resources. Related Information Configure Access Control (HTTP) [page 370] Configure Access Control (RFC) [page 377] Configure Access Control (LDAP) [page 383] Configure Access Control (TCP) [page 386] Configure Accessible Resources [page 389] Configure Domain Mappings for Cookies [page 493] 1.2.2.4.1 Configure Access Control (HTTP) Specify the backend systems that can be accessed by your cloud applications using HTTP. To allow your cloud applications to access a certain backend system on the intranet via HTTP, you must specify this system in the Cloud Connector. 370 PUBLIC SAP BTP Connectivity Connectivity
- 371. Note Make sure that also redirect locations are configured as internal hosts. If the target server responds with a redirect HTTP status code (30x), the cloud-side HTTP client usually sends the redirect over the Cloud Connector as well. The Cloud Connector runtime then performs a reverse lookup to rewrite the location header that indicates where to route the redirected request. If the redirect location is ambiguous (that is, several mappings point to the same internal host and port), the first one found is used. If none is found, the location header stays untouched. Tasks Expose Intranet Systems [page 371] Limit the Accessible Services for HTTP(S) [page 375] Activate or Suspend Resources [page 376] Expose Intranet Systems Insert a new entry in the Cloud Connector access control management: 1. Choose Cloud To On Premise from your Subaccount menu. 2. Choose Add. A wizard will open and ask for the required values. 3. Backend Type: Select the description that matches best the addressed backend system. When you are done, choose Next. 4. Protocol: This field allows you to decide whether the Cloud Connector should use HTTP or HTTPS for the connection to the backend system. Note that this is completely independent from the setting on cloud side. Thus, even if the HTTP destination on cloud side specifies "http://" in its URL, you can select HTTPS. This way, you are ensured that the entire connection from the cloud application to the actual backend system (provided through the SSL tunnel) is SSL-encrypted. The only prerequisite is that the SAP BTP Connectivity Connectivity PUBLIC 371
- 372. backend system supports HTTPS on that port. For more information, see Initial Configuration (HTTP) [page 319]. ○ If you specify HTTPS and there is a "system certificate" imported in the Cloud Connector, the latter attempts to use that certificate for performing a client-certificate-based logon to the backend system. ○ If there is no system certificate imported, the Cloud Connector opens an HTTPS connection without client certificate. 5. Internal Host and Internal Port specify the actual host and port under which the target system can be reached within the intranet. It needs to be an existing network address that can be resolved on the intranet and has network visibility for the Cloud Connector without any proxy. Cloud Connector will try to forward the request to the network address specified by the internal host and port, so this address needs to be real. 6. Virtual Host specifies the host name exactly as it is specified as the URL property in the HTTP destination configuration in SAP BTP See: Create HTTP Destinations [page 43] (Cloud Foundry environment) The virtual host can be a fake name and does not need to exist. The Virtual Port allows you to distinguish between different entry points of your backend system, for example, HTTP/80 and HTTPS/443, and have different sets of access control settings for them. For example, some noncritical resources may be accessed by HTTP, while some other critical resources are to be called using HTTPS only. The fields will be prepopulated with the values of the Internal Host and Internal Port. In case you don't modify them, you must provide your internal host and port also in the cloud-side destination configuration or in the URL used for your favorite HTTP client. 372 PUBLIC SAP BTP Connectivity Connectivity
- 373. 7. Principal Type defines what kind of principal is used when configuring a destination on the cloud side using this system mapping with authentication type Principal Propagation. Regardless of what you choose, make sure that the general configuration for the principal type has been done to make it work correctly. For destinations using different authentication types, this setting is ignored. If you choose None as principal type, it is not possible to use principal propagation to this system. Note There are two variants of a principal type X.509 certificate: X.509 Certificate (General Usage) and X.509 Certificate (Strict Usage). The latter was introduced with Cloud Connector 2.11. If the cloud side sends a principal, these variants behave identically. If no principal is sent, the injected HTTP headers indicate that the system certificate used for trust is not used for authentication. The recommended variant is X.509 Certificate (Strict Usage) as this lets you use principal propagation and basic authentication over the same access control entry, regardless of the logon order settings in the target system. For more information on principal propagation, see Configuring Principal Propagation [page 340]. 8. Host In Request Header lets you define, which host is used in the host header that is sent to the target server. By choosing Use Internal Host, the actual host name is used. When choosing Use Virtual Host, the virtual host is used. In the first case, the virtual host is still sent via the X-Forwarded-Host header. SAP BTP Connectivity Connectivity PUBLIC 373
- 374. 9. You can enter an optional description at this stage. The respective description will be shown when pressing the Info button of the access control entry (table Mapping Virtual to Internal System). 10. The summary shows information about the system to be stored and when saving the host mapping, you can trigger a ping from the Cloud Connector to the internal host, using the Check availability of internal host checkbox. This allows you to make sure the Cloud Connector can indeed access the internal system, and allows you to catch basic things, such as spelling mistakes or firewall problems between the Cloud Connector and the internal host. If the ping to the internal host is successful, the Cloud Connector saves the mapping without any remark. If it fails, a warning will pop up, that the host is not reachable. Details for the reason are available in the log files. You can execute such a check for all selected systems in the Access Control overview by pressing the button (Check availability...) in column Actions. 11. Optional: You can later edit such a system mapping (via Edit) to make the Cloud Connector route the requests for sales-system.cloud:443 to a different backend system. This can be useful if the system is currently down and there is a back-up system that can serve these requests in the meantime. However, you 374 PUBLIC SAP BTP Connectivity Connectivity
- 375. cannot edit the virtual name of this system mapping. If you want to use a different fictional host name in your cloud application, you must delete the mapping and create a new one. Back to Tasks [page 371] Limit the Accessible Services for HTTP(S) In addition to allowing access to a particular host and port, you also must specify which URL paths (Resources) are allowed to be invoked on that host. The Cloud Connector uses very strict allowlists for its access control. Only those URLs for which you explicitly granted access are allowed. All other HTTP(S) requests are denied by the Cloud Connector. To define the permitted URLs for a particular backend system, choose the line corresponding to that backend system and choose Add in section Resources Accessible On... below. A dialog appears prompting you to enter the specific URL path that you want to allow to be invoked. SAP BTP Connectivity Connectivity PUBLIC 375
- 376. The Cloud Connector checks that the path part of the URL (up to but not including a possible question mark (?) that may denote the start of optional CGI-style query parameters) is exactly as specified in the configuration. If it is not, the request is denied. If you select option Path and all sub-paths, the Cloud Connector allows all requests for which the URL path (not considering any query parameters) starts with the specified string. The Active checkbox lets you specify, if that resource is initially enabled or disabled. See the section below for more information on enabled and disabled resources. The WebSocket Upgrade checkbox lets you specify, whether that resource allows a protocol upgrade. Back to Tasks [page 371] Activate or Suspend Resources In some cases, it is useful for testing purposes to temporarily disable certain resources without having to delete them from the configuration. This allows you to easily reprovide access to these resources at a later point of time without having to type in everything once again. ● To suspend a resource, select it and choose the Suspend button: The status icon turns red, and from now on, the Cloud Connector will deny all requests coming in for this resource. ● To activate the resource again, select it and choose the Activate button. ● By choosing Allow WebSocket upgrade/Disallow WebSocket upgrade this is possible for the protocol upgrade setting as well. ● It is also possible to mark multiple lines and then suspend or activate all of them in one go by clicking the Activate/Suspend icons in the top row. The same is true for the corresponding Allow WebSocket upgrade/ Disallow WebSocket icons. Examples: ● /production/accounting and Path only (sub-paths are excluded) are selected. Only requests of the form GET /production/accounting or GET /production/accounting? name1=value1&name2=value2... are allowed. (GET can also be replaced by POST, PUT, DELETE, and so on.) ● /production/accounting and Path and all sub-paths are selected. All requests of the form GET / production/accounting-plus-some-more-stuff-here?name1=value1... are allowed. ● / and Path and all sub-paths are selected. All requests to this server are allowed. Back to Tasks [page 371] 376 PUBLIC SAP BTP Connectivity Connectivity
- 377. Related Information Configure Domain Mappings for Cookies [page 493] Consume Backend Systems (Java Web or Java EE 6 Web Profile) 1.2.2.4.2 Configure Access Control (RFC) Specify the backend systems that can be accessed by your cloud applications using RFC. Tasks Expose Intranet Systems [page 377] Limit the Accessible Resources for RFC [page 382] Expose Intranet Systems To allow your cloud applications to access a certain backend system on the intranet, insert a new entry in the Cloud Connector Access Control management. 1. Choose Cloud To On-Premise from your Subaccount menu and go to tab Access Control. 2. Choose Add. 3. Backend Type: Select the backend system type ( ABAP System or SAP Gateway for RFC). 4. Choose Next. 5. Protocol: Choose RFC or RFC SNC for connecting to the backend system. SAP BTP Connectivity Connectivity PUBLIC 377
- 378. Note The value RFC SNC is independent from your settings on the cloud side, since it only specifies the communication beween Cloud Connector and backend system. Using RFC SNC, you can ensure that the entire connection from the cloud application to the actual backend system (provided by the SSL tunnel) is secured, partly with SSL and partly with SNC. For more information, see Initial Configuration (RFC) [page 321]. Note ○ The back end must be properly configured to support SNC connections. ○ SNC configuration must be provided in the Cloud Connector. 6. Choose Next. 7. Choose whether you want to configure a load balancing logon or connect to a specific application server. 8. Specify the parameters of the backend system. It needs to be an existing network address that can be resolved on the intranet and has network visibility for the Cloud Connector. If this is only possible using a valid SAProuter, specify the router in the respective field. The Cloud Connector will try to establish a connection to this system, so the address has to be real. ○ When using a load-balancing configuration, the Message Server specifies the message server of the ABAP system. The system ID is a three-char identifier that is also found in the SAP Logon configuration. Alternatively, it's possible to directly specify the message server port in the System ID field. 378 PUBLIC SAP BTP Connectivity Connectivity
- 379. ○ When using direct logon, the Application Server specifies one application server of the ABAP system. The instance number is a two-digit number that is also found in the SAP Logon configuration. Alternatively, it's possible to directly specify the gateway port in the Instance Number field. 9. Optional: You can virtualize the system information in case you like to hide your internal host names from the cloud. The virtual information can be a fake name which does not need to exist. The fields will be pre- populated with the values of the configuration provided in Message Server and System ID, or Application Server and Instance Number. ○ Virtual Message Server - specifies the host name exactly as specified as the jco.client.mshost property in the RFC destination configuration in the cloud. The Virtual System ID allows you to distinguish between different entry points of your backend system that have different sets of access control settings. The value needs to be the same like for the jco.client.r3name property in the RFC destination configuration in the cloud. SAP BTP Connectivity Connectivity PUBLIC 379
- 380. ○ Virtual Application Server - it specifies the host name exactly as specified as the jco.client.ashost property in the RFC destination configuration in the cloud. The Virtual Instance Number allows you to distinguish between different entry points of your backend system that have different sets of access control settings. The value needs to be the same like for the jco.client.sysnr property in the RFC destination configuration in the cloud. 10. This step is only relevant if you have chosen RFC SNC. The <Principal Type> field defines what kind of principal is used when configuring a destination on the cloud side using this system mapping with authentication type Principal Propagation. No matter what you choose, make sure that the general configuration for the <Principal Type> has been done to make it work correctly. For destinations using different authentication types, this setting is ignored. In case you choose None as <Principal Type>, it is not possible to apply principal propagation to this system. Note If you use an RFC connection, you cannot choose between different principal types. Only the X.509 certificate is supported. You need an SNC-enabled backend connection to use it. For RFC, the two X. 509 certificate variants X.509 certificate (general usage) and X.509 certificate (strict usage) do not differ in behavior. For more information on principal propagation, see Configuring Principal Propagation [page 340]. 11. SNC Partner Name: This step will only come up if you have chosen RFC SNC. The SNC partner name needs to contain the correct SNC identification of the target system. 380 PUBLIC SAP BTP Connectivity Connectivity
- 381. 12. Mapping Virtual to Internal System: You can enter an optional description at this stage. The respective description will be shown as a rich tooltip when the mouse hovers over the entries of the virtual host column (table ). 13. The summary shows information about the system to be stored. When saving the system mapping, you can trigger a ping from the Cloud Connector to the internal host, using the Check availability of internal host checkbox. This allows you to make sure the Cloud Connector can indeed access the internal system, and allows you to catch basic things, such as spelling mistakes or firewall problems between the Cloud Connector and the internal host. If the ping to the internal host is successful, the Cloud Connector saves the mapping without any remark. If it fails, a warning will pop up, that the host is not reachable. Details for the reason are available in the log files. You can execute such a check at any time later for all selected systems in the Access Control overview. 14. Optional: You can later edit a system mapping (choose Edit) to make the Cloud Connector route the requests for sales-system.cloud:sapgw42 to a different backend system. This can be useful if the system is currently down and there is a back-up system that can serve these requests in the meantime. However, you cannot edit the virtual name of this system mapping. If you want to use a different fictional host name in your cloud application, you must delete the mapping and create a new one. Here, you can also change the Principal Type to None in case you don't want to allow principal propagation to a certain system. SAP BTP Connectivity Connectivity PUBLIC 381
- 382. 15. Optional. You can later edit a system mapping to add more protection to your system when using RFC via theCloud Connector, by restricting the mapping to specified clients and users: in column Actions, choose the button Maintain Authority Lists (only RFC) to open an allowlist/blocklist dialog. In section Authority Client Allowlist, enter all clients of the corresponding system in the field <Client ID> that you want to allow to use the Cloud Connector connection. In section Authority User Blocklist, press the button Add a user authority (+) to enter all users you want to exclude from this connection. Each user must be assigned to a specified client. When you are done, press Save. Note This function applies for RFC/RFC SNC only. Back to Tasks [page 377] Limit the Accessible Resources for RFC In addition to allowing access to a particular host and port, you also must specify which function modules (Resources) are allowed to be invoked on that host. You can enter an optional description at this stage. The 382 PUBLIC SAP BTP Connectivity Connectivity
- 383. Cloud Connector uses very strict allowlists for its access control. Besides internally used infrastructure function modules, only function modules for which you explicitly granted access are allowed. 1. To define the permitted function modules for a particular backend system, choose the row corresponding to that backend system and press Add in section Resources Accessible On... below. A dialog appears, prompting you to enter the specific function module name whose invoking you want to allow. 2. The Cloud Connector checks that the function module name of an incoming request is exactly as specified in the configuration. If it is not, the request is denied. 3. If you select the Prefix option, the Cloud Connector allows all incoming requests, for which the function module name begins with the specified string. 4. The Active checkbox allows you to specify whether that resource should be initially enabled or disabled. Back to Tasks [page 377] 1.2.2.4.3 Configure Access Control (LDAP) Add a specified system mapping to the Cloud Connector if you want to use an on-premise LDAP server or user authentication in your cloud application. To allow your cloud applications to access an on-premise LDAP server, insert a new entry in the Cloud Connector access control management. 1. Choose Cloud To On-Premise from your Subaccount menu. 2. Choose Add (+). A wizard opens and asks for the required values. 3. Backend Type: Select Non-SAP System from the drop down list. When you are done, choose Next. SAP BTP Connectivity Connectivity PUBLIC 383
- 384. 4. Protocol: Select LDAP or LDAPS for the connection to the backend system. When you are done, choose Next. 5. Internal Host and Internal Port: specify the host and port under which the target system can be reached within the intranet. It needs to be an existing network address that can be resolved on the intranet and has network visibility for the Cloud Connector. The Cloud Connector will try to forward the request to the network address specified by the internal host and port, so this address needs to be real. 6. Enter a Virtual Host and Virtual Port. The virtual host can be a fake name and does not need to exist. The fields are pre-populated with the values of the Internal Host and Internal Port. 7. You can enter an optional description at this stage. The respective description will be shown as a tooltip when you press the button Show Details in column Actions of the Mapping Virtual To Internal System overview. 384 PUBLIC SAP BTP Connectivity Connectivity
- 385. 8. The summary shows information about the system to be stored. When saving the host mapping, you can trigger a ping from the Cloud Connector to the internal host, using the Check Internal Host check box. This allows you to make sure the Cloud Connector can indeed access the internal system. Also, you can catch basic things, such as spelling mistakes or firewall problems between the Cloud Connector and the internal host. If the ping to the internal host is successful, the Cloud Connector saves the mapping without any remark. If it fails, a warning is displayed in column Check Result, that the host is not reachable. Details for the reason are available in the log files. You can execute such a check at any time later for all selected systems in the Mapping Virtual To Internal System overview by pressing Check Availability of Internal Host in column Actions. 9. Optional: You can later edit the system mapping (by choosing Edit) to make the Cloud Connector route the requests to a different LDAP server. This can be useful if the system is currently down and there is a back- up LDAP server that can serve these requests in the meantime. However, you cannot edit the virtual name of this system mapping. If you want to use a different fictional host name in your cloud application, you have to delete the mapping and create a new one. SAP BTP Connectivity Connectivity PUBLIC 385
- 386. 1.2.2.4.4 Configure Access Control (TCP) Add a specified system mapping to the Cloud Connector if you want to use the TCP protocol for communication with a backend system. To allow your cloud applications to access a certain backend system on the intranet via TCP, insert a new entry in the Cloud Connector access control management. 1. Choose Cloud To On-Premise from your Subaccount menu. 2. Choose Add (+). A wizard opens and asks for the required values. 3. Backend Type: Select Non-SAP System from the drop-down list. When you are done, choose Next. 4. Protocol: Select TCP or TCP SSL for the connection to the backend system. When choosing TCP, you can perform an end-to-end TLS handshake from the cloud client to the backend. If the cloud-side client is using plain communication, but you still need to encrypt the hop between Cloud Connector and the backend, choose TCP SSL. When you are done, choose Next. Note When selecting TCP as protocol, the following warning message is displayed: TCP connections can pose a security risk by permitting unmonitored traffic. Ensure only 386 PUBLIC SAP BTP Connectivity Connectivity
- 387. trustworthy applications have access. The reason is that using plain TCP, the Cloud Connector cannot see or log any detail information about the calls. Therefore, in contrast to HTTP or RFC (both running on top of TCP), the Cloud Connector cannot check the validity of a request. To minimize this risk, make sure you ○ deploy only trusted applications on SAP BTP. ○ configure an application allowlist in the Cloud Connector, see Set Up Trust for Principal Propagation [page 341]. ○ take the recommended security measures for your SAP BTP (sub)account. See section Security in the SAP BTP documentation. 5. Internal Host and Port or Port Range: specify the host and port under which the target system can be reached within the intranet. It needs to be an existing network address that can be resolved on the intranet and has network visibility for the Cloud Connector. The Cloud Connector will try to forward the request to the network address specified by the internal host and port. That is why this address needs to be real. For TCP and TCP SSL, you can also specify a port range through its lower and upper limit, separated by a hyphen. 6. Enter a Virtual Host and Virtual Port. The virtual host can be a fake name and does not need to exist. The fields are prepopulated with the values of the Internal Host and Port or Port Range. SAP BTP Connectivity Connectivity PUBLIC 387
- 388. 7. You can enter an optional description at this stage. The respective description will be shown as a tooltip when you press the button Show Details in column Actions of the Mapping Virtual To Internal System overview. 8. The summary shows information about the system to be stored. When saving the host mapping, you can trigger a ping from the Cloud Connector to the internal host, using the Check Internal Host checkbox. This allows you to make sure the Cloud Connector can indeed access the internal system. Also, you can catch basic things, such as spelling mistakes or firewall problems between the Cloud Connector and the internal host. If the ping to the internal host is successful, the Cloud Connector saves the mapping without any remark. If it fails, a warning is displayed in column Check Result, that the host is not reachable. Details for the reason are available in the log files. You can execute such a check at any time later for all selected systems in the Mapping Virtual To Internal System overview by pressing Check Availability of Internal Host in column Actions. 9. Optional: You can later edit the system mapping (by choosing Edit) to make the Cloud Connector route the requests to a different backend system. This can be useful if the system is currently down and there is a backup system that can serve these requests in the meantime. However, you cannot edit the virtual name nor port of this system mapping. If you want to use a different fictional host name in your cloud application, you must delete the mapping and create a new one. The same goes for port ranges. If a port range needs to be changed, you must delete the mapping and create it again with the desired port range. 388 PUBLIC SAP BTP Connectivity Connectivity
- 389. 1.2.2.4.5 Configure Accessible Resources Configure backend systems and resources in the Cloud Connector, to make them available for a cloud application. Tasks Map Systems and Limit Access [page 389] Use Scenarios for Resources [page 391] Map Systems and Limit Access Initially, after installing a new Cloud Connector, no network systems or resources are exposed to the cloud. You must configure each system and resource used by applications of the connected cloud subaccount. To do this, choose Cloud To On Premise from your subaccount menu and go to tab Access Control: SAP BTP Connectivity Connectivity PUBLIC 389
- 390. The Cloud Connector supports any type of system (SAP or non-SAP system) that can be called via one of the supported protocols. For example, a convenient way to access an ABAP system from a cloud application is via SAP NetWeaver Gateway, as it allows the consumption of ABAP content via HTTP and open standards. ● For systems using HTTP communication, see: Configure Access Control (HTTP) [page 370]. ● For information on configuring RFC resources, see: Configure Access Control (RFC) [page 377]. We recommend that you limit the access to backend services and resources. Instead of configuring a system and granting access to all its resources, grant access only to the resources needed by the cloud application. For example, define access to an HTTP service by specifying the service URL root path and allowing access to all its subpaths. When configuring an on-premise system, you can define a virtual host and port for the specified system. The virtual host name and port represent the fully qualified domain name of the related system in the cloud. We recommend that you use the virtual host name/port mapping to prevent leaking information about a system's physical machine name and port to the cloud. 390 PUBLIC SAP BTP Connectivity Connectivity
- 391. Back to Tasks [page 389] Use Scenarios for Resources As of version 2.12, the Cloud Connector lets you define a set of resources as a scenario that you can export, and import into another Cloud Connector. SAP BTP Connectivity Connectivity PUBLIC 391
- 392. Scenarios are useful if you provide an application to many consumers, which invokes a large number of resources in an on-premise system. In this case, you must expose a system on your Cloud Connector that covers all required resources, which increases the risk of incorrect configuration. Define and Export a Scenario [page 392] Import a Scenario [page 392] Remove a Scenario [page 393] Define and Export a Scenario If you, as application owner, have implemented and tested a scenario, and configured a Cloud Connector accordingly, you can define the scenario as follows: 1. Choose the Export Scenario button. 2. In the dialog, select the resources that belong to the scenario. 3. In the field <Scenario Name>, choose a descriptive name, under which the set of resources can be identified in the consuming Cloud Connector. 4. Choose Export to store the scenario. Note For applications provided by SAP, default scenario definitions may be available. To verify this, check the corresponding application documentation. Back to Use Scenarios for Resources [page 391] Back to Tasks [page 389] Import a Scenario 392 PUBLIC SAP BTP Connectivity Connectivity
- 393. As an administrator taking care for a scenario configuration in some other Cloud Connector, perform the following steps: 1. Choose the Import Scenario button to add all required resources to the desired access control entry. 2. In the dialog, navigate to the folder of the archive that contains the scenario definition. 3. Choose Import. The resources of the scenario are merged with the existing set of resources which are already available in the access control entry. All resources belonging to a scenario get an additional scenario icon in their status. When hovering over it, the assigned scenario(s) of this resource are listed. Back to Use Scenarios for Resources [page 391] Back to Tasks [page 389] Remove a Scenario To remove a scenario: 1. Choose the Remove Scenario button. 2. In the dialog, choose the scenario(s) you want to remove. 3. Choose Remove to remove all resources associated with the chosen entry from the access control entry. Resources that existed before, or are assigned to another scenario as well, are not removed. SAP BTP Connectivity Connectivity PUBLIC 393
- 394. Back to Use Scenarios for Resources [page 391] Back to Tasks [page 389] 1.2.2.5 Configuration REST APIs You can use a set of APIs to perform the basic setup of the Cloud Connector. Context As of version 2.11, the Cloud Connector provides several REST APIs that let you configure a newly installed Cloud Connector. The configuration options correspond to the following steps: ● Initial Configuration [page 312] ● Managing Subaccounts [page 328] ● Configure Access Control [page 369] ● Master and Shadow Administration [page 511] All configuration APIs start with the following string: /api/v1/configuration. Note Use the same host and port for the REST APIs that you use to access the Cloud Connector. 394 PUBLIC SAP BTP Connectivity Connectivity
- 395. Prerequisites ● After installing the Cloud Connector, you have changed the initial password. ● You have specified the high availability role of the Cloud Connector (master or shadow). ● You have configured the proxy on the master instance if required for your network. Request and Response Format Requests and responses are coded in JSon format. The following example shows the request payload {description:<value>} coded in JSon: Sample Code {"description":"very helpful description"} Values that represent a date are given as a UTC long number, which is the number of milliseconds since 1 January 1970 00:00:00 UT (GMT+00). In case of errors, the HTTP status code is 4xx. Error details are supplied in the response body in JSON format: {type: <type>, message: <message>} type can have one of these values: INVALID_REQUEST, ILLEGAL_STATE, NOT_FOUND, INVALID_CONFIGURATION, RUNTIME_FAILURE, SHADOW_UPDATE, FORBIDDEN_REQUEST Security and Sessions The Cloud Connector supports basic authentication and form-based authentication. Once authenticated, the client can keep the session and execute subsequent requests in this session. A session avoids the overhead caused by authentication. You can get the session ID from the response header field <Set-cookie> (as JSESSIONID=<session ID>), and send it in the request header Cookie: JSESSIONID=<session Id>. The Cloud Connector uses CSRF tokens to prevent CSRF (cross-site request forgery) attacks. Upon first request, a CSRF token is generated and sent back in the response header in field <X-CSRF-Token>. The client application must keep this token and send it in all subsequent requests as header field <X-CSRF-Token>, together with the session cookie as described above. Note If the request header field <Connection> has the value close (as opposed to keep-alive), no CSRF token is generated. If you want to make stateful, session-based REST calls, use Connection: keep- SAP BTP Connectivity Connectivity PUBLIC 395
- 396. alive, extract the CSRF token from the first response header, and include it in all request headers. Otherwise, use Connection: close and always submit user and password through basic authentication. An inactive session causes a timeout at some point, and will consequently be removed. A request using an expired session receives a login page (Content-type: text/html). The status code of the response is 200 in this case. The only way to detect an expired session is to check the content type and status code. Content type text/html in a connection with status code 200 indicates an expired session. For security reasons, a session should be closed or invalidated once it is not needed anymore. You can achieve this by including Connection: close in the header of the final call of the relevant session. As a result, the Cloud Connector invalidates the session. Subsequent attempts to send a request in the context of that session will respond with a login page as described above. User Roles As of Cloud Connector 2.12, the REST API supports different user roles. Depending on the role, an API grants or denies access. In default configuration, the Cloud Connector uses local user storage and supports the single user Administrator (administrator role). Using LDAP user storage, you can use various users (see also Configure Named Cloud Connector Users [page 502]): Role Technical Role Name Authorization Administrator admin or sccadmin All CRUD operations. Support sccsupport Edit log and trace configuration. Display sccdisplay Read configuration. Monitoring sccmonitoring Read monitoring information. Return Codes Successful requests return the code 200, or, if there is no content, 204. POST actions that create new entities return 201, with the location link in the header. The following general errors can be returned by each API: 400 – invalid request. For example, if parameters are invalid or the API is not supported anymore, an unexpected state occurs and in case of other non-critical errors. 401 – authorization required. 403 – the current Cloud Connector instance does not allow changes. For example, the instance has been assigned to the shadow role and therefore does not allow configuration changes, or the user role does not have required permission. 405 – an entity does not support the requested operation. 396 PUBLIC SAP BTP Connectivity Connectivity
- 397. 409 – current state of the Cloud Connector does not allow changes. For example, the password has to be changed first. 415 – unexpected mime type. 500 – operation failed. The status line provides details explaining the reason. Most APIs may also return specific error details, depending on the situation. Such errors are mentioned in the corresponding API description. Note The error texts depend on the request locale. Hypertext Application Language Entities returned by the APIs contain links as suggested by the current draft JSON Hypertext Application Language (see https:/ /tools.ietf.org/html/draft-kelly-json-hal-08 ). Available APIs API Name Use Common Description [page 399] ● Read common description ● Edit common description High Availability Settings [page 400] ● Get high availaility settings ● Set high availaility settings Proxy Settings [page 411] ● Get proxy settings ● Set proxy settings ● Remove proxy settings Authentication and UI Settings [page 414] ● Read authentication settings ● Edit authentication settings ● Edit LDAP authentication settings SAP BTP Connectivity Connectivity PUBLIC 397
- 398. API Name Use Certificate Management for Backend Communication [page 422] ● Get description for CA certificate for principal propaga tion ● Get binary content of CA certificate for principal propa gation ● Create a self-signed CA certificate for principal propaga tion ● Create a certificate signing request for CA certificate for principal propagation ● Upload a signed certificate chain as CA certificate for principal propagation ● Upload a PKCS#12 certificate as CA certificate for prin cipal propagation ● Delete CA certificate for principal propagation ● Get description for system certificate ● Get binary content of system certificate ● Create a self-signed system certificate ● Create a certificate signing request for a system certifi- cate ● Upload a signed certificate chain as system certificate ● Upload a PKCS#12 certificate as system certificate ● Delete system certificate Solution Management Configuration [page 435] ● Get solution management configuration ● Set solution management configuration and turn on re porting ● Turn off reporting ● Download current LMDB XML report Backup [page 437] ● Create backup configuration ● Restore backup configuration Subaccount [page 439] ● Get list of subaccounts ● Create subaccount ● Delete subaccount ● Edit subaccount ● Connect or disconnect subaccount ● Extend validity of subaccount ● Create or change recovery subaccount ● Delete recovery subaccount ● Extend validity of recovery subaccount ● Get subaccount configuration System Mappings [page 448] ● Get system mappings ● Create system mapping ● Delete system mapping ● Delete all system mappings ● Edit system mapping 398 PUBLIC SAP BTP Connectivity Connectivity
- 399. API Name Use System Mapping Resources [page 453] ● Get system mapping resources ● Get system mapping resource ● Create system mapping resource ● Edit system mapping resource ● Delete system mapping resource ● Delete all system mapping resources Domain Mappings [page 457] ● List domain mappings ● Create domain mappings ● Delete domain mappings ● Edit domain mappings Subaccount Service Channels [page 460] ● Get service channels ● Create service channel ● Delete service channel ● Edit service channel ● Enable or disable service channel Related Information Examples [page 463] 1.2.2.5.1 Common Description Read and edit the Cloud Connector's common description via API. Read Common Description URI /api/v1/configuration/connector Method GET Request Response {role: <current high availability role>, description: <description of Cloud Connector instance>} SAP BTP Connectivity Connectivity PUBLIC 399
- 400. Errors Roles Administrator, Display, Support Edit Common Description URI /api/v1/configuration/connector Method PUT Request {description} Response {role: <current high availability role>, description: <description of Cloud Connector instance>} Errors INVALID_REQUEST Roles Administrator ● Request Properties: description: a string; use an empty string to remove the description. ● Errors: INVALID_REQUEST: if the value of description is not a JSON string. Note null is not a JSON string. 1.2.2.5.2 High Availability Settings Read and edit the high availability settings of a Cloud Connector instance via API. When installing a Cloud Connector instance, you usually define its high availability role (master or shadow instance) during initial configuration, see Change your Password and Choose Installation Type [page 314]. If the high availability role was not defined before, you can set the master or shadow role via this API. If a shadow instance is connected to the master, this API also lets you switch the roles: the master instance requests the shadow instance to take over the master role, and then takes the shadow role itself. 400 PUBLIC SAP BTP Connectivity Connectivity
- 401. Note Editing the high availability settings is only allowed on the master instance, and supports only shadow as input. Get High Availability Settings URI /api/v1/configuration/connector/haRole Method GET Request Response "<HA role>" Errors Roles Administrator, Display, Support Example curl -i -k -u Administrator:<password> https://localhost:8443/api/v1/ configuration/connector/haRole Set High Availability Settings Use this API if you want to set the role of a fresh installation (no role assigned yet). As of version 2.12.0, this API also allows to switch the roles if a shadow instance is connected to the master. In this case, the API is only allowed on the master instance and supports only the value shadow as input. The master instance requests the shadow instance to take over the master role and then assumes the shadow role itself. URI /api/v1/configuration/connector/haRole Method POST SAP BTP Connectivity Connectivity PUBLIC 401
- 402. Request "master" or "shadow" Response Errors ILLEGAL_STATE, INVALID_REQUEST Roles Administrator Errors: ● INVALID_REQUEST (400): If a high-availability role other than "master" or "shadow" is supplied. ● ILLEGAL_STATE (409): If changing the high-availability role is not possible; changing the role is only possible if no role has been assigned, or if the current role is master and a shadow system is connected. Example curl -i -k -H 'Content-Type: application/json' -d '"shadow"' -u Administrator:<password> -X POST https://localhost:8443/api/v1/configuration/ connector/haRole Related Information Master Instance Configuration [page 402] Shadow Instance Configuration [page 406] 1.2.2.5.2.1 Master Instance Configuration Read and edit the high availability settings for a Cloud Connector master instance via API. Note The APIs below are available as of Cloud Connector version 2.13.0. Restriction These APIs are only permitted on a Cloud Connector master instance. The shadow instance rejects the requests with error code 400 – Invalid Request. 402 PUBLIC SAP BTP Connectivity Connectivity
- 403. Get Configuration URI /api/v1/configuration/connector/ha/ master/config Method GET Request Response {haEnabled, allowedShadowHost} Errors Roles Administrator, Display, Support Response Properties: ● haEnabled: a Boolean value that indicates whether or not a shadow system is allowed to connect ● allowedShadowHost: the name of the shadow host (a string) that is allowed to connect; an empty string signifies that any host is allowed to connect as shadow. Example curl -i -k -u <user>:<password> -X GET https://host>:<port>/api/v1/configuration/ connector/ha/master/config Set Configuration URI /api/v1/configuration/connector/ha/ master/config Method PUT Request {haEnabled, allowedShadowHost} Response 204 on success Errors INVALID_REQUEST Roles Administrator SAP BTP Connectivity Connectivity PUBLIC 403
- 404. Response Properties: ● haEnabled: Boolean value that indicates whether or not a shadow system is allowed to connect. ● allowedShadowHost: Name of the shadow host (a string) that is allowed to connect. An empty string means that any host is allowed to connect as shadow. Errors: ● INVALID_REQUEST (400): if the name of the shadow host is not a valid host name Example curl -i -k -u <user>:<password> -X PUT -H 'Content-Type: application/json' -d '{"haEnabled":true}' https://<host>:<port>/api/v1/configuration/connector/ha/ master/config Get State URI /api/v1/configuration/connector/ha/ master/state Method GET Request Response {state, shadowHost} Errors Roles Administrator, Display, Support Response Properties: ● state: One of the following strings: ALONE, BINDING, CONNECTED or BROKEN. ● shadowHost: Connected shadow host (a string) Example curl -i -k -u <user>:<password> -X GET https://<host>:<port>/api/v1/ configuration/connector/ha/master/state 404 PUBLIC SAP BTP Connectivity Connectivity
- 405. Set State URI /api/v1/configuration/connector/ha/ master/state Method POST Request Response {op} Errors ILLEGAL_STATE, INVALID_REQUEST Roles Administrator Request Properties: The value of property op is one of the following strings: ● SWITCH: Switch roles with shadow ● FORCE_SWITCH: Take over the shadow role, even if shadow instance does not respond. Errors: ● INVALID_REQUEST (400): Value of property op is neither SWITCH nor FORCE_SWITCH. ● ILLEGAL_STATE (409): Master system is in a state that does not permit the requested operation. Example curl -i -k -u <user>:<password> -X POST -H 'Content-Type: application/json' -d '{"op":"SWITCH"}' https://<host>:<port>/api/v1/configuration/connector/ha/master/ state Reset A successful call to this API restores default values for all settings related to high availability on the master side. Caution Do not perform this call if the shadow is connected to a master. SAP BTP Connectivity Connectivity PUBLIC 405
- 406. URI /api/v1/configuration/connector/ha/ master/state Method DELETE Request Response 204 on success Errors ILLEGAL_STATE Roles Administrator Errors: ● ILLEGAL_STATE (409): A shadow instance is connected to the master. Example curl -i -k -u <user>:<password> -X DELETE https://<host>:<port>/api/v1/ configuration/connector/ha/master/state 1.2.2.5.2.2 Shadow Instance Configuration Read and edit the configuration settings for a Cloud Connector shadow instance via API (available as of Cloud Connector version 2.12.0, or, where mentioned, as of version 2.13.0). Note The APIs below are only permitted on a Cloud Connector shadow instance. The master instance will reject the requests with error code 403 – FORBIDDEN_REQUEST. Get Configuration URI /api/v1/configuration/connector/ha/ shadow/config Method GET Request 406 PUBLIC SAP BTP Connectivity Connectivity
- 407. Response {masterHost, masterPort, ownHost, checkIntervalInSeconds, takeoverDelayInSeconds, connectTimeoutInMillis, requestTimeoutInMillis} Errors Roles Administrator, Display, Support Response Properties: ● masterHost: Host name of the master instance (string) ● masterPort: Port of the master instance (string or number) ● ownHost: Host name of the shadow instance (string) ● checkIntervalInSeconds: Time between two health checks against the master instance (number) ● takeoverDelayInSeconds: The time a master instance may stay unreachable before the shadow instance takes over (number) ● connectTimeoutInMillis: Timeout for connection attempts between shadow and master instance (number) ● requestTimeoutInMillis: Timeout for requests between shadow and master instance (number) Note This API may take some time to fetch the own hosts from the environment. Example curl -i -k -u <user>:<password> -X GET https://<host>:<port>/api/v1/ configuration/connector/ha/shadow/config Set Configuration URI /api/v1/configuration/connector/ha/ shadow/config Method PUT SAP BTP Connectivity Connectivity PUBLIC 407
- 408. Request {masterPort, masterHost, ownHost, checkIntervalInSeconds, takeoverDelayInSeconds, connectTimeoutInMillis, requestTimeoutInMillis} Response {masterPort, masterHost, ownHost, checkIntervalInSeconds, takeoverDelayInSeconds, connectTimeoutInMillis, requestTimeoutInMillis} Errors Roles Administrator Request Properties: ● masterHost: Host name of the master instance (string) ● masterPort: Port of the master instance (string or number) ● ownHost: Host name of the shadow instance (string) ● checkIntervalInSeconds: Time between two health checks against the master instance (number) ● takeoverDelayInSeconds: The time a master instance may stay unreachable before the shadow instance takes over (number) ● connectTimeoutInMillis: Timeout for connection attempts between shadow and master instance (number) ● requestTimeoutInMillis: Timeout for requests between shadow and master instance (number) Response Properties: See Request Properties. Example curl -i -k -u <user>:<password> -X PUT https://<host>:<port>/api/v1/ configuration/connector/ha/shadow/config -H 'Content-Type: application/json' -d '{"masterHost":"localhost", "masterPort":"8443", "ownHost":"localhost", "checkIntervalInSeconds":30, "takeoverDelayInSeconds":10, "connectTimeoutInMillis":1000, "requestTimeoutInMillis":12000}' Get State 408 PUBLIC SAP BTP Connectivity Connectivity
- 409. Note Available as of version 2.13.0. URI /api/v1/configuration/connector/ha/ shadow/state Method GET Request Response {state, ownHosts, stateMessage, masterVersions} Errors Roles Administrator, Display, Support Response Properties: ● state: Possible string values are: INITIAL, DISCONNECTED, DISCONNECTING, HANDSHAKE, INITSYNC, READY, or LOST. ● ownHosts: List of alternative host names for the shadow instance. ● stateMessage: Message providing details on the current state. This property may not always be present. Typically, this property is available if an error occurred (for example, a failed attempt to connect to the master instance). ● masterVersions: Overview of relevant component versions of the master system, including a flag (property ok) that indicates whether or not there are incompatibility issues because of differing master and shadow versions. Note This property is only available if the shadow instance is connected to the master instance, or if there has been a successful connection to the master system at some point in the past. Example curl -i -k -u <user>:<password> -X GET https://<host>:<port>/api/v1/ configuration/connector/ha/shadow/state Change State SAP BTP Connectivity Connectivity PUBLIC 409
- 410. URI /api/v1/configuration/connector/ha/ shadow/state Method POST Request Response {op, user, password} Errors INVALID_REQUEST, ILLEGAL_STATE Roles Administrator Request Properties: ● op: String value representing the state change operation. Possible values are CONNECT or DISCONNECT. ● user: User for logon to the master instance ● password: Password for logon to the master instance Errors: ● INVALID_REQUEST (400): Invalid or missing property values were supplied; this includes wrong user or password ● ILLEGAL_STATE (409): The requested operation cannot be executed given the current state of master and shadow instance. This typically means the master instance does not allow high availability. Note The logon credentials are used for initial logon to master instance only. If a shadow instance is disconnected from its master instance, it will reconnect to the (same) master instance using a certificate. Hence, user and password can be omitted when reconnecting. Example curl -i -k -u <user>:<password> -X POST https://<host>:<port>/api/v1/ configuration/connector/ha/shadow/state -H 'Content-Type: application/json' -d '{"op":"CONNECT", "user":"<user on master>", "password":"<password>"}' curl -i -k -u <user>:<password> -X POST https://<host>:<port>/api/v1/ configuration/connector/ha/shadow/state -H 'Content-Type: application/json' -d '{"op":"DISCONNECT"}' Reset 410 PUBLIC SAP BTP Connectivity Connectivity
- 411. Note Available as of version 2.13.0. A successful call to this API deletes master host and port, and restores default values for all other settings related to a connection to the master. Caution Do not perform this call if the shadow is connected to a master. URI /api/v1/configuration/connector/ha/ shadow/state Method DELETE Request Response Errors ILLEGAL_STATE Roles Administrator Errors: ● ILLEGAL_STATE (409): the shadow is currently connected to a master. Example curl -i -k -u <user>:<password> -X DELETE https://<host>:<port>/api/v1/ configuration/connector/ha/shadow/state 1.2.2.5.3 Proxy Settings Read and edit the Cloud Connector's proxy settings via API. Get Proxy Settings SAP BTP Connectivity Connectivity PUBLIC 411
- 412. URI /api/v1/configuration/connector/proxy Method GET Request Response {host, port, user} Errors Roles Administrator, Display, Support Response Properties: ● host: the name of the proxy host (a string) ● port: the port of the proxy host (a string) ● user: the user name (a string) Sample Code curl -ik -u Administrator:<password> https://localhost:8443/api/v1/ configuration/connector/proxy Set Proxy Settings (Master Only) URI /api/v1/configuration/connector/proxy Method PUT Request {host, port, user, password} Response Errors INVALID_REQUEST, FORBIDDEN_REQUEST Roles Administrator Request Properties: ● host: the name of the proxy host (a string) ● port: the port of the proxy host (a string) ● user: the user name (a string) ● password: the password (a string - optional) 412 PUBLIC SAP BTP Connectivity Connectivity
- 413. Errors: ● INVALID_REQUEST (400): invalid values were supplied, or mandatory values are missing. ● FORBIDDEN_REQUEST (403): the target of the call is a shadow instance. The following example sets empty user and password. Sample Code curl -ik -u Administrator:<password> https://localhost:8443/api/v1/ configuration/connector/proxy -X PUT -H 'Content-Type: application/json' -d '{"host":"proxy", "port":"8080"}' This request removes the proxy configuration. Sample Code curl -ik -u Administrator:<password> https://localhost:8443/api/v1/ configuration/connector/proxy -X PUT -H 'Content-Type: application/json' -d '{}' Remove Proxy Settings (Master Only) URI /api/v1/configuration/connector/proxy Method DELETE Request Response 204 on success Errors FORBIDDEN_REQUEST Roles Administrator Errors: ● FORBIDDEN_REQUEST (403): the target of the call is a shadow instance. Sample Code curl -ik -u Administrator:<password> https://localhost:8443/api/v1/ configuration/connector/proxy -X DELETE SAP BTP Connectivity Connectivity PUBLIC 413
- 414. 1.2.2.5.4 Authentication and UI Settings Read and edit the Cloud Connector's authentication and UI settings via API. Get Authentication Settings URI /api/v1/configuration/connector/ authentication Method GET Request Response {type, configuration} Errors Roles Administrator, Display, Support Response Properties: ● type: The authentication type, which is one of the following strings: basic or ldap. ● configuration: The configuration of the active LDAP authentication. This property is only available if type is ldap. Its value is an object with properties that provide details on LDAP configuration. Example curl -i -k -H 'Accept:application/json' -u Administrator:<password> -X GET https://<scchost>:8443/api/v1/configuration/ connector/authentication Change Basic Authentication User URI /api/v1/configuration/connector/ authentication/basic Method PUT 414 PUBLIC SAP BTP Connectivity Connectivity
- 415. Request {password, user} Response 204 on success Errors INVALID_REQUEST Roles Administrator Request Properties: ● password: The current password (a string) ● user: The new user name (a string), overwriting the current user name. Errors: ● INVALID_REQUEST (400): Current password is wrong. Change Basic Authentication Password URI /api/v1/configuration/connector/ authentication/basic Method PUT Request {oldPassword, newPassword} Response 204 on success Errors INVALID_REQUEST Roles Administrator Request Properties: ● oldPassword: The current password, about to be changed (a string) ● newPassword: The new password (a string) Errors: ● INVALID_REQUEST (400): Passwords are the same or current password is wrong. SAP BTP Connectivity Connectivity PUBLIC 415
- 416. Example curl -i -k -H 'Content-Type:application/json' -d '{"oldPassword"="manage", "newPassword"="test"}' -u Administrator:manage -X PUT https://localhost:8443/api/v1/configuration/ connector/authentication/basic Change LDAP Authentication Caution The Cloud Connector will restart if the request was successful. There is no test that confirms login will work afterwards. If you run into problems you can revert to basic authentication by executing the script useFileUserStore located in the root directory of your Cloud Connector installation. URI /api/v1/configuration/connector/ authentication/ldap Method PUT Request {enable, configuration} Response 204 on success Errors INVALID_REQUEST, INVALID_CONFIGURATION Roles Administrator Request Properties: ● enable: Boolean flag that indicates whether or not to employ LDAP authentication. ● configuration: The LDAP configuration, a JSON object with the properties {config, hosts, user, password, customAdminRole , customDisplayRole, customMonitoringRole , customSupportRole}. ○ Property hosts is an array. Each element of the array defines a host, again specified through a JSON object, with the properties {host, port, isSecure}, accepting string, string (or number), and Boolean values, respectively. ○ All properties of the top-level object except hosts accept string values. ○ Properties config and hosts are mandatory. The array of hosts needs to have at least one element. ○ All other properties are optional. Errors: ● INVALID_REQUEST (400): Configuration is invalid. 416 PUBLIC SAP BTP Connectivity Connectivity
- 417. ● INVALID_CONFIGURATION (409): LDAP server is not accessible (does not respond). Note In both error cases nothing is stored, and LDAP authentication is disabled. Example curl -i -k -H 'Content-Type: application/json' -u Administrator:<password> -X PUT https://localhost:8443/api/v1/configuration/connector/authentication/ldap -d '{"enable":true, "configuration":{"hosts":[{"host":"ldaphost", "port":"10389", "isSecure":false}], "config":"roleBase="ou=groups,dc=scc" roleName="cn" roleSearch="(uniqueMember={0})" userBase="ou=users,dc=scc" userSearch= "(uid={0})"", "user":"ldapadmin", "password":"<ldapadminpassword>"}}' Get Description for UI Certificate This API returns a textual description for the system certificate. Note Available as of version 2.13.0. URI /api/v1/configuration/connector/ui/ uiCertificate Method GET Response {subjectDN, issuer, notBeforeTimeStamp, notAfterTimeStamp, subjectAltNames} Errors Roles Administrator, Display, Support Response Properties: ● subjectDN: The subject distinguished name (a string) ● issuer: The issuer (a string) ● notBeforeTimeStamp: Timestamp of the beginning of the validity period (a UTC long number) ● notAfterTimeStamp: Timestamp of the end of the validity period (a UTC long number) SAP BTP Connectivity Connectivity PUBLIC 417
- 418. ● subjectAltNames: Subject alternative names, as an array of objects with properties type and value. The value of property type is one of the following strings: IP, DNS, URI, or RFC822. The value of property value is the associated value (a string). Note subjectAltNames is not present if there are no subject alternative names. Example curl -i -k -H "Accept: application/json" -u <user>:<password> -X GET https:// <host>:<port>/api/v1/configuration/connector/ui/uiCertificate Create a Self-Signed UI Certificate Note Available as of version 2.13.0. URI /api/v1/configuration/connector/ui/ uiCertificate Method POST Request {type, subjectDN, subjectAltNames} Response 201 on success Errors Roles Administrator Request Properties: ● type: The string selfsigned ● subjectDN: The subject distinguished name (a string) ● subjectAltNames: Subject alternative names, as an array of objects with properties type and value. The value of property type is one of the following strings: IP, DNS, URI, or RFC822. The value of property value is the associated value (a string). This property is optional. The UI certificate created this way has a validity of 1 year. 418 PUBLIC SAP BTP Connectivity Connectivity
- 419. Example curl -k -u Administrator:<password> -X POST -H "Content-Type: application/json" --data '{"type":"selfsigned", "subjectDN":"CN=me"}' https: //<host>:<port>/api/v1/configuration/connector/ui/uiCertificate Create a Certificate Signing Request for a UI Certificate Note Available as of version 2.13.0. URI /api/v1/configuration/connector/ui/ uiCertificate Method POST Request {type, subjectDN, subjectAltNames} Response PEM-encoded certificate request Errors Roles Administrator Request Properties: ● type: The string csr ● subjectDN: The subject distinguished name (a string) ● subjectAltNames: Subject alternative names, as an array of objects with properties type and value. The value of property type is one of the following strings: IP, DNS, URI, or RFC822. The value of property value is the associated value (a string). This property is optional. Example curl -k -u Administrator:<password> -X POST -H "Content-Type: application/json" --data '{"type":"csr", "subjectDN":"CN=me"}' https: //<host>:<port>/api/v1/configuration/connector/ui/uiCertificate -o csr.pem SAP BTP Connectivity Connectivity PUBLIC 419
- 420. Upload a Signed Certificate Chain as UI Certificate Note Available as of version 2.13.0. URI /api/v1/configuration/connector/ui/ uiCertificate Method PATCH Request multipart/form-data with the following form parameter: signedCertificate Response 201 on success Errors INVALID_REQUEST Roles Administrator Request Parameters: ● signedCertificate: The signed certificate and CA certificate chain (PEM-encoded) Errors: ● INVALID_REQUEST (400): The certificate chain provided does not match the most recent certificate request, or it is not a certificate chain in the proper format (PEM-encoded). Example curl -i -k -u <user>:<password> -X PATCH -F signedCertificate=@<signedchain.pem> https://<host>:<port>/api/v1/configuration/connector/ui/uiCertificate Example For test purposes, you can sign the certificate signing request with keytool. keytool -genkeypair -keyalg RSA -keysize 1024 -alias mykey -dname "cn=very trusted, c=test" -validity 365 -keystore ca.ks -keypass testit -storepass testit keytool -gencert -rfc -infile csr.pem -outfile signedcsr.pem -alias mykey - keystore ca.ks -keypass testit -storepass testit keytool -exportcert -rfc -file ca.pem -alias mykey -keystore ca.ks -keypass testit -storepass testit 420 PUBLIC SAP BTP Connectivity Connectivity
- 421. cat signedcsr.pem ca.pem > signedchain.pem Upload a PKCS#12 Certificate as UI Certificate Note Available as of version 2.13.0. URI /api/v1/configuration/connector/ui/ uiCertificat Method PUT Request multipart/form-data with the following form parameters: pkcs12 password keyPassword Response 204 on success Errors INVALID_REQUEST Roles Administrator Request Parameters: ● pkcs12: Contents of PKCS#12 file ● password: Password for decrypting the PKCS#12 file ● keyPassword: Optional password for the private key Errors: ● INVALID_REQUEST (400): Contents of PKCS#12 or password are invalid Note keyPassword is optional. If missing, password is used to decrypt the pkcs#12 file and the private key. SAP BTP Connectivity Connectivity PUBLIC 421
- 422. Example curl -i -k -u <user>:<password> https://<host>:<port>/api/v1/configuration/ connector/ui/uiCertificate -X PUT -F 'password=<p12Password>' -F pkcs12=@<p12file> Example For test purposes, you can create an own self-signed pkcs#12 certificate with keytool. keytool -genkeypair -alias key -keyalg RSA -keysize 2048 -validity 365 -keypass test20 -keystore test.p12 -storepass test20 -storetype PKCS12 -dname 'CN=test' 1.2.2.5.5 Certificate Management for Backend Communication Manage a CA certificate for principal propagation or a system certificate via API. Note The APIs below are available as of Cloud Connector version 2.13. There are two similar sets of APIs for system certificate and CA certificate for principal propagation. Note Some of the APIs list a parameter subjectAltNames (subject alternative names or SAN) for the request or response object. This parameter is an array of objects with the following properties: ● type: one of the strings DNS, URI, IP, or RFC822. ● value: the value associated with the chosen type. ● CA Certificate for Principal Propagation: APIs [page 422] ● System Certificate: APIs [page 428] 1.2.2.5.5.1 CA Certificate for Principal Propagation: APIs Manage a CA certificate for principal propagation via API. 422 PUBLIC SAP BTP Connectivity Connectivity
- 423. Note The APIs below are available as of Cloud Connector version 2.13.0. Get Description for a CA Certificate for Principal Propagation URI /api/v1/configuration/connector/ onPremise/ppCaCertificate Method GET Header Accept: application/json Response {subjectDN, issuer, notBeforeTimeStamp, notAfterTimeStamp, subjectAltNames} Errors NOT_FOUND Roles Administrator, Display, Support Response Properties: ● subjectDN: the subject distinguished name (a string) ● issuer: the issuer (a string) ● notBeforeTimeStamp: timestamp of the beginning of the validity period (a UTC long number) ● notAfterTimeStamp: timestamp of the end of the validity period (a UTC long number) ● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication [page 422] for details). Errors: ● NOT_FOUND (404): there is no CA certificate for principal propagation. Note subjectAltNames is not present if there are no subject alternative names. Example curl -i -k -H "Accept: application/json" -u <user>:<password> -X GET https:// <host>:<port>/api/v1/configuration/connector/onPremise/ppCaCertificate SAP BTP Connectivity Connectivity PUBLIC 423
- 424. Get Binary Content of a CA Certificate for Principal Propagation URI /api/v1/configuration/connector/ onPremise/ppCaCertificate Method GET Header Accept: application/pkix-cert Response Binary data of the certificate. Errors NOT_FOUND Roles Administrator, Display, Support Response: ● Success: the binary data of the certificate; you can verify the downloaded certificate by storing it in file ppca.crt, for instance, and then running keytool -printcert -file ppca.crt ● Failure: an error in the usual JSON format; the content type of the response is application/json in this case. Errors: ● NOT_FOUND (404): there is no CA certificate for principal propagation. Example curl -k -H "Accept: application/pkix-cert" -u <user>:<password> -X GET --output sys.crt https://<host>:<port>/api/v1/configuration/connector/onPremise/ ppCaCertificate Create a Self-Signed CA Certificate for Principal Propagation (Master Only) URI /api/v1/configuration/connector/ onPremise/ppCaCertificate 424 PUBLIC SAP BTP Connectivity Connectivity
- 425. Method POST Request {type, subjectDN, subjectAltNames} Response 201 on success Errors Roles Administrator Request Properties: ● type: the string selfsigned ● subjectDN: the subject distinguished name (a string) ● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication [page 422] for details). This property is optional. The certificate created this way has a validity of 1 year. Example curl -i -k -H "Accept: application/json" -H "Content-Type: application/json" -u <user>:<password> -X POST --data '{"type":"selfsigned", "subjectDN":"CN=me"}' https://<host>:<port>/api/v1/configuration/connector/onPremise/ppCaCertificate Create a Certificate Signing Request for a CA Certificate for Principal Propagation (Master Only) URI /api/v1/configuration/connector/ onPremise/ppCaCertificate Method POST Request {type, subjectDN, subjectAltNames} Response PEM-encoded certificate request Errors Roles Administrator SAP BTP Connectivity Connectivity PUBLIC 425
- 426. Request Properties: ● type: the string selfsigned ● subjectDN: the subject distinguished name (a string) ● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication [page 422] for details). This property is optional. Example curl -k -u <user>:<password> -X POST -H "Content-Type: application/json" --data '{"type":"csr", "subjectDN":"CN=me"}' https://<host>:<port>/api/v1/configuration/connector/onPremise/ppCaCertificate - o csr.pem Upload a Signed Certificate Chain as CA Certificate for Principal Propagation (Master Only) URI /api/v1/configuration/connector/ onPremise/ppCaCertificate Method PATCH Request multipart/form-data with the following parameter: signedCertificate. Response 201 on success Errors INVALID_REQUEST Roles Administrator Request Properties: ● signedCertificate: the signed certificate and CA certificate chain (PEM-encoded) Errors: ● INVALID_REQUEST (400): the certificate chain provided does not match the most recent certificate request, or it is not a certificate chain in the correct format (PEM-encoded). 426 PUBLIC SAP BTP Connectivity Connectivity
- 427. Example curl -i -k -u <user>:<password> -X PATCH -F signedCertificate=@<signedchain.pem> https://<host>:<port>/api/v1/configuration/connector/onPremise/ppCaCertificate Example: Sign The Certificate Signing Request keytool -genkeypair -keyalg RSA -keysize 1024 -alias mykey -dname "cn=very trusted, c=test" -validity 365 -keystore ca.ks -keypass testit -storepass testit keytool -gencert -rfc -infile csr.pem -outfile signedcsr.pem -alias mykey - keystore ca.ks -keypass testit -storepass testit keytool -exportcert -rfc -file ca.pem -alias mykey -keystore ca.ks -keypass testit -storepass testit cat signedcsr.pem ca.pem > signedchain.pem Upload a PKCS#12 Certificate as CA Certificate for Principal Propagation (Master Only) URI /api/v1/configuration/connector/ onPremise/ppCaCertificate Method PUT Request Multipart/form-data with the following form parameters: pkcs12, password, keyPassword Response 204 on success Errors INVALID_REQUEST Roles Administrator Request Parameters: ● pkcs12: contents of PKCS#12 file ● password: password for decrypting PKCS#12 file ● keyPassword: optional password for the private key Errors: ● INVALID_REQUEST (400): contents of PKCS#12 or password are invalid Note keyPassword is optional. If it is missing, password is used to decrypt the pkcs#12 file and the private key. SAP BTP Connectivity Connectivity PUBLIC 427
- 428. Example curl -i -k -u <user>:<password> https://<host>:<port>/api/v1/configuration/ connector/onPremise/ppCaCertificate -X PUT -F 'password=<p21Password>' -F pkcs12=@<p12file> Create an own self-signed pkcs#12 certificate for tests with: keytool -genkeypair -alias key -keyalg RSA -keysize 2048 -validity 365 -keypass test20 -keystore test.p12 -storepass test20 -storetype PKCS12 -dname 'CN=test' Delete a CA Certificate for Principal Propagation (Master Only) URI /api/v1/configuration/connector/ onPremise/ppCaCertificate Method DELETE Request Response 204 on success Errors NOT_FOUND Roles Administrator Errors: ● NOT_FOUND (404): there is no CA certificate for principal propagation. Example curl -k -H "Accept: application/json" -u <user>:<password> --request DELETE https://localhost:8443/api/v1/configuration/connector/onPremise/ppCaCertificate 1.2.2.5.5.2 System Certificate: APIs Manage a system certificate via API. 428 PUBLIC SAP BTP Connectivity Connectivity
- 429. Note The APIs below are available as of Cloud Connector version 2.13.0. Get Description for a System Certificate URI /api/v1/configuration/connector/ onPremise/systemCertificate Method GET Header Accept: application/json Response {subjectDN, issuer, notBeforeTimeStamp, notAfterTimeStamp, subjectAltNames} Errors NOT_FOUND Roles Administrator, Display, Support Response Properties: ● subjectDN: the subject distinguished name (a string) ● issuer: the issuer (a string) ● notBeforeTimeStamp: timestamp of the beginning of the validity period (a UTC long number) ● notAfterTimeStamp: timestamp of the end of the validity period (a UTC long number) ● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication [page 422] for details). Errors: ● NOT_FOUND (404): there is no system certificate. Note subjectAltNames is not present if there are no subject alternative names. Example curl -i -k -H "Accept: application/json" -u <user>:<password> -X GET https:// <host>:<port>/api/v1/configuration/connector/onPremise/systemCertificate SAP BTP Connectivity Connectivity PUBLIC 429
- 430. Get Binary Content of a System Certificate URI /api/v1/configuration/connector/ onPremise/systemCertificate Method GET Header Accept: application/pkix-cert Response Binary data of the certificate. Errors NOT_FOUND Roles Administrator, Display, Support Response: ● Success: the binary data of the certificate; you can verify the downloaded certificate by storing it in file sys.crt, for instance, and then running keytool -printcert -file sys.crt ● Failure: an error in the usual JSON format; the content type of the response is application/json in this case. Errors: ● NOT_FOUND (404): there is no system certificate. Example curl -i -k -H "Accept: application/pkix-cert" -u <user>:<password> -X GET -- output sys.crt https://<host>:<port>/api/v1/configuration/connector/onPremise/ systemCertificate Create a Self-Signed System Certificate (Master Only) URI /api/v1/configuration/connector/ onPremise/systemCertificate Method POST Header CONTENT_TYPE: application/json 430 PUBLIC SAP BTP Connectivity Connectivity
- 431. Request {type, subjectDN, subjectAltNames} Response 201 on success Errors Roles Administrator Request Properties: ● type: the string selfsigned ● subjectDN: the subject distinguished name (a string) ● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication [page 422] for details). This property is optional. The certificate created this way has a validity of 1 year. Example curl -i -k -H "Accept: application/json" -H "Content-Type: application/json" -u <user>:<password> -X POST --data '{"type":"selfsigned", "subjectDN":"CN=me"}' https://<host>:<port>/api/v1/configuration/connector/onPremise/systemCertificate Create a Certificate Signing Request for a System Certificate (Master Only) URI /api/v1/configuration/connector/ onPremise/systemCertificate Method POST Header CONTENT_TYPE: application/json Request {type, subjectDN, subjectAltNames} Response PEM-encoded certificate request Errors Roles Administrator Request Properties: ● type: the string selfsigned SAP BTP Connectivity Connectivity PUBLIC 431
- 432. ● subjectDN: the subject distinguished name (a string) ● subjectAltNames: subject alternative names (see Certificate Management for Backend Communication [page 422] for details). This property is optional. Example curl -k -u <user>:<password> -X POST -H "Content-Type: application/json" --data '{"type":"csr", "subjectDN":"CN=me"}' https://<host>:<port>/api/v1/configuration/connector/onPremise/ systemCertificate -o csr.pem Upload a Signed Certificate Chain as System Certificate (Master Only) URI /api/v1/configuration/connector/ onPremise/systemCertificate Method PATCH Request multipart/form-data with the following parameter: signedCertificate. Response 201 on success Errors INVALID_REQUEST Roles Administrator Request Properties: ● signedCertificate: the signed certificate and CA certificate chain (PEM-encoded) Errors: ● INVALID_REQUEST (400): the certificate chain provided does not match the most recent certificate request, or it is not a certificate chain in the correct format (PEM-encoded). Example curl -i -k -u <user>:<password> -X PATCH -F signedCertificate=@<signedchain.pem> https://<host>:<port>/api/v1/configuration/connector/onPremise/systemCertificate 432 PUBLIC SAP BTP Connectivity Connectivity
- 433. For test purposes, you can sign the certificate signing request with keytool: keytool -genkeypair -keyalg RSA -keysize 1024 -alias mykey -dname "cn=very trusted, c=test" -validity 365 -keystore ca.ks -keypass testit -storepass testit keytool -gencert -rfc -infile csr.pem -outfile signedcsr.pem -alias mykey - keystore ca.ks -keypass testit -storepass testit keytool -exportcert -rfc -file ca.pem -alias mykey -keystore ca.ks -keypass testit -storepass testit cat signedcsr.pem ca.pem > signedchain.pem Upload a PKCS#12 Certificate as System Certificate (Master Only) URI /api/v1/configuration/connector/ onPremise/systemCertificate Method PUT Request Multipart/form-data with the following form parameters: pkcs12, password, keyPassword Response 204 on success Errors INVALID_REQUEST Roles Administrator Request Parameters: ● pkcs12: contents of PKCS#12 file ● password: password for decrypting PKCS#12 file ● keyPassword: optional password for the private key Errors: ● INVALID_REQUEST (400): contents of PKCS#12 or password are invalid Note keyPassword is optional. If it is missing, password is used to decrypt the pkcs#12 file and the private key. SAP BTP Connectivity Connectivity PUBLIC 433
- 434. Example curl -i -k -u <user>:<password> https://<host>:<port>/api/v1/configuration/ connector/onPremise/systemCertificate -X PUT -F password=<p21Password> -F pkcs12=@<p12file> Create an own self-signed pkcs#12 certificate for tests with: keytool -genkeypair -alias key -keyalg RSA -keysize 2048 -validity 365 -keypass test20 -keystore test.p12 -storepass test20 -storetype PKCS12 -dname 'CN=test' Delete a System Certificate (Master Only) URI /api/v1/configuration/connector/ onPremise/systemCertificate Method DELETE Request Response 204 on success Errors NOT_FOUND Roles Administrator Errors: ● NOT_FOUND (404): there is no system certificate. Example curl -k -H "Accept: application/json" -u <user>:<password> --request DELETE https://localhost:8443/api/v1/configuration/connector/onPremise/systemCertificate 434 PUBLIC SAP BTP Connectivity Connectivity
- 435. 1.2.2.5.6 Solution Management Configuration Manage the Cloud Connector's solution management configuration via API. Get Solution Management Configuration URI /api/v1/configuration/connector/ solutionManagement Method GET Request Response {hostAgentPath, isEnabled, dsrEnabled} Errors Roles Administrator, Display, Support Response Properties: ● isEnabled: flag indicating if reporting to solution management is active. ● hostAgentPath: path for host agent executable. ● dsrEnabled: indicating if DSR reporting is active. Example curl -ik -u <user>:<password> https://<host>:<port>/api/v1/configuration/ connector/solutionManagement Set Solution Management Configuration and Turn On Reporting This API turns on the integration with the Solution Manager. The prerequisite is an available Host Agent. You can specify a path to the Host Agent executable, if you don't use the default path. URI /api/v1/configuration/connector/ solutionManagement SAP BTP Connectivity Connectivity PUBLIC 435
- 436. Method POST Request {hostAgentPath, dsrEnabled} Response Errors Roles Administrator, Support Response Properties: ● hostAgentPath: path for host agent executable (string, optional). ● dsrEnabled: flag indicating if DSR reporting is active (boolean, optional)- Example curl -ik -u <user>:<password> https://<host>:<port>/api/v1/configuration/ connector/solutionManagement -X POST or, if configuration has to be changed: curl -ik -u <user>:<password> https://<host>:<port>/api/v1/configuration/ connector/solutionManagement -X POST -d "{"hostAgentPath":"new/path/to/ hostAgent"}" -H "Content-Type:application/json" Turn Off Solution Management Reporting URI /api/v1/configuration/connector/ solutionManagement Method DELETE Request Response Errors Roles Administrator, Support 436 PUBLIC SAP BTP Connectivity Connectivity
- 437. Example curl -ik -u <user>:<password> https://<host>:<port>/api/v1/configuration/ connector/solutionManagement -X DELETE Download Current LMDB XML Report Generates a zip file containing the registration file for the solution management LMDB (Landscape Management Database). Note Available as of Cloud Connector version 2.12.0. URI /api/v1/configuration/connector/ solutionManagement/registrationFile Method GET Request Response Errors Roles Administrator, Support 1.2.2.5.7 Backup Manage the Cloud Connector's configuration backup via API. Create Backup Configuration URI /api/v1/configuration/backup Method POST SAP BTP Connectivity Connectivity PUBLIC 437
- 438. Request {password} Response ZIP archive (content type application/zip) Errors Roles Administrator Request Properties: ● password: the password used to encrypt sensitive data. Note Only sensitive data in the backup are encrypted with an arbitrary password of your choice. The password is required for the restore operation. The returned ZIP archive itself is not password-protected. Restore Backup Configuration URI /api/v1/configuration/backup Method PUT Request Multipart/form-data backup file and password as form pa rameter. Successful request forces restart of the Cloud Connector. Response 204 - in case of success. Errors 400 {type: INVALID_REQUEST, message: <msg>} Roles Administrator Note Since this API uses a multipart request, it requires a multipart request header. 438 PUBLIC SAP BTP Connectivity Connectivity
- 439. 1.2.2.5.8 Subaccount Manage the Cloud Connector's subaccount settings via API. Operations Subaccount Get Subaccounts [page 439] Create Subaccount (Master Only) [page 440] Delete Subaccount (Master Only) [page 441] Edit Subaccount (Master Only) [page 441] Connect/Disconnect Subaccount (Master Only) [page 442] Refresh Subaccount Certificate (Master Only) [page 443] Get Subaccount Configuration [page 444] Recovery Subaccount Create Recovery Subaccount (Master Only) [page 444] Delete Recovery Subaccount (Master Only) [page 445] Refresh Certificate of Recovery Subaccount (Master Only) [page 446] Activate/Deactivate Recovery Subaccount (Master Only) [page 447] Takeover (Master Only) [page 447] Get Subaccounts URI /api/v1/configuration/subaccounts Method GET Request Response [{regionHost, subaccount, locationID}] Errors Roles Administrator, Display, Support SAP BTP Connectivity Connectivity PUBLIC 439
- 440. Response: An array of objects with the following properties: ● regionHost: region hosts (a string). ● subaccount: subaccount name (a string). ● locationID: location identifier for the Cloud Connector instance (a string); this property is not available if the default location ID is in use. Back to Operations [page 439] Create Subaccount (Master Only) Creates and connects a subaccount. URI /api/v1/configuration/subaccounts Method POST Request {regionHost, subaccount, cloudUser, cloudPassword, locationID, displayName, description} Response 201, created subaccount entity: {regionHost, subaccount, locationID, displayName, description, tunnel} Errors INVALID_REQUEST, INVALID_CONFIGURATION Roles Administrator Request Properties: ● regionHost: region host name (a string). ● subaccount: subaccount technical name (a string). ● cloudUser: user for the specified subaccount and region host. ● cloudPassword: password for the cloud user. ● locationID: location identifier for the Cloud Connector instance (a string; optional). ● displayName: display name of the subaccount (a string; optional). ● description: subaccount description (a string; optional). Response Properties: ● regionHost: region host name (a string). ● subaccount: subaccount technical name (a string). ● locationID: location ID (a string); this property is not available if the default location ID is in use. 440 PUBLIC SAP BTP Connectivity Connectivity
- 441. ● displayName: display name of the subaccount (a string); this property is not available if there is no specified display name. ● description: subaccount description (a string); this property is not available if there is no description. ● tunnel: object outlining the current state of the tunnel. Errors: ● INVALID_REQUEST (400): one or more mandatory parameters are missing or invalid. ● INVALID_CONFIGURATION (409): the subaccount already exists as a regular subaccount or recovery subaccount. Back to Operations [page 439] Delete Subaccount (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount> Method DELETE Request Response 204 on success Errors NOT_FOUND, ILLEGAL_STATE Roles Administrator Errors: ● NOT_FOUND (404): subaccount does not exist (in the specified region). ● ILLEGAL_STATE (409): there is at least one session that has access to the subaccount. Back to Operations [page 439] Edit Subaccount (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount> Method PUT SAP BTP Connectivity Connectivity PUBLIC 441
- 442. Request {locationID, displayName, description} Response {regionHost, subaccount, locationID, displayName, description, tunnel, recoveryAccountState} Errors NOT_FOUND Roles Administrator Request Properties: ● locationID: location identifier for the Cloud Connector instance (a string; optional); if this parameter is not supplied the location ID will not change. Revert to the default location ID by supplying the empty string. ● displayName: subaccount display name (a string; optional); if this parameter is not supplied the display name will not change. Clear the display name by using an empty string. ● description: subaccount description (a string; optional); if this parameter is not supplied the description will not change. Clear the description by using an empty string. Response Properties: ● regionHost: region host name (a string). ● subaccount: subaccount technical name (a string). ● locationID: location identifier for the Cloud Connector instance (a string); this property is not available if the default location ID is in use. ● displayName: display name of the subaccount (a string); this property is not available if there is no specified display name. ● description: subaccount description (a string); this property is not available if there is no description. ● tunnel: object outlining the current state of the tunnel. ● recoveryAccountState: object detailing the current state of the recovery subaccount. This property is supplied only if a recovery subaccount is configured. Errors ● NOT_FOUND (404): subaccount does not exist (in the specified region). Back to Operations [page 439] Connect/Disconnect Subaccount (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/state 442 PUBLIC SAP BTP Connectivity Connectivity
- 443. Method PUT Request {connected} Response 204 on success Errors Roles Administrator Request Properties: ● connected: a Boolean value indicating whether the subaccount should be connected (true) or disconnected (false). Back to Operations [page 439] Refresh Subaccount Certificate (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/validity Method POST Request {user, password} Response {regionHost, subaccount, locationID, displayName, description, tunnel, recoveryAccountState} Errors Roles Administrator Request Properties: ● user: user for the specified region host and subaccount. ● password: password for the (cloud) user. Response Properties: ● regionHost: region host name (a string). ● subaccount: subaccount technical name (a string). ● locationID: location identifier for the Cloud Connector instance (a string); this property is not available if the default location ID is in use. SAP BTP Connectivity Connectivity PUBLIC 443
- 444. ● displayName: display name of the subaccount (a string); this property is not available if there is no specified display name. ● description: subaccount description (a string); this property is not available if there is no description. ● tunnel: object outlining the current state of the tunnel. ● recoveryAccountState: object detailing the current state of the recovery subaccount. This property is supplied only if a recovery subaccount is configured. Back to Operations [page 439] Get Subaccount Configuration URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount> Method GET Request Response {regionHost, subaccount, locationID, displayName, description, tunnel: {state, connections, applicationConnections:[], serviceChannels:[]}} Errors Roles Administrator, Display, Support Response Properties: ● regionHost: region host name (a string). ● subaccount: subaccount technical name (a string). ● locationID: location ID (a string); this property is not available if the default location ID is in use. ● displayName: display name of the subaccount (a string); this property is not available if there is no specified display name. ● description: description (a string); this property is not available if there is no description. ● tunnel: object outlining the current state of the tunnel. Back to Operations [page 439] Create Recovery Subaccount (Master Only) 444 PUBLIC SAP BTP Connectivity Connectivity
- 445. URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/recovery Method POST Request {regionHost, cloudUser, cloudPassword} Response 201 on success Errors INVALID_REQUEST, ILLEGAL_STATE Roles Administrator Request Properties: ● regionHost: region host of the recovery subaccount. ● cloudUser: user for the specified region host and recovery subaccount. ● cloudPassword: password for the cloud user. Errors: ● INVALID_REQUEST (400): invalid or missing request parameters. ● ILLEGAL_STATE (409): a recovery subaccount already exists. Note A recovery subaccount cannot be changed. Delete it and create a new one instead. Back to Operations [page 439] Delete Recovery Subaccount (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/recovery Method DELETE Request Response Errors NOT_FOUND Roles Administrator SAP BTP Connectivity Connectivity PUBLIC 445
- 446. Errors: ● NOT_FOUND (404): there is no recovery subaccount. Back to Operations [page 439] Refresh Certificate of Recovery Subaccount (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/recovery/ validity Method POST Request {user, password} Response {regionHost, subaccount, locationID, displayName, description, tunnel, recoveryAccountState} Errors INVALID_REQUEST, NOT_FOUND Roles Administrator Request Properties: ● user: user for the specified region host and subaccount. ● password: password for the (cloud) user. Response Properties: ● regionHost: region host name (a string). ● subaccount: subaccount technical name (a string). ● locationID: location identifier for the Cloud Connector instance (a string); this property is not available if the default location ID is in use. ● displayName: display name of the subaccount (a string); this property is not available if there is no specified display name. ● description: subaccount description (a string); this property is not available if there is no description. ● tunnel: object outlining the current state of the tunnel. ● recoveryAccountState: object detailing the current state of the recovery subaccount. This property is supplied only if a recovery subaccount is configured. Errors ● INVALID_REQUEST (400): user or password are missing. 446 PUBLIC SAP BTP Connectivity Connectivity
- 447. ● NOT_FOUND (404): there is no recovery subaccount. Back to Operations [page 439] Activate/Deactivate Recovery Subaccount (Master Only) Note Available as of Cloud Connector 2.13.1. URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/recovery/state Method PUT Request {active} Response 204 on success Errors NOT_FOUND Roles Administrator Request Properties: ● active: Boolean value indicating whether the recovery subaccount should be active (true) or inactive (false). Errors: ● NOT_FOUND (404): there is no recovery subaccount. Back to Operations [page 439] Takeover (Master Only) Caution When performing this operation, the recovery subaccount permanently takes over from the original subaccount, and the original subaccount is deleted. The recovery subaccount must be active for takeover to succeed, see Activate/Deactivate Recovery Subaccount (Master Only) [page 447]. SAP BTP Connectivity Connectivity PUBLIC 447
- 448. Note Available as of Cloud Connector 2.13.1. URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/recovery/ takeover Method POST Request Response 204 on success Errors NOT_FOUND, ILLEGAL_STATE Roles Administrator Errors: ● NOT_FOUND (404): there is no recovery subaccount. ● ILLEGAL_STATE (409): recovery subaccount is not active. Back to Operations [page 439] 1.2.2.5.9 System Mappings Manage the Cloud Connector's system mappings via API. Get All System Mappings URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/systemMappings Method GET Request 448 PUBLIC SAP BTP Connectivity Connectivity
- 449. Response [{virtualHost, virtualPort, localHost, localPort, protocol, backendType, authenticationMode, hostInHeader, description, ...}] Errors Roles Administrator, Display, Support Response: An array of objects with the following properties: ● virtualHost: Virtual host used on the cloud side (a string) ● virtualPort: Virtual port used on the cloud side (a string) ● localHost: Host on the on-premise side (a string) ● localPort: Port on the on-premise side (a string) ● protocol: Protocol used when sending requests and receiving responses (a string) ● backendType: Type of the backend (a string) ● authenticationMode: Authentication mode used on the backend side (a string). ● hostInHeader: Policy for setting the host in the response header. Available for HTTP(S) protocols only. ● totalResourcesCount: the total number of resources ● enabledResourcesCount: the number of enabled resources ● description: Description for the system mapping (a string). ● sncPartnerName: SNC name of an ABAP Server, required for RFCS communication only. ● sapRouter: SAP router route, required only if an SAP router is used. ● allowedClients: Array of strings, describing the SAP clients allowing to execute the calls in this system. Valid clients are 3 letters long. If no clients are defined here, there is no restriction – every client is allowed. Only applicable for RFC-based communication. ● blacklistedClientUsers: Array of {client, user}, describing users that are not allowed to execute the call, even if the client is listed under allowed clients. Only applicable for RFC-based communication. Get System Mapping URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/ systemMappings/ <virtualHost>:<virtualPort> Method GET Request SAP BTP Connectivity Connectivity PUBLIC 449
- 450. Response {virtualHost, virtualPort, localHost, localPort, protocol, backendType, authenticationMode, hostInHeader, description, ...} Errors Roles Administrator, Display, Support Response: An array of objects with the following properties: ● virtualHost: Virtual host used on the cloud side (a string) ● virtualPort: Virtual port used on the cloud side (a string) ● localHost: Host on the on-premise side (a string) ● localPort: Port on the on-premise side (a string) ● protocol: Protocol used when sending requests and receiving responses (a string) ● backendType: Type of the backend (a string) ● authenticationMode: Authentication mode used on the backend side (a string). ● hostInHeader: Policy for setting the host in the response header (a string). Available for HTTP(S) protocols only. ● totalResourcesCount: the total number of resources ● enabledResourcesCount: the number of enabled resources ● description: Description for the system mapping (a string). ● sncPartnerName: SNC name of an ABAP Server, required for RFCS communication only. ● sapRouter: SAP router route, required only if an SAP router is used. ● allowedClients: Array of strings, describing the SAP clients allowing to execute the calls in this system. Valid clients are 3 letters long. If no clients are defined here, there is no restriction – every client is allowed. Only applicable for RFC-based communication. ● blacklistedClientUsers: Array of {client, user}, describing users that are not allowed to execute the call, even if the client is listed under allowed clients. Only applicable for RFC-based communication. Create System Mapping (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/systemMappings Method POST 450 PUBLIC SAP BTP Connectivity Connectivity
- 451. Request {virtualHost, virtualPort, localHost, localPort, protocol, backendType, authenticationMode, hostInHeader, description, ...} Response 201 on success Errors Roles Administrator Request Properties: ● virtualHost: Virtual host used on the cloud side (a string) ● virtualPort: Virtual port used on the cloud side (a string) ● localHost: Host on the on-premise side (a string) ● localPort: Port on the on-premise side (a string) ● protocol: Protocol used when sending requests and receiving responses, which must be one of the following strings: HTTP, HTTPS, RFC, RFCS, LDAP, LDAPS, TCP, TCPS. ● backendType: Type of the backend system. Valid values are abapSys, netweaverCE, netweaverGW, applServerJava, BC, PI, hana, otherSAPsys, nonSAPsys. ● authenticationMode: Authentication mode to be used on the backend side, which must be one of the following strings: NONE, X509_GENERAL, X509_RESTRICTED, KERBEROS. ● hostInHeader: Policy for setting the host in the response header. This property is applicable to HTTP(S) protocols only, and it is optional. If set, it must be one of the following strings: internal, virtual. The default is virtual. You may also use all capital letters, i.e. INTERNAL and VIRTUAL. ● description: Description for the system mapping (string, optional). The default is no description, i.e. the empty string. ● sncPartnerName: SNC name of an ABAP Server, required for RFCS communication only. ● sapRouter: SAP router route, required only if an SAP router is used. ● allowedClients: Array of strings, describing the SAP clients allowing to execute the calls in this system. Valid clients are 3 letters long. If no clients are defined here, there is no restriction – every client is allowed. Only applicable for RFC-based communication. ● blacklistedClientUsers: Array of {client, user}, describing users that are not allowed to execute the call, even if the client is listed under allowed clients. Only applicable for RFC-based communication. Delete System Mapping (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/systemMappings Method DELETE SAP BTP Connectivity Connectivity PUBLIC 451
- 452. Request Response 204 on success Errors Roles Administrator Delete All System Mappings (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/systemMappings Method DELETE Request Response 204 on success Errors Roles Administrator Edit System Mapping URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/ systemMappings/virtualHost:virtualPort Method PUT Request {virtualHost, virtualPort, localHost, localPort, protocol, backendType, authenticationMode, hostInHeader, description, ...} Response Errors Roles Administrator 452 PUBLIC SAP BTP Connectivity Connectivity
- 453. Request Properties: ● virtualHost: Virtual host used on the cloud side (a string) ● virtualPort: Virtual port used on the cloud side (a string) These two properties are technically mandatory as they identify the system mapping to be edited or changed. They cannot be changed. However, they are also part of the URI path. If omitted from the request, they will effectively be copied from the URI path, and no error is thrown. This policy of leniency deviates from strict REST conventions, but was adopted to increase user-friendliness by avoiding unnecessary error situations. All other properties are optional. Add those properties that you want to change. ● localHost: Host on the on-premise side (a string) ● localPort: Port on the on-premise side (a string) ● protocol: Protocol used when sending requests and receiving responses, which must be one of the following strings: HTTP, HTTPS, RFC, RFCS, LDAP, LDAPS, TCP, TCPS. ● backendType: Type of the backend system. Valid values are abapSys, netweaverCE, netweaverGW, applServerJava, BC, PI, hana, otherSAPsys, nonSAPsys. ● authenticationMode: Authentication mode to be used on the backend side, which must be one of the following strings: NONE, X509_GENERAL, X509_RESTRICTED, KERBEROS. ● hostInHeader: Policy for setting the host in the response header; this property is optional. If set, it must be one of the following strings: internal, virtual. The default is virtual. You may also use all capital letters, i.e. INTERNAL and VIRTUAL. ● description: Description for the system mapping (string, optional). The default is no description, i.e. the empty string. ● sncPartnerName: SNC name of an ABAP Server, only set for RFCS communication. ● sapRouter: SAP router route, only set if an SAP router is used. ● allowedClients: Array of strings, describing the SAP clients allowing to execute the calls in this system. Valid clients are 3 letters long. If no clients are defined here, there is no restriction – every client is allowed. Only applicable for RFC-based communication. ● blacklistedClientUsers: Array of {client, user}, describing users, that are not allowed to execute the call, even if the client is listed under allowed clients. Only applicable for RFC-based communication. 1.2.2.5.10 System Mapping Resources Manage the Cloud Connector's system mapping resources via API. Get System Mapping Resources SAP BTP Connectivity Connectivity PUBLIC 453
- 454. URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/ systemMappings/virtualHost:virtualPort/ resources Method GET Request Response [{id, enabled, exactMatchOnly, websocketUpgradeAllowed, description}] Errors Roles Administrator, Display, Support Response: An array of objects, each representing a resource through the following properties: ● id: The resource itself, which, depending on the owning system mapping, is either a URL path (or the leading section of it), or a RFC function name (prefix) ● enabled: Boolean flag indicating whether the resource is enabled. ● exactMatchOnly: Boolean flag determining whether access is granted only if the requested resource is an exact match. ● websocketUpgradeAllowed: Boolean flag indicating whether websocket upgrade is allowed; this property is of relevance only if the owning system mapping employs protocol HTTP or HTTPS. ● description: Description (a string); this property is not available unless explicitly set. Get System Mapping Resource URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/ systemMappings/virtualHost:virtualPort/ resources/<encodedResourceId> Method GET Request Response {id, enabled, exactMatchOnly, websocketUpgradeAllowed, description} Errors 454 PUBLIC SAP BTP Connectivity Connectivity
- 455. Roles Administrator, Display, Support Response Properties: ● id: The resource itself, which, depending on the owning system mapping, is either a URL path (or the leading section of it), or a RFC function name (prefix) ● enabled: Boolean flag indicating whether the resource is enabled. ● exactMatchOnly: Boolean flag determining whether access is granted only if the requested resource is an exact match. ● websocketUpgradeAllowed: Boolean flag indicating whether websocket upgrade is allowed; this property is of relevance only if the owning system mapping employs protocol HTTP or HTTPS. ● description: Description (a string); this property is not available unless explicitly set. Create System Mapping Resource URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/ systemMappings/virtualHost:virtualPort/ resources Method POST Request {id, enabled, exactMatchOnly, websocketUpgradeAllowed, description} Response 201 on success Errors Roles Administrator Request Properties: ● id: The resource itself, which, depending on the owning system mapping, is either a URL path (or the leading section of it), or a RFC function name (prefix). ● enabled: Boolean flag indicating whether the resource is enabled (optional). The default value is false. ● exactMatchOnly: Boolean flag determining whether access is granted only if the requested resource is an exact match (optional). The default value is false. ● websocketUpgradeAllowed: Boolean flag indicating whether websocket upgrade is allowed (optional). The default value is false. This property is recognized only if the owning system mapping employs protocol HTTP or HTTPS. ● description: Description (a string, optional) SAP BTP Connectivity Connectivity PUBLIC 455
- 456. Tip Encoded Resource ID URI paths may contain the resource ID in order to identify the resource to be edited or deleted. A resource ID, however, may contain characters such as the forward slash that collide with the path separator of the URI and hence require an escape mechanism. We adopted the following simple escape or encoding method for a resource ID: 1. Replace all occurrences of character '+' with '+2B'. 2. Replace all occurrences of character '-' with '+2D'. 3. Replace all occurrences of character '/' with '-'. Edit System Mapping Resource URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/ systemMappings/virtualHost:virtualPort/ resources/<encodedResourceId> Method PUT Request {enabled, exactMatchOnly, websocketUpgradeAllowed, description} Response 204 on success Errors Roles Administrator Request Properties: ● enabled: Boolean flag indicating whether the resource is enabled. ● exactMatchOnly: Boolean flag determining whether access is granted only if the requested resource is an exact match. ● websocketUpgradeAllowed: Boolean flag indicating whether websocket upgrade is allowed; this property is of relevance only if the owning system mapping employs protocol HTTP or HTTPS. ● description: Description (a string); this property is not available unless explicitly set. Delete System Mapping Resource 456 PUBLIC SAP BTP Connectivity Connectivity
- 457. URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/ systemMappings/virtualHost:virtualPort/ resources/<encodedResourceId> Method DELETE Request Response 204 on success Errors NOT_FOUND Roles Administrator Errors: NOT_FOUND (404): Resource was not found Delete All System Mapping Resources URI /api/v1/configuration/subaccounts/ <region>/<subaccount>/systemMappings/ <virtualHost>:<virtualPort>/resources Method DELETE Request Response 204 on success Errors Roles Administrator 1.2.2.5.11 Domain Mappings Manage the Cloud Connector's configuration for domain mappings via API. SAP BTP Connectivity Connectivity PUBLIC 457
- 458. Get Domain Mappings URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/domainMappings Method GET Request Response [{virtualDomain, internalDomai}] Errors Roles Administrator, Display, Support Response: An array of objects, each representing a domain mapping through the following properties: ● virtualDomain: Domain used on the cloud side ● internalDomain: Domain used on the on-premise side Create Domain Mappings (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/domainMappings Method POST Request {virtualDomain, internalDomain} Response 201 Errors Roles Administrator Edit Domain Mappings (Master Only) 458 PUBLIC SAP BTP Connectivity Connectivity
- 459. URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/ domainMappings/<internalDomain> Method PUT Request {virtualDomain, internalDomain} Response 204 on success Errors NOT_FOUND Roles Administrator Request: ● virtualDomain: New virtual domain ● internalDomain: New internal domain Errors: ● NOT_FOUND (404): Domain mapping does not exist. Note The internal domain in the URI path (i.e., <internalDomain>) is the current internal domain of the domain mapping that is to be edited. It may differ from the new internal domain set in the request. Delete Domain Mappings (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/ domainMappings/<internalDomain> Method DELETE Request Response 204 on success Errors NOT_FOUND Roles Administrator Errors: ● NOT_FOUND (404): Domain mapping does not exist. SAP BTP Connectivity Connectivity PUBLIC 459
- 460. Delete All Domain Mappings (Master Only) URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/domainMappings Method DELETE Request Response 204 on success Errors Roles Administrator 1.2.2.5.12 Subaccount Service Channels Manage Cloud Connector service channels via API. Get Service Channels URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/channels Method GET Request Response [{typeDesc, details, port, enabled, connected, connectionsCount, availableConnectionsCount, connectedSinceTimeStamp}] Errors Roles Administrator, Display, Support Response: An array of objects, each of which represents a service channel through the following properties: ● typeDesc: an object specifying the service channel type through the properties typeKey and typeName. ● details 460 PUBLIC SAP BTP Connectivity Connectivity
- 461. ● port ● enabled ● connected ● connectionsCount ● availableConnectionsCount ● connectedSinceTimeStamp Create Service Channel URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/channels Method POST Request {typeKey,details,serviceNumber,connect ionCount} Response 201, Location header for new entity. Errors 400 - if a parameter is invalid or account or service channel are invalid: {type: INVALID_REQUEST, message: <msg>} Roles Administrator Request Properties: ● typeKey: type of service channel. Valid values are HANA_DB, HCPVM, RFC. ● details: ○ HANA instance name for HANA_DB ○ VM name for HCPVM ○ S/4HANA Cloud tenant host for RFC ● serviceNumber: service number, which is mapped to a port according to the type of service channel. ● connectionCount: number of connections for the channel. Delete Service Channel SAP BTP Connectivity Connectivity PUBLIC 461
- 462. URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/channels/<id> Method DELETE Request Response {} Errors Roles Administrator Edit Service Channel URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/channels/<id> Method PUT Request {typeKey,details,serviceNumber,connect ionCount} Response 204 Errors 400 - if account or service channel Id are invalid: {type: INVALID_REQUEST, message: <msg>} Roles Administrator Enable/Disable Service Channel URI /api/v1/configuration/subaccounts/ <regionHost>/<subaccount>/channels/<id>/ state Method PUT 462 PUBLIC SAP BTP Connectivity Connectivity
- 463. Request {enabled:boolean} Response Errors 400 - if account or service channel Id are invalid: {type: "INVALID_REQUEST", message: <msg>} 500 {type:"RUNTIME_FAILURE","message":"Ser vice channel could not be opened"} Roles Administrator 1.2.2.5.13 Examples Find examples on how to use the Cloud Connector's configuration REST APIs. Concept The sample code in this section (download zip file) demonstrates how to use the REST APIs provided by Cloud Connector to perform various configuration tasks. Starting with a freshly installed Cloud Connector, the samples include initial configuration of the Cloud Connector instance, connectivity setup, high availability configuration, and common tasks like backup/restore operations, as well as integration with solution management. The examples are implemented in Kotlin, a simple Java VM-based language. However, even if you are using a different language, they still show the basic use of the APIs and their parameters for specific configuration purposes. If you are not familiar with Kotlin, find a brief introduction and some typical statements below. REST API Parameters [page 464] REST API Invocation [page 464] How To Use the Examples [page 465] SAP BTP Connectivity Connectivity PUBLIC 463
- 464. REST API Parameters In almost all requests and responses, structures are encoded in JSON format. To describe the parameter details, we use Kotlin data classes. This class represents a structure that you can use as value in a request or response: data class OnlyPropertiesNamesAreRelevant( val user: String, val password: String ) The JSON representation for that class is {"user":<userValue>, "password":<passwordValue>} Encoded in Kotlin this string looks like """{"user":"$userValue", "password":"$passwordValue"}""" or as an object: val credentials = OnlyPropertiesNamesAreRelevant(userValue, passwordValue) Back to Concept [page 463] REST API Invocation (a) Fuel.put(url) (b) .header("Connection", "close") (c) .authentication().basic(user, password) (d) .jsonBody(credentials) (e) .responseObject<OnlyPropertiesNamesAreRelevant> { _, _, result -> when (result) { (f) is Result.Failure -> processRequestError(result.error) is Result.Success -> println("returned: ${result.get()}") } } .join() ● (a) - Fuel is an HTTP framework used in the examples. Important is the verb after Fuel - it is the REST API method. ● (b) - Adds a request header Connection: close, which forces a connection close after request. In the examples, this header is defined on FuelManager for all calls. ● (c) - Basic authentication is used for the call with user and password. 464 PUBLIC SAP BTP Connectivity Connectivity
- 465. ● (d) - HTTP requests with parameters require mostly JSON. The jsonBody-method adds the header Content-Type: application/json and serializes the provided object credentials to JSON. Requests without body like DELETE or GET omit body methods. ● (e) - The responseObject<ClassType>-method adds the header Accept: application/json and de-serializes the response to the specified class type. Some APIs do not have any response or non-JSON response. In such cases, the method response is used instead of responseObject<ClassType>. ● (f) - The way, how Kotlin decides between success (2xx) and failed responses. For details on the possible response status, see Configuration REST APIs [page 394]. Back to Concept [page 463] How To Use the Examples Some common details, used by different examples, were extracted to the scenario.json configuration file. This lets you use meaningful names like config.master!!.user in the examples. The file is loaded by val config = loadScenarioConfiguration() Each example also invokes disableTrustChecks() This method disables all SSL-related checks. Caution disableTrustChecks() is only used for test purposes. Do not use it in a productive environment. Both methods, as well as some common REST API parameter structures (data classes) are defined in the file Scenario Configuration [page 467]. This is the only help class under sources/. When using the examples, start with Initial Configuration [page 468]. Prerequisite is a freshly installed Cloud Connector. After a mandatory password change and defining the high availability role of the Cloud Connector instance (master or shadow), the example demonstrates how to provide a description for the instance and how to set up the UI and system certificates. Once the initial configuration is done, you can optionally proceed with these steps: ● Connect to your subaccount on BTP (Subaccount Configuration [page 470]) ● Create or restore a configuration backup (Backup And Restore Configuration [page 477]) ● Configure and connect high availability instances (High Availability Settings [page 475]) ● Integrate the Cloud Connector with the solution management infrastructure (Solution Management Integration [page 478]) SAP BTP Connectivity Connectivity PUBLIC 465
- 466. Back to Concept [page 463] Related Information scenario.json [page 466] Source Files [page 466] 1.2.2.5.13.1 scenario.json Sample Code { "subaccount": { "regionHost": "cf.eu10.hana.ondemand.com", "subaccount": "11aabbcc-7821-448b-9ecf-a7d986effa7c", "user": "xxx", "password": "xxx" }, "master": { "url": "https://localhost:8443", "user": "Administrator", "password": "test" }, "shadow": { "url": "https://localhost:8444", "user": "Administrator", "password": "test" } } 1.2.2.5.13.2 Source Files Scenario Configuration [page 467] Initial Configuration [page 468] Subaccount Configuration [page 470] High Availability Settings [page 475] Backup And Restore Configuration [page 477] Solution Management Integration [page 478] 466 PUBLIC SAP BTP Connectivity Connectivity
- 467. 1.2.2.5.13.2.1 Scenario Configuration Sample Code package com.sap.scc.examples import com.github.kittinunf.fuel.core.FuelError import com.google.gson.Gson import java.io.File import java.security.SecureRandom import java.security.cert.X509Certificate import javax.net.ssl.* data class CloudConnector( val url: String, var user: String, var password: String ) fun disableTrustChecks() { try { HttpsURLConnection.setDefaultHostnameVerifier { hostname: String, session: SSLSession -> true } val context: SSLContext = SSLContext.getInstance("TLS") val trustAll: X509TrustManager = object : X509TrustManager { override fun checkClientTrusted(chain: Array<X509Certificate>, authType: String) {} override fun checkServerTrusted(chain: Array<X509Certificate>, authType: String) {} override fun getAcceptedIssuers(): Array<X509Certificate> { return arrayOf() } } context.init(null, arrayOf(trustAll), SecureRandom()) HttpsURLConnection.setDefaultSSLSocketFactory(context.socketFactory) } catch (e: Exception) { e.printStackTrace() } } class ScenarioConfiguration { var subaccount: SubaccountParameters? = null var master: CloudConnector? = null var shadow: CloudConnector? = null } data class SubaccountParameters( val regionHost: String, val subaccount: String, val user: String, val password: String, var locationId: String? = null ) data class SccCertificate( var subjectDN: String? = null, var issuer: String? = null, var notAfter: String? = null, var notBefore: String? = null, var subjectAltNames: List<SubjectAltName>? = null ) data class SubjectAltName( var type: String? = null, var value: String? = null ) internal fun loadScenarioConfiguration(): ScenarioConfiguration { println("scenario.json will be loaded from $ {File("scenario.json").absolutePath}") return Gson().fromJson(File("scenario.json").readText(), ScenarioConfiguration::class.java) } SAP BTP Connectivity Connectivity PUBLIC 467
- 468. internal fun processRequestError(error: FuelError) { println("failed with ${error.message} ${String(error.errorData)}") throw RuntimeException("Stop here. ") } 1.2.2.5.13.2.2 Initial Configuration Sample Code package com.sap.scc.examples //import com.sap.scc.examples.SccCertificate import com.github.kittinunf.fuel.Fuel import com.github.kittinunf.fuel.core.BlobDataPart import com.github.kittinunf.fuel.core.FuelManager import com.github.kittinunf.fuel.core.Method import com.github.kittinunf.fuel.core.extensions.authentication import com.github.kittinunf.fuel.gson.responseObject import com.github.kittinunf.result.Result import java.io.ByteArrayInputStream import java.io.File /* This example shows how to use REST APIs to perform the initial configuration of a master instance after installing and starting the Cloud Connector. As a prerequisite you need to install and start the Cloud Connector. The example begins with changing the initial password, setting the instance to the master role, edit the description, and upload UI and system certificates. For the certificates used by Cloud Connector in order to access the UI and for the system certificate used to access backend systems, we simply upload the already available PKCS#12 certificates uiCert.p12 and systemCert.p12 encrypted with the password "test1234". Cloud Connector also provides other options for certificate management, please take a look at the documentation. The configuration details for master and shadow instances can be found in scenario.json. */ fun main() { //Cloud Connector distribution generates only an untrusted self-signed certificate. //So for this demonstration use case we need to deactivate all trust checks. disableTrustChecks() //Use 'Connection: close' header, to make stateless communication more efficient FuelManager.instance.baseHeaders = mapOf("Connection" to "close") //Add output of cURL commands for revision //FuelManager.instance.addRequestInterceptor(LogRequestAsCurlInterceptor) //Load configuration from property file val config = loadScenarioConfiguration() //Change the initial password Fuel.put("${config.master!!.url}/api/v1/configuration/connector/ authentication/basic") .authentication().basic(config.master!!.user, "manage") .body("""{"oldPassword":"manage", "newPassword":"$ {config.master!!.password}"}""") .response { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) 468 PUBLIC SAP BTP Connectivity Connectivity
- 469. is Result.Success -> println("Password successfully set to $ {config.master!!.password}") } } .join() //Set the High-Availability Role to master, use "shadow" if you want to set it to shadow Fuel.put("${config.master!!.url}/api/v1/configuration/connector/haRole") .authentication().basic(config.master!!.user, config.master!!.password) .body("master") .response { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> println("high-availability role successfully set to 'master'") } } .join() //Edit Common Description Fuel.put("${config.master!!.url}/api/v1/configuration/connector") .authentication().basic(config.master!!.user, config.master!!.password) .body("""{"description":"<description of Cloud Connector instance>"}""") .responseObject<SccDescriptionResponse> { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> println(result.get()) } } .join() //Upload a PKCS#12 Certificate as UI Certificate val uiCertificateFormData = listOf("password" to "test1234", "keyPassword" to "test1234") Fuel.upload( "${config.master!!.url}/api/v1/configuration/connector/ui/ uiCertificate", Method.PUT, uiCertificateFormData ) .add(BlobDataPart(ByteArrayInputStream(File("uiCert.p12").readBytes()) , name = "pkcs12")) .authentication().basic(config.master!!.user, config.master!!.password) .response { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> println("PKCS#12 Certificate 'uiCert.p12' successfully uploaded") } } .join() //Upload a PKCS#12 Certificate as as System Certificate val systemCertificateFormData = listOf("password" to "test1234", "keyPassword" to "test1234") Fuel.upload( "${config.master!!.url}/api/v1/configuration/connector/onPremise/ systemCertificate", Method.PUT, systemCertificateFormData ) .add(BlobDataPart(ByteArrayInputStream(File("systemCert.p12").readByte s()), name = "pkcs12")) .authentication().basic(config.master!!.user, config.master!!.password) .response { _, _, result -> when (result) { SAP BTP Connectivity Connectivity PUBLIC 469
- 470. is Result.Failure -> processRequestError(result.error) is Result.Success -> println("PKCS#12 Certificate 'systemCert.p12' successfully uploaded") } } .join() } //Data structures used by REST calls in this scenario data class SccDescriptionResponse( var role: String, var description: String ) 1.2.2.5.13.2.3 Subaccount Configuration Sample Code package com.sap.scc.examples import com.github.kittinunf.fuel.Fuel import com.github.kittinunf.fuel.core.FuelManager import com.github.kittinunf.fuel.core.extensions.authentication import com.github.kittinunf.fuel.gson.jsonBody import com.github.kittinunf.fuel.gson.responseObject import com.github.kittinunf.result.Result /* This example shows how to use REST APIs to configure and connect a subaccount in cloud connector. The example begins with (1) connecting of the subaccount, then we create a system (2) for an HTTP service and (3) for an RFC service. The configuration details for master and shadow instances can be found in scenario.json. */ fun main() { //Cloud Connector distribution generates only an untrusted self-signed certificate. //So for this demonstration use case we need to deactivate all trust checks. disableTrustChecks() //Use 'Connection: close' header, to make stateless communication more efficient FuelManager.instance.baseHeaders = mapOf("Connection" to "close") //Add output of cURL commands for revision //FuelManager.instance.addRequestInterceptor(LogRequestAsCurlInterceptor) //1.1. Create and connect subaccount //Load configuration from property file val config = loadScenarioConfiguration() //Some cloud regions require 2-Factor-Authentication println("Enter MFA (aka 2FA) token, if required: ") var token = readLine() ?: "" //Parameters required to establish the connection to the subaccount (aka the secure tunnel) var subaccountCreateData = SubaccountConfiguration( config.subaccount!!.regionHost, config.subaccount!!.subaccount, config.subaccount!!.user, "" + config.subaccount!!.password + token, locationId = config.subaccount!!.locationId ) //Optional: Initialize the map to work with generated _links 470 PUBLIC SAP BTP Connectivity Connectivity
- 471. //If you don't like to use _links, you can easily compute the entity links var subaccountLinks: Map<String, HalLink> = mapOf() Fuel.post("${config.master!!.url}/api/v1/configuration/subaccounts") .authentication().basic(config.master!!.user, config.master!!.password) .jsonBody(subaccountCreateData) .responseObject<SubaccountInfo> { _, response, result -> when (result) { is Result.Success -> { val subaccountLocation = response.header("Location").first() println("1.1. subaccount was created under: $subaccountLocation") println("subaccount: ${result.get()} ") //GET details as SubaccountInfo every time possible by invoking //https://<SCC>/api/v1/configuration/subaccounts/ <regionHost>/<subaccountId> subaccountLinks = result.get()._links } is Result.Failure -> processRequestError(result.error) } } .join() //1.2. From time to time it is necessary to extend the validity of the subaccount - refresh subaccount //Again some cloud landscapes require 2-Factor-Authentication println("Enter MFA (aka 2FA) token for refresh, if required: ") token = readLine() ?: "" Fuel.post(subaccountLinks["validity"]!!.href) .authentication().basic(config.master!!.user, config.master!!.password) .jsonBody(SubaccountRefreshCred(config.subaccount!!.user, "" + config.subaccount!!.password + token)) .responseObject<SubaccountInfo> { _, _, result -> when (result) { is Result.Success -> println("1.2. validity of the subaccount was extended") is Result.Failure -> processRequestError(result.error) } } .join() //2.1. Create a system mapping (aka access control) for an HTTP service val httpSystem = SystemMapping( "virtual.host", "vport", "local", "lport", CommunicationProtocol.HTTPS, BackendType.abapSys, hostInHeader = HostInHeader.INTERNAL ) var httpSystemLinks: Map<String, HalLink> = mapOf() Fuel.post(subaccountLinks["systemMappings"]!!.href) .authentication().basic(config.master!!.user, config.master!!.password) .jsonBody(httpSystem) .responseString { _, response, result -> when (result) { is Result.Success -> { val httpSystemMappingLocation = response.header("Location").first() println("2.1. system mapping was created under: $httpSystemMappingLocation") //GET the details about the system mapping by invoking //https://<SCC>/api/v1/configuration/subaccounts/ <regionHost>/<subaccountId>/systemMappings/<vhost>:<vport> Fuel.get(httpSystemMappingLocation) .authentication().basic(config.master!!.user, config.master!!.password) .responseObject<SystemMapping> { _, _, result -> when (result) { SAP BTP Connectivity Connectivity PUBLIC 471
- 472. is Result.Success -> { println("system mapping: ${result.get()}") httpSystemLinks = result.get()._links } is Result.Failure -> processRequestError(result.error) } } .join() } is Result.Failure -> processRequestError(result.error) } } .join() //2.2 Add an allowed resource to the system mapping. Since this system mapping points to an HTTP service, use HTTP resource parameters Fuel.post(httpSystemLinks["resources"]!!.href) .authentication().basic(config.master!!.user, config.master!!.password) .jsonBody(HttpResource("/", exactMatchOnly = false)) .responseString { _, response, result -> when (result) { is Result.Success -> { val httpResourceLocation = response.header("Location").first() println("2.2. http resource was created under: $httpResourceLocation") //GET the details about the resource by invoking //https://<SCC>/api/v1/configuration/subaccounts/ <regionHost>/<subaccountId>/systemMappings/<vhost>:<vport>/<encoded-id> //<encoded-id> -> replace '/' with '-' Fuel.get(httpResourceLocation) .authentication().basic(config.master!!.user, config.master!!.password) .responseObject<HttpResource> { _, _, result -> when (result) { is Result.Success -> println("http resource: $ {result.get()}") is Result.Failure -> processRequestError(result.error) } } .join() } is Result.Failure -> processRequestError(result.error) } } .join() //3.1 Create a system mapping for an RFC service var rfcSystemLinks: Map<String, HalLink> = mapOf() Fuel.post(subaccountLinks["systemMappings"]!!.href) .authentication().basic(config.master!!.user, config.master!!.password) .jsonBody( SystemMapping( "virtual.host", "rfcport", "local", "rfcport", CommunicationProtocol.RFCS, BackendType.abapSys ) ) .responseString { _, response, result -> when (result) { is Result.Success -> { val rfcSystemMappingLocation = response.header("Location").first() 472 PUBLIC SAP BTP Connectivity Connectivity
- 473. println("3.1. system mapping was created under: $rfcSystemMappingLocation") //GET the details about the system mapping by invoking //https://<SCC>/api/v1/configuration/subaccounts/ <regionHost>/<subaccountId>/systemMappings/<vhost>:<vport> Fuel.get(rfcSystemMappingLocation) .authentication().basic(config.master!!.user, config.master!!.password) .responseObject<SystemMapping> { _, _, result -> when (result) { is Result.Success -> { println("system mapping: ${result.get()}") rfcSystemLinks = result.get()._links } is Result.Failure -> processRequestError(result.error) } } .join() } is Result.Failure -> processRequestError(result.error) } } .join() //3.2 Now add the function module RFC_SYSTEM_INFO as an allowed resource to the system mapping val rfcResource = RfcResource("RFC_SYSTEM_INFO") Fuel.post(rfcSystemLinks["resources"]!!.href) .authentication().basic(config.master!!.user, config.master!!.password) .jsonBody(rfcResource) .responseString { _, response, result -> when (result) { is Result.Success -> { val resourceLocation = response.header("Location").first() println("3.2. rfc resource was created under: $resourceLocation") //GET the details about the resource by invoking //https://<SCC>/api/v1/configuration/subaccounts/ <regionHost>/<subaccountId>/systemMappings/<vhost>:<vport>/<encoded-id> //<encoded-id> -> replace '/' with '-' Fuel.get(resourceLocation) .authentication().basic(config.master!!.user, config.master!!.password) .responseObject<RfcResource> { _, _, result -> when (result) { is Result.Success -> println("rfc resource: $ {result.get()}") is Result.Failure -> processRequestError(result.error) } } .join() } is Result.Failure -> processRequestError(result.error) } } .join() } //Data structures used by REST calls in this scenario //Nullable properties are optional data class SubaccountConfiguration( var regionHost: String, var subaccount: String, var cloudUser: String, var cloudPassword: String, var displayName: String? = null, var locationId: String? = null SAP BTP Connectivity Connectivity PUBLIC 473
- 474. ) data class SubaccountInfo( val displayName: String, val regionHost: String, val subaccount: String, val tunnel: SubaccountTunnelInfo, val user: String, val _links: Map<String, HalLink> ) data class SubaccountTunnelInfo( val state: String, //Connected val connectedSince: String, //timestamp formatted with client locale val connections: Int, val applicationConnections: List<String>, val serviceChannels: List<String>, val subaccountCertificate: X509CertificateInfo, ) data class X509CertificateInfo( val notAfter: String, val notBefore: String, val subjectDN: String, val issuer: String ) data class HalLink(val href: String) data class SubaccountRefreshCred( var cloudUser: String, var cloudPassword: String ) data class SystemMapping( val virtualHost: String, val virtualPort: String, val localHost: String, val localPort: String, val protocol: CommunicationProtocol, val backendType: BackendType, val sncPartnerName: String? = null, val hostInHeader: HostInHeader? = null, val sapRouter: String? = null, val authenticationMode: AuthenticationMode = AuthenticationMode.NONE, val description: String = "", ) { val _links: Map<String, HalLink> = mapOf() } enum class CommunicationProtocol { HTTP, HTTPS, RFC, RFCS, LDAP, LDAPS, TCP, TCPS } enum class BackendType { abapSys, netweaverCE, applServerJava, BC, PI, hana, netweaverGW, otherSAPsys, nonSAPsys } enum class HostInHeader { INTERNAL, VIRTUAL } enum class AuthenticationMode { NONE, X509_CERTIFICATE, X509_CERTIFICATE_LOCAL, KERBEROS } data class HttpResource( val id: String, //URI path val enabled: Boolean = true, val exactMatchOnly: Boolean = true, val webSocketUpgradeAllowed: Boolean = true, val description: String = "" ) data class RfcResource( val id: String, //Function module or prefix for function module val enabled: Boolean = true, val exactMatchOnly: Boolean = true, val description: String = "" 474 PUBLIC SAP BTP Connectivity Connectivity
- 475. ) 1.2.2.5.13.2.4 High Availability Settings Sample Code package com.sap.scc.examples import com.github.kittinunf.fuel.Fuel import com.github.kittinunf.fuel.core.FuelManager import com.github.kittinunf.fuel.core.Headers import com.github.kittinunf.fuel.core.extensions.authentication import com.github.kittinunf.fuel.gson.jsonBody import com.github.kittinunf.fuel.gson.responseObject import com.github.kittinunf.result.Result import java.net.URL /* This example shows how to use REST APIs to change high availability settings of the Cloud Connector instances. As a prerequisite you need to install and start a shadow and a master instance. Afterwards perform the initial configuration of the master instance (see InitialConfiguration.kt). The configuration details for master and shadow instances can be found in scenario.json. */ fun main() { //Cloud Connector distribution generates only an untrusted self-signed certificate. //So for this demonstration use case we need to deactivate all trust checks. disableTrustChecks() //Use 'Connection: close' header, to make stateless communication more efficient FuelManager.instance.baseHeaders = mapOf("Connection" to "close") //Add output of cURL commands for revision //FuelManager.instance.addRequestInterceptor(LogRequestAsCurlInterceptor) //Load configuration from property file val config = loadScenarioConfiguration() //The high-availability role 'master' in Cloud Connector instance 'master' is already set in the initial configuration. //Set the high-availability role to 'shadow' in Cloud Connector instance 'shadow' Fuel.put("${config.shadow!!.url}/api/v1/configuration/connector/haRole") .authentication().basic(config.shadow!!.user, config.shadow!!.password) .body("shadow") .response { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> println("high-availability role successfully set to 'shadow'") } } .join() //Enable HA in the master instance and define the allowed shadow hosts Fuel.put("${config.master!!.url}/api/v1/configuration/connector/ha/master/ config") .header(Headers.CONTENT_TYPE, "application/json") SAP BTP Connectivity Connectivity PUBLIC 475
- 476. .authentication().basic(config.master!!.user, config.master!!.password) .body("""{"haEnabled":"true", "allowedShadowHost":"$ {URL(config.shadow!!.url).host}"}""") .responseObject<HAMasterConfiguration> { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> { val masterConfig = result.get() println("Master configuration: $masterConfig ") } } } .join() //The configuration of the shadow instance var shadowConfig: HAShadowConfiguration? = null //Get the current configuration Fuel.get("${config.shadow!!.url}/api/v1/configuration/connector/ha/shadow/ config") .authentication().basic(config.shadow!!.user, config.shadow!!.password) .responseObject<HAShadowConfiguration> { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> shadowConfig = result.get() } } .join() //Edit the retrieved configuration and set it shadowConfig!!.masterPort = "${URL(config.master!!.url).port}" shadowConfig!!.masterHost = URL(config.master!!.url).host shadowConfig!!.ownHost = URL(config.master!!.url).host Fuel.put("${config.shadow!!.url}/api/v1/configuration/connector/ha/shadow/ config") .authentication().basic(config.shadow!!.user, config.shadow!!.password) .jsonBody(shadowConfig!!) .responseObject<HAShadowConfiguration> { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> shadowConfig = result.get() } } .join() //Set the HA link of both cloud connector instances to 'CONNECT' Fuel.post("${config.shadow!!.url}/api/v1/configuration/connector/ha/ shadow/state") .header(Headers.CONTENT_TYPE, "application/json") .authentication().basic(config.shadow!!.user, config.shadow!!.password) .body("""{"op":"CONNECT", "user":"${config.master!!.user}", "password":"${config.master!!.password}"}""") .response { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> println("Master (${config.master!!.url}) and shadow (${config.shadow!!.url}) successfully connected") } } .join() } //Data structures used by REST calls in this scenario //Structure used to read the high availability settings for a Cloud Connector master instance data class HAMasterConfiguration( var haEnabled: Boolean? = null, var allowedShadowHost: String? = null ) 476 PUBLIC SAP BTP Connectivity Connectivity
- 477. //Structure used to read and edit the high availability settings for a Cloud Connector shadow instance data class HAShadowConfiguration( var masterPort: String, var masterHost: String, var ownHost: String? = null, var checkIntervalInSeconds: Int?, var takeoverDelayInSeconds: Int?, var connectTimeoutInMillis: Int?, var requestTimeoutInMillis: Int? ) 1.2.2.5.13.2.5 Backup And Restore Configuration Sample Code package com.sap.scc.examples import com.github.kittinunf.fuel.Fuel import com.github.kittinunf.fuel.core.BlobDataPart import com.github.kittinunf.fuel.core.FuelManager import com.github.kittinunf.fuel.core.Headers import com.github.kittinunf.fuel.core.Method import com.github.kittinunf.fuel.core.extensions.authentication import com.github.kittinunf.result.Result import java.io.ByteArrayInputStream import java.io.File /* This example shows how to use REST APIs to perform the Backup and Restore of the Cloud Connector configuration. As a prerequisite you have a stable Cloud Connector configuration and you want to save the backup for later use. The configuration details can be found in scenario.json. */ fun main() { //Cloud Connector distribution generates only an untrusted self-signed certificate. //So for this demonstration use case we need to deactivate all trust checks. disableTrustChecks() //Use 'Connection: close' header, to make stateless communication more efficient FuelManager.instance.baseHeaders = mapOf("Connection" to "close") //Add output of cURL commands for revision //FuelManager.instance.addRequestInterceptor(LogRequestAsCurlInterceptor) //Load configuration from property file val config = loadScenarioConfiguration() //Create the backup configuration of the cloud connector "master". Fuel.post("${config.master!!.url}/api/v1/configuration/backup") .header(Headers.CONTENT_TYPE, "application/json") .authentication().basic(config.master!!.user, config.master!!.password) .body("""{"password":"my-very-secret-password"}""") .response { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> File("backup.zip").writeBytes(result.get()) } SAP BTP Connectivity Connectivity PUBLIC 477
- 478. } .join() //Restore the backup configuration if some fatal accidental changes should be reverted val formData = listOf("password" to "my-very-secret-password") Fuel.upload("${config.master!!.url}/api/v1/configuration/backup", Method.PUT, formData) .add(BlobDataPart(ByteArrayInputStream(File("backup.zip").readBytes()) , name = "backup")) .authentication().basic(config.master!!.user, config.master!!.password) .response { _, _, result -> when (result) { is Result.Failure -> processRequestError(result.error) is Result.Success -> println("Backup configuration successfully restored in (${config.master!!.url}) ") } } .join() } 1.2.2.5.13.2.6 Solution Management Integration Sample Code package com.sap.scc.examples import com.github.kittinunf.fuel.Fuel import com.github.kittinunf.fuel.core.FuelManager import com.github.kittinunf.fuel.core.extensions.authentication import com.github.kittinunf.fuel.gson.jsonBody import com.github.kittinunf.fuel.gson.responseObject import com.github.kittinunf.result.Result import java.io.File /* This example shows how to use REST APIs to configure the integration with SAP solution management. In most cases it should be only necessary to pass a boolean flag in order to enable or disable solution management integration. It is expected that SAP host agent is already installed on the host as prerequisite for solution management integration. This example executes requests against master and shadow instances. The shadow instance is optional. Ignore the requests to shadow instance if there is only a master instance in your environment. The configuration details for master and shadow instances can be found in scenario.json. */ fun main() { //Cloud Connector distribution generates only an untrusted self-signed certificate. //So for this demonstration use case we need to deactivate all trust checks. disableTrustChecks() //Use 'Connection: close' header, to make stateless communication more efficient FuelManager.instance.baseHeaders = mapOf("Connection" to "close") 478 PUBLIC SAP BTP Connectivity Connectivity
- 479. //Add output of cURL commands for revision //FuelManager.instance.addRequestInterceptor(LogRequestAsCurlInterceptor) //Load configuration from property file val config = loadScenarioConfiguration() //First we check the current configuration of solution management Fuel.get("${config.master!!.url}/api/v1/configuration/connector/ solutionManagement") .authentication().basic(config.master!!.user, config.master!!.password) .responseObject<SolutionManagementConfiguration> { _, _, result -> when (result) { is Result.Success -> println("response: ${result.get()}") is Result.Failure -> processRequestError(result.error) } } .join() //Configure the hostAgent path on the shadow instance //Invoking this API on a shadow instance changes only the configuration. //Only when invoking it on a master instance it also activates solution management integration. //Note: This step is not required if host agent is installed at the default location Fuel.post("${config.shadow!!.url}/api/v1/configuration/connector/ solutionManagement") .authentication().basic(config.shadow!!.user, config.shadow!!.password) .jsonBody(SolutionManagementConfiguration(hostAgentPath = "/path/to/ hostAgent")) .response { _, _, result -> when (result) { is Result.Success -> println("new path to host agent was set") is Result.Failure -> processRequestError(result.error) } } .join() //Turns on the solution management integration. //Note: this operation is possible only on the master instance. //In case of an HA setup, the flag enabled is propagated to the shadow automatically. //Note: optionally you can set here the new path for host agent and enable DSR. Fuel.post("${config.master!!.url}/api/v1/configuration/connector/ solutionManagement") .authentication().basic(config.master!!.user, config.master!!.password) .jsonBody(SolutionManagementConfiguration()) .response { _, _, result -> when (result) { is Result.Success -> println("solution management is activated") is Result.Failure -> processRequestError(result.error) } } .join() //Turns off the solution management integration. //Note: this operation is possible only on the master instance. //In case of an HA setup, the flag not enabled is propagated to the shadow automatically Fuel.delete("${config.master!!.url}/api/v1/configuration/connector/ solutionManagement") .authentication().basic(config.master!!.user, config.master!!.password) .response { _, _, result -> when (result) { is Result.Success -> println("solution management is deactivated") is Result.Failure -> processRequestError(result.error) } SAP BTP Connectivity Connectivity PUBLIC 479
- 480. } .join() //Registration file with LMDB model can be downloaded by following request. //This file can be used for a manual upload to solution management. //If solution management integration is active,the updates are triggered by configuration changes automatically. Fuel.get("${config.master!!.url}/api/v1/configuration/connector/ solutionManagement/registrationFile") .authentication().basic(config.master!!.user, config.master!!.password) .response { _, _, result -> when (result) { is Result.Success -> File("lmdbModel.zip").writeBytes(result.get()) is Result.Failure -> processRequestError(result.error) } } .join() } //Data structures used by REST calls in this scenario //Nullable properties are optional data class SolutionManagementConfiguration( var hostAgentPath: String? = null, var enabled: Boolean? = null, var dsrEnabled: Boolean? = null ) 1.2.2.6 Configure an On-Premise User Store Configure SAP BTP Java applications to use your corporate LDAP server or on-premise SAP system as a user store. Prerequisites ● Your have configured your Java cloud application to use an on-premise user provider and to consume its users via the Cloud Connector. To do this, execute the following command: neo deploy --host <host> --account <subaccount name> --application <application name> --source <path to WAR file> --user <e-mail or user name> -- vm-arguments "-Dcom.sap.cloud.security.um.user_provider_name=onpremise - Dcom.sap.cloud.security.um.destination_name=onpremiseumconnector" ● You have created a connectivity destination to configure the on-premise user provider, using the following paremeters: Name=onpremiseumconnector Type=HTTP URL= http://scc.scim:80/scim/v1 Authentication=NoAuthentication CloudConnectorVersion=2 ProxyType=OnPremise ● You are using only one domain for user authentication. Authentication to multiple domains including sub- domains is not supported. 480 PUBLIC SAP BTP Connectivity Connectivity
- 481. For more information, see also On-Premise User Store. Context If you configure your SAP BTP applications to use the corporate LDAP server or on-premise SAP system as a user store, the platform doesn't need to keep the entire user database but requests the necessary information from the on-premise user store. Java applications running on SAP BTP can use the on-premise system to check credentials, search for users, and retrieve details. In addition to the user information, the cloud application may request information about the groups a user belongs to. One way a Java cloud application can define user authorizations is by checking a user's membership to specific groups in the on-premise user store. The application uses the roles for the groups defined in SAP BTP. For more information, see Managing Roles. Note The configuration steps below are applicable only for Microsoft Active Directory (AD). Procedure 1. From the main menu, choose Configuration. 2. From the Cloud User Store section on the Cloud tab, choose Edit. 3. To connect to LDAP using SSL, select Secure. 4. Manage the hosts and ports for your LDAP servers: SAP BTP Connectivity Connectivity PUBLIC 481
- 482. ○ Choose the Add icon to add a host. Note Multiple hosts are currently not supported. ○ Choose Edit to edit the selected host. ○ Choose Delete to delete the selected hosts. 5. Enter the user name and password for the service user that is used to contact the LDAP system. Note The user name must be fully qualified, including the AD domain suffix, for example, [email protected]. 6. In User Path, specify the LDAP subtree that contains the users. 7. In Group Path, specify the LDAP subtree that contains the groups. 8. Choose Save. Related Information Using an SAP System as an On-Premise User Store Use LDAP for Authentication [page 503] Managing Destinations [page 38] 1.2.2.7 Using Service Channels Configure Cloud Connector service channels to connect your on-premise network to specific services on SAP BTP. Context Cloud Connector service channels provide access from an external network to certain services on SAP BTP. The called services are not exposed to direct access from the Internet. The Cloud Connector ensures that the connection is always available and communication is secured. 482 PUBLIC SAP BTP Connectivity Connectivity
- 483. Service Channel Type Description SAP HANA Database on SAP BTP The service channel for the SAP HANA Database lets you access SAP HANA databases that run in the Cloud from da tabase clients (for example, clients using ODBC/JDBC driv ers). You can use the service channel to connect database, analytical, BI, or replication tools to your SAP HANA data base in your SAP BTP subaccount. RFC Connection to SAP BTP ABAP environment The service channel for RFC supports calls from on-premise systems to the SAP BTP ABAP environment using RFC. Next Steps Configure a Service Channel for an SAP HANA Database [page 483] Connect DB Tools to SAP HANA via Service Channels [page 486] Configure a Service Channel for RFC [page 487] Related Information Service Channels: Port Overview [page 489] 1.2.2.7.1 Configure a Service Channel for an SAP HANA Database Using Cloud Connector service channels, you can establish a connection to an SAP HANA database in SAP BTP that is not directly exposed to external access. Context The service channel for SAP HANA Database allows accessing SAP HANA databases running in the cloud via ODBC/JDBC. You can use the service channel to connect database, analytical, BI, or replication tools to an SAP HANA database in your SAP BTP subaccount. In the Cloud Foundry environment, this feature is only available in regions (data centers) that provide the SAP HANA service (i.e., SAP data centers (openstack), Azure and AWS). In AWS regions, you can currently use the service channel only for SAP HANA databases provisioned before June 4, 2018 (old version). Using the SAP HANA service provisioned after June 4, 2018 (new version on AWS and GCP), you can access SAP HANA SAP BTP Connectivity Connectivity PUBLIC 483
- 484. databases directly, without going through the Cloud Connector, see Connecting to an SAP HANA Service Instance Directly from SAP HANA Clients. To find detailed information for a specific Cloud Foundry region and SAP HANA service version, see Find the Right Guide. This feature is only available if your data center provides the SAP HANA service. Alternatively, you can access SAP HANA databases directly, without going through the Cloud Connector, see Connecting to an SAP HANA Service Instance Directly from SAP HANA Clients. Note The following procedure requires a productive SAP HANA instance that is available in the same subaccount. You cannot access an SAP HANA instance that is owned by a different subaccount within the same or another global account (shared SAP HANA database). See also Sharing Databases with Other Subaccounts. Procedure 1. From your subaccount menu, choose On-Premise To Cloud. 2. Choose Add (+). 3. In the Add Service Channel dialog, leave the default value HANA Database in the <Type> field. 4. Choose Next. 5. Choose the SAP HANA instance name. If you cannot select it from the drop-down list, enter the instance name manually. In the Neo environment, it must match one of the names (IDs) shown in the cockpit under SAP HANA/SAP ASE Databases & Schemas , in the <DB/Schema ID> column. Note The SAP HANA instance name is case-sensitive. In the Cloud Foundry environment (SAP BTP), the format of the SAP HANA instance name consists of the Cloud Foundry space name, the database name and the database ID. Example: test:testInstance:3fcc976d-457a-474e-975b-e572600f474e:de19c262-a1fc-4096-bfce-1c41388e4b49 484 PUBLIC SAP BTP Connectivity Connectivity
- 485. Where ○ test: Cloud Foundry space name ○ testInstance: tenant database instance name ○ 3fcc976d-457a-474e-975b-e572600f474e:de19c262-a1fc-4096-bfce-1c41388e4b49: database ID 6. Specify the local instance number. This is a double-digit number which computes the local port used to access the SAP HANA instance in the cloud. The local port is derived from the local instance number as 3<instance number>15. For example, if the instance number is 22, then the local port is 32215. The local instance number must not be 00. This instance number might cause problems with some SAP HANA clients. 7. Specify the number of physical connections to SAP BTP. The default value is 1. One physical connection can open various virtual connections through multiplexing. 8. Leave Enabled selected to establish the channel immediately after clicking Finish, or unselect it if you don't want to establish the channel immediately. 9. Choose Finish. Next Steps Once you have established an SAP HANA Database service channel, you can connect on-premise database or BI tools to the selected SAP HANA database in the cloud. This may be done by using <cloud_connector_host>:<local_HANA_port> in the JDBC/ODBC connect strings. See Connect DB Tools to SAP HANA via Service Channels [page 486]. SAP BTP Connectivity Connectivity PUBLIC 485
- 486. 1.2.2.7.2 Connect DB Tools to SAP HANA via Service Channels Context You can connect database, BI, or replication tools running in on-premise network to an SAP HANA database on SAP BTP using service channels of the Cloud Connector. You can also use the high availability support of the Cloud Connector on a database connection. The picture below shows the landscape in such a scenario. Follow the steps below to set up failover support, configure a service channel, and connect on-premise DB tools via JDBC or ODBC to the SAP HANA database. ● For more information on using SAP HANA instances, see Using an SAP HANA XS Database System ● For the connection string via ODBC you need a corresponding database user and password (see step 4 below). See also: Creating Database Users. ● Find detailed information on failover support in the SAP HANA Administration Guide: Configuring Clients for Failover. Note This link points to the latest release of SAP HANA Administration Guide. Refer to the SAP BTP Release Notes to find out which SAP HANA SPS is supported by SAP BTP. Find the list of guides for earlier releases in the Related Links section below. 486 PUBLIC SAP BTP Connectivity Connectivity
- 487. Procedure 1. To establish a highly available connection to one or multiple SAP HANA instances in the cloud, we recommend that you make use of the failover support of the Cloud Connector. Set up a master and a shadow instance. See Install a Failover Instance for High Availability [page 508]. 2. In the master instance, configure a service channel to the SAP HANA database of the SAP BTP subaccount to which you want to connect. If, for example, the chosen HANA instance is 01, the port of the service channel is 30115. See also Configure a Service Channel for an SAP HANA Database [page 483]. 3. Connect on-premise DB tools via JDBC to the SAP HANA database by using the following connection string: Example: jdbc:sap://<cloud-connector-master-host>:30115;<cloud-connector-shadow-host>: 30115[/?<options>] The SAP HANA JDBC driver supports failover out of the box. All you need is to configure the shadow instance of the Cloud Connector as a failover server in the JDBC connection string. The different options supported in the JDBC connection string are described in: Connect to SAP HANA via JDBC 4. You can also connect on-premise DB tools via ODBC to the SAP HANA database. Use the following connection string: "DRIVER=HDBODBC32;UID=<user>;PWD=<password>;SERVERNODE=<cloud-connector- master-host>:30115;<cloud-connector-shadow-host>:30115;" Related Information Guides for earlier releases of SAP HANA 1.2.2.7.3 Configure a Service Channel for RFC For scenarios that need to call from on-premise systems to SAP BTP ABAP environment using RFC, you can establish a connection to an ABAP Cloud tenant host. To do this, select On-Premise to Cloud Service Channels in the Cloud Connector. Prerequisites SAP BTP Connectivity Connectivity PUBLIC 487
- 488. ● When using the default connectivity setup with the Cloud Foundry subaccount in which the system has been provisioned, you can use a service channel without additional configuration, as long as the system is a single-tenant system. ● When using connectivity via a Neo subaccount, you must create a communication arrangement for the scenario SAP_COM_0200. For more information, see Create a Communication Arrangement for Cloud Connector Integration (documentation for ABAP environment on SAP BTP). Procedure 1. From your subaccount menu, choose On Premise To Cloud. 2. Choose the Add (+) icon. 3. In the Add Service Channel dialog, select ABAP Cloud System from the drop-down list of supported channel types. 4. Choose Next. The ABAP Cloud System dialog opens. 5. Enter the <ABAP Cloud Cloud Tenant Host> that you want to connect to. Note For SAP BTP ABAP environment, the tenant host is <serviceinstanceguid>.abap.<region>.hana.ondemand.com (note that this is not the frontend address with the abap-web subdomain). The region is, for example, eu10 or us10. 6. In the same dialog window, define the <Local Instance Number> under which the ABAP Cloud system is reachable for the client systems. You can enter any instance number for which the port is not used yet on the Cloud Connector host. The port numbers result from the following pattern: 33<LocalInstanceNumber>. 7. In the same dialog window, leave Enabled selected to establish the channel immediately after choosing Finish. Unselect it if you don't want to establish the channel immediately. 488 PUBLIC SAP BTP Connectivity Connectivity
- 489. 8. Choose Finish. Note When addressing an ABAP Cloud system in a destination configuration, you must enter the Cloud Connector host as application server host. As instance number, specify the <Local Instance Number> that you configured for the service channel. As user, you must provide the business user name but not the technical user name associated with the same. 1.2.2.7.4 Service Channels: Port Overview A service channel overview lets you see the details of all service channels that are used by a Cloud Connector installation. The service channel port overview lists all service channels that are configured in the Cloud Connector. It lets you see at a glance, which server ports are used by a Cloud Connector installation. In addition, you can find the following information about each service channel: ● Status (enabled, disabled, disconnected) ● Service channel type (SAP HANA Database, Virtual Machine, S/4HANA Cloud) ● Assigned subaccount ● Details (for example, the assigned SAP HANA instance name or virtual machine name) From the Actions column, you can switch directly to the On-Premise To Cloud section of the corresponding subaccount and edit the selected service channel. To find the overview list, choose Connector from the navigation menu and go to section Service Channels Overview: SAP BTP Connectivity Connectivity PUBLIC 489
- 490. 1.2.2.8 Configure Trust Set up an allowlist for cloud applications and a trust store for on-premise systems in the Cloud Connector. Tasks Trust Cloud Applications in the Cloud Connector [page 490] Configure the Trust Store [page 492] Trust Cloud Applications in the Cloud Connector Restriction Currently, the complete implementation of this feature is available only for interaction with the Neo environment. By default, all applications within a subaccount are allowed to use the Cloud Connector associated with the subaccount they run in. However, this behavior might not be desired in any scenario. For example, this may be acceptable for some applications, as they must interact with on-premise resources, while other applications, for which it is not transparent whether they try to receive on-premise data, might turn out to be malicious. For such cases, you can use an application allowlist. 490 PUBLIC SAP BTP Connectivity Connectivity
- 491. As long as there is no entry in this list, all applications are allowed to use the Cloud Connector. If one or more entries appear in the allowlist, then only these applications are allowed to connect to the exposed systems in the Cloud Connector. You can add, edit, or delete entries as follows: 1. From your subaccount menu, choose Cloud to On-Premise and go to the Applications tab. 2. To add an application, choose the Add icon in section Trusted Applications. 3. Enter the <Application Name> in the Add Tunnel Application dialog. Note To add all applications that are listed in section Tunnel Connection Limits on the same screen, you can also use the Upload button next to the Add button. The list Tunnel Connection Limits shows all applications for which a specific maximal number of tunnel connections was specified. See also: Configure Tunnel Connections [page 496]. 4. (Optional) Enter the maximal number of <Tunnel Connections> only if you want to override the default value. 5. Choose Save. Note The application name is visible in the SAP BTP cockpit under Applications Java Applications . To allow a subscribed application, you must add it to the allowlist in the format <providerSubaccount>:<applicationName>. In particular, when using HTML5 applications, an implicit subscription to services:dispatcher is required. To edit an existing entry: 1. Choose the Edit button. 2. When you are done, select Save. To remove an application from the list: 1. Select the entry. 2. Choose Delete. To delete all entries, choose Delete All. SAP BTP Connectivity Connectivity PUBLIC 491
- 492. To add all applications from section Tunnel Connection Limits to the allowlist, choose the button Add all applications... from section Trusted Applications. Back to Tasks [page 490] Configure the Trust Store By default, the Cloud Connector trusts every on-premise system when connecting to it via TLS. As this may be an undesirable behavior from a security perspective, you can configure a trust store that acts as an allowlist of trusted certificate authorities. Any TLS server certificate issued by one of those CAs will be considered trusted. If the CA that has issued a concrete server certificate is not included in the trust store, the server is considered untrusted and the connection will fail. You can configure the trust store as follows: 1. From the main menu, choose Configuration . 2. Select the On Premise tab, section Trust Store. An empty trust store does not impose any restrictions on the trusted on-premise systems. It becomes an allowlist as soon as you add the first public key. Note You must provide the CA's X.509 certificates in .der or .cer format. 492 PUBLIC SAP BTP Connectivity Connectivity
- 493. Back to Tasks [page 490] 1.2.2.9 Configure Domain Mappings for Cookies Context Some HTTP servers return cookies that contain a domain attribute. For subsequent requests, HTTP clients should send these cookies to machines that have host names in the specified domain. For example, if the client receives a cookie like the following: Set-Cookie: cookie-field=some-value; domain=mycompany.corp; path=...; ... It returns the cookie in follow-up requests to all hosts like ecc60.mycompany.corp, crm40.mycompany.corp, and so on, if the other attributes like path and attribute require it. However, in a Cloud Connector setup between a client and a Web server, this may lead to problems. For example, assume that you have defined a virtual host sales-system.cloud and mapped it to the internal host name ecc60.mycompany.corp. The client "thinks" it is sending an HTTP request to the host name sales- system.cloud, while the Web server, unaware of the above host name mapping, sets a cookie for the domain mycompany.corp. The client does not know this domain name and thus, for the next request to that Web server, doesn't attach the cookie, which it should do. The procedure below prevents this problem. Procedure 1. From your subaccount menu, choose Cloud To On-Premise, and go to the Cookie Domains tab. 2. Choose Add. 3. Enter cloud as the virtual domain, and your company name as the internal domain. 4. Choose Save. SAP BTP Connectivity Connectivity PUBLIC 493
- 494. The Cloud Connector checks the Web server's response for Set-Cookie headers. If it finds one with an attribute domain=intranet.corp, it replaces it with domain=sales.cloud before returning the HTTP response to the client. Then, the client recognizes the domain name, and for the next request against www1.sales.cloud it attaches the cookie, which then successfully arrives at the server on machine1.intranet.corp. Note Some Web servers use a syntax such as domain=.intranet.corp (RFC 2109), even though the newer RFC 6265 recommends using the notation without a dot. Note The value of the domain attribute may be a simple host name, in which case no extra domain mapping is necessary on the Cloud Connector. If the server sets a cookie with domain=machine1.intranet.corp, the Cloud Connector automatically reverses the mapping machine1.intranet.corp to www1.sales.cloud and replaces the cookie domain accordingly. Related Information Configure Access Control [page 369] 1.2.2.10 Configure Solution Management Integration Activate Solution Management reporting in the Cloud Connector. If you want to monitor the Cloud Connector with the SAP Solution Manager, you can install a host agent on the machine of the Cloud Connector and register the Cloud Connector on your system. Prerequisites ● You have installed the SAP Diagnostics Agent and SAP Host Agent on the Cloud Connector host and connected them to the SAP Solution Manager. As of Cloud Connector version 2.11.2, the RPM on Linux ensures that the host agent configuration is adjusted and that user groups are setup correctly. For more details about the host agent and diagnostics agent, see SAP Host Agent and the SCN Wiki SAP Solution Manager Setup/Managed System Checklist . See also SAP notes 2607632 (SAP Solution Manager 7.2 - Managed System Configuration for SAP Cloud Connector) and 1018839 (Registering in the System Landscape Directory using sldreg). For consulting, contact your local SAP partner. 494 PUBLIC SAP BTP Connectivity Connectivity
- 495. Note Linux OS: if you installed the host agent after installing the Cloud Connector, you can execute enableSolMan.sh in the installation directory (available as of Cloud Connector version 2.11.2) to adjust the host agent configuration and user group setup. This action requires root permission. ● The SAP Solution Manager must be of release 7.2 SP06 or higher. Procedure To enable the integration, do the following: 1. From the Cloud Connector main menu, choose Configuration Reporting . In section Solution Management of the Reporting tab, select Edit. 2. Select the Active checkbox. 3. In the field <Host Agent>, specify the location of the host agent as filepath. 4. If you want to store the reporting results (Dynamic Statistical Records), select Write DSR To File. 5. Choose Save. Note To download the registration file lmdbModel.xml, choose the icon Download registration file from the Reporting tab. Related Information Monitoring [page 516] SAP BTP Connectivity Connectivity PUBLIC 495
- 496. 1.2.2.11 Configure Tunnel Connections Adapt connectivity settings that control the throughput by choosing the appropriate limits (maximal values). If required, you can adjust the following parameters for the communication tunnel by changing their default values: ● Application Tunnel Connections (default: 1) Note This parameter specifies the default value for the maximal number of tunnel connections per application. The value must be higher than 0. ● Tunnel Worker Threads (default: 10) ● Protocol Processor Worker Threads (default: 20) For detailed information on connection configuration requirements, see Configuration Setup [page 290]. To change the parameter values, do the following: 1. From the Cloud Connector main menu, choose Configuration Advanced . In section Connectivity, select Edit. 2. In the Edit Connectivity Settings dialog, change the parameter values as required. 3. Choose Save. Additionally, you can specify the number of allowed tunnel connections for each application that you have specified as a trusted application [page 343]. Note If you don't change the value for a trusted application, it keeps the default setting specified above. If you change the value, it may be higher or lower than the default and must be higher than 0. To add a specific connection limit to a trusted application, do the following: 1. From your subaccount menu, choose Cloud To On-Premise Applications . In section Tunnel Connection Limits, choose Add. 496 PUBLIC SAP BTP Connectivity Connectivity
- 497. 2. In the Edit Tunnel Connections Limit dialog, enter the <Application Name> and change the number of <Tunnel Connections> as required. Note The application name is visible in the SAP BTP cockpit under Applications Java Applications . To allow a subscribed application, you must add it to the allowlist in the format <providerSubaccount>:<applicationName>. In particular, when using HTML5 applications, an implicit subscription to services:dispatcher is required. 3. Choose Save. To edit this setting, select the application from the Limits list and choose Edit. 1.2.2.12 Configure the Java VM Adapt the JVM settings that control memory management. If required, you can adjust the following parameters for the Java VM by changing their default values: ● Initial Heap Size (default: 1024 MB) ● Maximal Heap Size (default: 1024 MB) ● Maximal Direct Memory (default: 2 GB) Note A restart is required when changing JVM settings. We recommended that you set the initial heap size equal to the maximal heap size, to avoid memory fragmentation. To change the parameter values, do the following: 1. From the Cloud Connector main menu, choose Configuration Advanced . In section JVM, select Edit. SAP BTP Connectivity Connectivity PUBLIC 497
- 498. 2. In the Edit JVM Settings dialog, change the parameter values as required. 3. Choose Save. 1.2.2.13 Configuration Backup You can backup and restore your Cloud Connector configuration. To backup or restore your Cloud Connector configuration, do the following: 1. From the Cloud Connector main menu, choose Connector. 2. To backup or restore your configuration, choose the respective icon in the upper right corner of the screen. 1. To backup your configuration, enter and repeat a password in the Backup dialog and choose Backup. Note An archive containing a snapshot of the current Cloud Connector configuration is created and downloaded by your browser. You can use this archive to restore the current state on this or a new Cloud Connector installation, if the original installation can no longer be used. Do not restore the backup on a second Cloud Connector, while the instance from which the backup was taken is still active. Such a setup might cause issues and is therefore not supported. For security reasons, some files are encrypted, using the password provided for the backup procedure. 2. To restore your configuration, enter the required Archive Password and the Login Password of the currently logged-in administrator user in the Restore from Archive dialog and choose Restore. Note The restore action overwrites the current configuration of the Cloud Connector. It will be permanently lost unless you have created another backup before restoring. Upon successfully restoring the configuration, the Cloud Connector restarts automatically. All sessions are then 498 PUBLIC SAP BTP Connectivity Connectivity
- 499. terminated. The props.ini file however is treated in a special way. If the file in the backup differs from the one that is used in the current installation, it will be placed next to the original one as props.ini.restored. If you want to use the props.ini.restored file, replace the existing one on OS level and restart the Cloud Connector. 1.2.2.14 Configure Login Screen Information Add additional information to the login screen and configure its appearance. To configure the login screen information, proceed as follows: 1. Go to Configuration User Interface and press the Edit button in section Login Screen Information. As a result, the following dialog is opened: SAP BTP Connectivity Connectivity PUBLIC 499
- 500. 2. In section Display Policy, select a display policy for the login screen information. 3. In section Display Properties, specify your preferred display properties (appearance and position): ○ The login information is displayed in a box with rounded corners. You can specify its width and height in pixels (unit px) or as a percentage (unit %). Note Omitting any value triggers the default or auto behavior. ○ For the width, the default behavior is equivalent to 100%. ○ For the height, the default behavior sets the height to a value that accommodates the login information (that is, the given HTML fragment). For extensive information we therefore recommend that you limit the height to a suitable pixel or percentage value to induce scrolling, and to prevent the box from growing beyond a reasonable height. 500 PUBLIC SAP BTP Connectivity Connectivity
- 501. ○ When customizing the background color of the box, the opacity (of the background color), font color, or text alignment, then the section Login Information automatically switches to preview mode. That way you can follow live the changes made to the appearance of the box and of the information displayed inside it. Note You can hide the box and to show only the text of the login information by choosing an opacity value of 0 (opacity is the opposite of transparency. No opacity means complete transparency). ○ You can position the box containing the login information at the top or bottom of the login page. To do this, set the field <Position> to the corresponding pixel or percentage value. 4. Enter the information to be displayed in section Login Information. The information must be supplied as an HTML fragment. There is a limited number of tags that can be used. Attributes available for these tags are subject to restrictions. Available Tag Attribute Restriction p Only attribute style is permitted, with property text- align set to a valid value (left, right, center, or justified) ul No attributes allowed ol No attributes allowed li No attributes allowed br No attributes allowed h1 No attributes allowed h2 No attributes allowed h3 No attributes allowed i No attributes allowed b No attributes allowed a Must have exactly two attributes: ○ href (its value must be a <URL> with protocol http or https) ○ target (its value must be "_blank") HTML syntax checking is strict. Attribute values must be enclosed by double quotes. Missing or unmatched opening or closing tags are not permitted. Note Tag br does not require a closing tag as there cannot be any inner HTML. SAP BTP Connectivity Connectivity PUBLIC 501
- 502. 1.2.3 Operations Learn more about operating the Cloud Connector, using its administration tools and optimizing its functions. Topic Description Configure Named Cloud Connector Users [page 502] If you operate an LDAP server in your system landscape, you can configure the Cloud Connector to use the named users who are available on the LDAP server instead of the default Cloud Connector users. High Availability Setup [page 507] The Cloud Connector lets you install a redundant (shadow) instance, which monitors the main (master) instance. Change the UI Port [page 513] Use the changeport tool (Cloud Connector version 2.6.0+) to change the port for the Cloud Connector administration UI. . Connect and Disconnect a Cloud Subaccount [page 514] As a Cloud Connector administrator, you can connect the Cloud Connector to (and disconnect it from) the configured cloud subaccount. Secure the Activation of Traffic Traces [page 515] Tracing of network traffic data may contain business critical information or security sensitive data. You can implement a "four-eyes" (double check) principle to protect your traces (Cloud Connector version 1.3.2+). Monitoring [page 516] Use various views to monitor the activities and state of the Cloud Connector. Alerting [page 542] Configure the Cloud Connector to send email alerts when ever critical situations occur that may prevent it from oper ating. Audit Logging [page 545] Use the auditor tool to view and manage audit log informa tion (Cloud Connector version 2.2+). Troubleshooting [page 548] Information about monitoring the state of open tunnel con nections in the Cloud Connector. Display different types of logs and traces that can help you troubleshoot connection problems. Process Guidelines for Hybrid Scenarios [page 553] How to manage a hybrid scenario, in which applications run ning on SAP BTP require access to on-premise systems us ing the Cloud Connector. 1.2.3.1 Configure Named Cloud Connector Users Set up LDAP-based user management for the Cloud Connector. 502 PUBLIC SAP BTP Connectivity Connectivity
- 503. LDAP-Based User Management We recommend that you configure LDAP-based user management for the Cloud Connector to allow only named administrator users to log on to the administration UI. This guarantees traceability of the Cloud Connector configuration changes via the Cloud Connector audit log. If you use the default and built-in Administrator user, you cannot identify the actual person or persons who perform configuration changes. Also, you will not be able to use different types of user groups. Configuration If you have an LDAP server in your landscape, you can configure the Cloud Connector to authenticate Cloud Connector users against the LDAP server. Valid users or user groups must be assigned to one of the following roles: ● Administrator users: admin or sccadmin ● Display users: sccdisplay or sccmonitoring Note The role sccmonitoring provides access to the monitoring APIs, and is particularly used by the SAP Solution Manager infrastructure, see Monitoring APIs [page 524]. It cannot be used to access the Cloud Connector administation UI. ● Support users: sccsupport Alternatively, you can define custom role names for each of these user groups, see: Use LDAP for Authentication [page 503]. Once configured, the default Cloud Connector Administrator user becomes inactive and can no longer be used to log on to the Cloud Connector. 1.2.3.1.1 Use LDAP for Authentication You can use LDAP (Lightweight Directory Access Protocol) to configure Cloud Connector authentication. After installation, the Cloud Connector uses file-based user management by default. Alternatively, the Cloud Connector also supports LDAP-based user management. If you operate an LDAP server in your landscape, you can configure the Cloud Connector to use the LDAP user base. If LDAP authentication is active, you can assign users or user groups to the following default roles: Default Role Authorization sccadmin or admin Administrate the Cloud Connector (all CRUD operations). SAP BTP Connectivity Connectivity PUBLIC 503
- 504. Default Role Authorization sccdisplay Access the Cloud Connector administration UI in read-only mode. sccsupport ● Access the Cloud Connector administration UI in read- only mode. ● Perform support-related tasks like setting trace levels or creating a thread dump. sccmonitoring Provides access to the monitoring APIs, and is particularly used by the SAP Solution Manager infrastructure, see Moni toring APIs [page 524]. Note This role cannot be used to access the Cloud Connector administation UI. Group membership is checked by the Cloud Connector. Setting LDAP Authentication 1. From the main menu, choose Configuration and go to the User Interface tab. 2. From the Authentication section, choose Switch to LDAP. 3. (Optional) To save intermediate adoptions of the LDAP configuration, choose Save Draft. This lets you store the changes in the Cloud Connector without activation. 504 PUBLIC SAP BTP Connectivity Connectivity
- 505. 4. Usually, the LDAP server lists users in an LDAP node and user groups in another node. In this case, you can use the following template for LDAP configuration. Copy the template into the configuration text area: roleBase="ou=groups,dc=scc" roleName="cn" roleSearch="(uniqueMember={0})" userBase="ou=users,dc=scc" userSearch="(uid={0})" Change the <ou> and <dc> fields in userBase and roleBase, according to the configuration on your LDAP server, or use some other LDAP query. Note The configuration depends on your specific LDAP server. For details, contact your LDAP administrator. 5. Provide the LDAP server's host and port (port 389 is used by default) in the <Host> field. To use the secure protocol variant LDAPS based on TLS, select Secure. 6. Provide a failover LDAP server's host and port (port 389 is used by default) in the <Alternate Host> field. To use the secure protocol variant LDAPS based on TLS, select <Secure Alternate Host>. 7. (Optional) Depending on your LDAP server configuration you may need to specify the <Connection User Name> and its <Connection Password>. LDAP Servers supporting anonymous binding ignore these parameters. 8. (Optional) To use your own role names, you can customize the default role names in the Custom Roles section. If no custom role is provided, the Cloud Connector checks permissions for the corresponding default role name: ○ <Administrator Role> (default: sccadmin) ○ <Support Role> (default: sccsupport) ○ <Display Role> (default: sccdisplay) ○ <Monitoring Role> (default: sccmonitoring) 9. (Optional) Before activating the LDAP authentication, you can execute an authentication test by choosing the Test LDAP Configuration button. In the pop-up dialog, you must specify user name and password of a user who is allowed to logon after activating the configuration. The check verifies if authentication would be successful or not. Note We strongly recommend that you perform an authentication test. If authentication should fail, login is not possible anymore. The test dialog also provides a test protocol, which could be helpful for troubleshooting. For more information about how to set up LDAP authentication, see tomcat.apache.org/tomcat-8.5-doc/ realm-howto.html . Note To find a list of all supported attributes, see https:/ /tomcat.apache.org/tomcat-7.0-doc/config/ realm.html#JNDI_Directory_Realm_-_org.apache.catalina.realm.JNDIRealm . You can also configure LDAP authentication on the shadow instance in a high availability setup (master and shadow). From the main menu of the shadow instance, select Shadow Configuration, go to tab User Interface, and check the Authentication section. SAP BTP Connectivity Connectivity PUBLIC 505
- 506. Note If you are using LDAP together with a high availability setup, you cannot use the configuration option userPattern. Instead, use a combination of userSearch, userSubtree and userBase. Caution An LDAP connection over SSL/TLS can cause SSL errors if the LDAP server uses a certificate that is not signed by a trusted CA. If you cannot use a certificate signed by a trusted CA, you must set up the trust relationship manually, that is, import the public part of the issuer certificate to the JDK's trust storage. Usually, the cacerts file inside the java directory (jre/lib/security/cacerts) is used for trust storage. To import the certificate, you can use keytool: keytool -import -storepass changeit -file <certificate used by LDAP server> -keystore cacerts -alias <e.g. LDAP_xyz> For more information, see also https:/ /docs.oracle.com/cd/E19830-01/819-4712/ablqw/index.html . 10. After finishing the configuration, choose Activate. Immediately after activating the LDAP configuration you must restart the Cloud Connector server, which invalidates the current browser session. Refresh the browser and logon to the Cloud Connector again, using the credentials configured at the LDAP server. 11. To switch back to file-based user management, choose the Switch icon again. Note If you have set up an LDAP configuration incorrectly, you may not be able to logon to the Cloud Connector again. In this case, adjust the Cloud Connector configuration to use the file-based user store again without the administration UI. For more information, see the next section. Switching Back to File-Based User Store without the Administration UI If your LDAP settings do not work as expected, you can use the useFileUserStore tool, provided with Cloud Connector version 2.8.0 and higher, to revert back to the file-based user store: 1. Change to the installation directory of the Cloud Connector and enter the following command: ○ Microsoft Windows: useFileUserStore ○ Linux, Mac OS: ./useFileUserStore.sh 2. Restart the Cloud Connector to activate the file-based user store. For versions older than 2.8.0, you must manually edit the configuration files. Depending on your operating system, the configuration file is located at: ● Microsoft Windows OS: <install_dir>config_masterorg.eclipse.gemini.web.tomcat default-server.xml ● Linux OS: /opt/sap/scc/config_master/org.eclipse.gemini.web.tomcat/default- server.xml 506 PUBLIC SAP BTP Connectivity Connectivity
- 507. ● Mac OS X: /opt/sap/scc/config_master/org.eclipse.gemini.web.tomcat/default- server.xml 1. Replace the Realm section with the following: <Realm className="org.apache.catalina.realm.LockOutRealm"> <Realm className="org.apache.catalina.realm.CombinedRealm"> <Realm X509UsernameRetrieverClassName="com.sap.scc.tomcat.utils.SccX509SubjectDnRetri ever" className="org.apache.catalina.realm.UserDatabaseRealm" digest="SHA-256" resourceName="UserDatabase"/> <Realm X509UsernameRetrieverClassName="com.sap.scc.tomcat.utils.SccX509SubjectDnRetri ever" className="org.apache.catalina.realm.UserDatabaseRealm" digest="SHA-1" resourceName="UserDatabase"/> </Realm> </Realm> 2. Restart the Cloud Connector service: ○ Microsoft Windows OS: Open the Windows Services console and restart the cloud connector service. ○ Linux OS: Execute ○ System V init distributions: service scc_daemon restart ○ Systemd distributions: systemctl restart scc_daemon ○ Mac OS X: Not applicable because no daemon exists (for Mac OS X, only a portable variant is available). 1.2.3.2 High Availability Setup You can operate the Cloud Connector in a high availability mode, in which a master and a shadow instance are installed. Task Description Install a Failover Instance for High Availability [page 508] Install a redundant Cloud Connector instance (shadow) that monitors the main instance (master). Master and Shadow Administration [page 511] Learn how to operate master and shadow instances. Related Information Connect DB Tools to SAP HANA via Service Channels [page 486] SAP BTP Connectivity Connectivity PUBLIC 507
- 508. 1.2.3.2.1 Install a Failover Instance for High Availability The Cloud Connector lets you install a redundant instance that monitors the main instance. Context In a failover setup, when the main instance should go down for some reason, a redundant one can take over its role. The main instance of the Cloud Connector is called master and the redundant instance is called the shadow. The shadow has to be installed and connected to its master. During the setup of high availability, the master pushes the entire configuration to the shadow. Later on, during normal operation, the master also pushes configuration updates to the shadow. Thus, the shadow instance is kept synchronized with the master instance. The shadow pings the master regularly. If the master is not reachable for a while, the shadow tries to take over the master role and to establish the tunnel to SAP BTP. Note For detailed information about sizing of the master and the shadow instance, see also Sizing Recommendations [page 286]. Procedure Preparing the Master Instance for High Availability 1. Open the Cloud Connector UI and go to the master instance. 2. From the main menu, choose High Availability. 3. Choose Enable. If this flag is not activated, no shadow instance can connect to this Cloud Connector. Additionally, when providing a concrete Shadow Host, you can ensure that only from this host a shadow instance can be connected. 508 PUBLIC SAP BTP Connectivity Connectivity
- 509. Caution Pressing the Reset button resets all high availability settings to their initial state. As a result, high availability is disabled and the shadow host is cleared. Reset only works if no shadow is connected. Installing and Setting Up a Shadow Instance Install the shadow instance in the same network segment as the master instance. Communication between master and shadow via proxy is not supported. The same distribution package is used for master and shadow instance. Note If you plan to use LDAP for the user authentication on both master and shadow, make sure you configure it before you establish the connection from shadow to master. 1. On first start-up of a Cloud Connector instance, a UI wizard asks you whether the current instance should be master or shadow. Choose Shadow and Save: 2. From the main menu, choose Shadow Connector and provide connection data for the master instance, that is, the master host and port. As of version 2.8.1.1, you can choose from the list of known host names, to use the host name under which the shadow host is visible to the master. You can specify a host name manually, if the one you want is not on the list. For the first connection, you must log on to the master instance, using the user name and password for the master instance. The master and shadow instances exchange X.509 certificates, which will be used for mutual authentication. SAP BTP Connectivity Connectivity PUBLIC 509
- 510. Note If you want to attach the shadow instance to a different master, press the Reset button. All your high availability settings will be removed, that is, reset to their initial state. This works only if the shadow is not connected. 3. Upon a successful connection, the master instance pushes the entire configuration plus some information about itself to the shadow instance. You can see this information in the UI of the shadow instance, but you can't modify it. 4. The UI on the master instance shows information about the connected shadow instance. From the main menu, choose High Availability: 5. As of version 2.6.0, the High Availability view includes an Alert Messages panel. It displays alerts if configuration changes have not been pushed successfully. This might happen, for example, if a temporary network failure occurs at the same time a configuration change is made. This panel lets an administrator know if there is an inconsistency in the configuration data between master and shadow that could cause trouble if the shadow needs to take over. Typically, the master recognizes this situation and tries to push the configuration change at a later time automatically. If this is successful, all failure alerts are removed and replaced by a warning alert showing that there had been trouble before. As of version 2.8.0.1, these alerts have been integrated in the general Alerting section; there is no longer a separate Alert Messages panel. If the master doesn't recover automatically, disconnect, then reconnect the shadow, which triggers a complete configuration transfer. 510 PUBLIC SAP BTP Connectivity Connectivity
- 511. Related Information Initial Configuration [page 312] Master and Shadow Administration [page 511] 1.2.3.2.2 Master and Shadow Administration Administration of Shadow Instances There are several administration activities you can perform on the shadow instance. All configuration of tunnel connections, host mappings, access rules, and so on, must be maintained on the master instance; however, you can replicate them to the shadow instance for display purposes. You may want to modify the check interval (time between checks of whether the master is still alive) and the takeover delay (time the shadow waits to see whether the master would come back online, before taking over the master role itself). As of Cloud Connector version 2.11.2, you can configure the timeout for the connection check, by pressing the gear icon in the section Connection To Master of the shadow connector main page. SAP BTP Connectivity Connectivity PUBLIC 511
- 512. The <Connection Timeout> field specifies the maximum time allowed for establishing the technical connection to the master, the <Request Timeout> defines the maximum time allowed for executing the check over this connection. In the Timeout Validation section, you can check the current settings by pressing the Execute button. If the timeouts are hit, you might want to increase the settings accordingly. Keep in mind the following points: ● The log level on master and shadow instances can be different. ● Configuration for check interval and takeover delay is maintained only on the shadow instance, and is transferred to the master for display purposes. ● Audit logs are only written on the master instance and are not transferred to the shadow. However, if the shadow becomes the master for some time, the audit log is potentially distributed over both master and shadow instances. You can use the Reset button to drop all the configuration information on the shadow that is related to the master, but only if the shadow is not connected to the master. Required Configuration on the Shadow Instance Once connected to the master, the shadow instance receives the configuration from the master instance. Yet, there are some aspects you must configure on the shadow instance separately: ● User administration is configured separately on master and shadow instances. Generally, it is not required to have the same configuration on both instances. In most cases, however, it is suitable to configure master and shadow in the same way. ● The UI certificate is not shared. Each host can have its own certificate, so you must maintain the UI certificates on master and shadow. You can use the same certificate though. ● SNC configuration: If secure RFC communication or principal propagation for RFC calls is used, you must configure SNC on each instance separately. Failover Process The shadow instance regularly checks whether the master instance is still alive. If a check fails, the shadow instance first attempts to reestablish the connection to the master instance for the time period specified by the takeover delay parameter. ● If no connection becomes possible during the takeover delay time period, the shadow tries to take over the master role. At this point, it is still possible for the master to be alive and the trouble to be caused by a network issue between the shadow and master. The shadow instance next attempts to establish a tunnel to the given SAP BTP subaccount. If the original master is still alive (that is, its tunnel to the cloud subaccount is still active), this attempt is denied and the shadow instance remains in "shadow status", periodically pinging the master and trying to connect to the cloud, while the master is not yet reachable. ● If the takeover delay period has fully elapsed, and the shadow instance does make a connection, the cloud side opens a tunnel and the shadow instance takes over the role of the master. From this point, the shadow 512 PUBLIC SAP BTP Connectivity Connectivity
- 513. instance shows the UI of the master instance and allows the usual operations of a master instance, for example, starting/stopping tunnels, modifying the configuration, and so on. When the original master instance restarts, it first checks whether the registered shadow instance has taken over the master role. If it has, the master registers itself as a shadow instance on the former shadow (now master) instance. Thus, the two Cloud Connector installations, in fact, have switched their roles. Note Only one shadow instance is supported. Any further shadow instances that attempt to connect are declined by the master instance. The master considers a shadow as lost, if no check/ping is received from that shadow instance during a time interval that is equal to three times the check period. Only after this much time has elapsed can another shadow system register itself. Note On the master, you can manually trigger failover by selecting the Switch Roles button. If the shadow is available, the switch is made as expected. Even if the shadow instance cannot be reached, the role switch of the master may still be enforced. Select Switch Roles only if you are absolutely certain it is the correct action to take for your current circumstances. 1.2.3.3 Change the UI Port Context By default, the Cloud Connector uses port 8443 for its administration UI. If this port is blocked by another process, or if you want to change it after the installation, you can use the changeport tool, provided with Cloud Connector version 2.6.0 and higher. Note On Windows, you can also choose a different port during installation. Procedure 1. Change to the installation directory of the Cloud Connector. To adjust the port and execute one of the following commands: ○ Microsoft Windows OS: changeport <desired_port> SAP BTP Connectivity Connectivity PUBLIC 513
- 514. ○ Linux OS, Mac OS X: ./changeport.sh <desired_port> 2. When you see a message stating that the port has been successfully modified, restart the Cloud Connector to activate the new port. 1.2.3.4 Connect and Disconnect a Cloud Subaccount The major principle for the connectivity established by the Cloud Connector is that the Cloud Connector administrator should have full control over the connection to the cloud, that is, deciding if and when the Cloud Connector should be connected to the cloud, the accounts to which it should be connected, and which on- premise systems and resources should be accessible to applications of the connected subaccount. Using the administration UI, the Cloud Connector administrator can connect and disconnect the Cloud Connector to and from the configured cloud subaccount. Once disconnected, no communication is possible, either between the cloud subaccount and the Cloud Connector, or to the internal systems. The connection state can be verified and changed by the Cloud Connector administrator on the Subaccount Dashboard tab of the UI. Note Once the Cloud Connector is freshly installed and connected to a cloud subaccount, none of the systems in the customer network are yet accessible to the applications of the related cloud subaccount. Accessible systems and resouurces must be configured explicitly in the Cloud Connector one by one, see Configure Access Control [page 369]. A Cloud Connector instance can be connected to multiple subaccounts in the cloud. This is useful especially if you need multiple subaccounts to structure your development or to stage your cloud landscape into development, test, and production. In this case, you can use a single Cloud Connector instance for multiple subaccounts. However, we recommend that you do not use subaccounts running in productive scenarios and subaccounts used for development or test purposes within the same Cloud Connector. You can add or a delete a cloud account to or from a Cloud Connector using the Add and Delete buttons on the Subaccount Dashboard (see screenshot above). 514 PUBLIC SAP BTP Connectivity Connectivity
- 515. Related Information Managing Subaccounts [page 328] 1.2.3.5 Secure the Activation of Traffic Traces For support purposes, you can trace HTTP and RFC network traffic that passes through the Cloud Connector. Context Traffic data may include business-critical information or security-sensitive data, such as user names, passwords, address data, credit card numbers, and so on. Thus, by activating the corresponding trace level, a Cloud Connector administrator might see data that he or she is not meant to. To prevent this behavior, implement the four-eyes principle, which is supported by the Cloud Connector release 1.3.2 and higher. Once the four-eyes principle is applied, activating a trace level that dumps traffic data will require two separate users: ● An operating system user on the machine where the Cloud Connector is installed; ● An Administrator user of the Cloud Connector user interface. By assigning these roles to two different people, you can ensure that both persons are needed to activate a traffic dump. Four-Eyes Principle for Microsoft Windows OS 1. Create a file named writeHexDump in <scc_install_dir>scc_config. The owner of this file must be a user other than the operating system user who runs the cloud connector process. Note Usually, this file owner is the user which is specified in the Log On tab in the properties of the cloud connector service (in the Windows Services console). We recommend that you use a dedicated OS user for the cloud connector service. ○ Only the file owner should have write permission for the file. ○ The OS user who runs the cloud connector process needs read-only permissions for this file. ○ Initially, the file should contain a line like allowed=false. ○ In the security properties of the file scc_config.ini (same directory), make sure that only the OS user who runs the cloud connector process has write/modify permissions for this file. The most efficient way to do this is simply by removing all other users from the list. 2. Once you've created this file, the Cloud Connector refuses any attempt to activate the Payload Trace flag. SAP BTP Connectivity Connectivity PUBLIC 515
- 516. 3. To activate the payload trace, first the owner of writeHexDump must change the file content from allowed=false to allowed=true. Thereafter, the Administrator user can activate the payload trace from the Cloud Connector administration screens. Four-Eyes Principle for Linux OS/Mac OS X 1. Create a file named writeHexDump in /usr/local/vl/base/cfg (Cloud Connector 1.3.2) or /opt/sap/scc/scc_config (Cloud Connector 2.x). The owner of this file must be a user other than the scctunnel user (that is, the operating system user under which the cloud connector processes run) and not a member of the operating system user group sccgroup. ○ Only the file owner should have write permission for the file. ○ The scctunnel user needs read-only permissions for this file. ○ Initially, the file should contain a line like allowed=false. 2. Once you've created this file, the Cloud Connector refuses any attempt to set the trace level higher than Runtime (Cloud Connector 1.3.2) or to activate the Payload Trace flag (Cloud Connector 2.x). 3. To set a higher trace level, which includes traffic Hex-dumps (Cloud Connector 1.3.2), or to activate the payload trace (Cloud Connector 2.x), the file owner mentioned above must first change the file content from allowed=false to allowed=true. Thereafter, the Administrator user can activate one of the higher trace levels (Cloud Connector 1.3.2) or the payload trace (Cloud Connector 2.x) from the Cloud Connector administration screens. 1.2.3.6 Monitoring Learn how to monitor the Cloud Connector from the SAP BTP cockpit and from the Cloud Connector administration UI. Checking the Operational State The simplest way to verify whether a Cloud Connector is running is to try to access its administration UI. If you can open the UI in a Web browser, the cloud connector process is running. ● On Microsoft Windows operating systems, the cloud connector process is registered as a Windows service, which is configured to start automatically after a new Cloud Connector installation. If the Cloud Connector server is rebooted, the cloud connector process should also auto-restart immediately. You can check the state with the following command: sc query "SAP Cloud Connector" The line state shows the state of the service. 516 PUBLIC SAP BTP Connectivity Connectivity
- 517. ● On Linux operating systems, the Cloud Connector is registered as a daemon process and restarts automatically each time the cloud connector process is down, for example, following a system restart. You can check the daemon state with the following command: service scc_daemon status To verify if a Cloud Connector is connected to a certain cloud subaccount, log on to the Cloud Connector administration UI and go to the Subaccount Dashboard, where the connection state of the connected subaccounts is visible, as described in section Connect and Disconnect a Cloud Subaccount [page 514]. Monitoring from the Cockpit The cockpit includes a Connectivity section, where users can check the status of the Cloud Connector(s) attached in the current subaccount, if any, as well as information about the Cloud Connector ID, version, used Java runtime, high availability setup (master and shadow instance), and so on (choose Connectivity Cloud Connectors ). Access to this view is, by default, granted to administrators, developers, and support users. Monitoring from the Cloud Connector Aministration UI The Cloud Connector offers various views for monitoring its activities and state. You can check the overall state of the Cloud Connector through its Hardware Metrics [page 518], whereas subaccount-specific performance and usage data is available via Subaccount-Specific Monitoring [page 519]. To provide external monitoring tools, you can use the Monitoring APIs [page 524]. Related Information Configure Solution Management Integration [page 494] SAP BTP Connectivity Connectivity PUBLIC 517
- 518. High Availability Setup [page 507] 1.2.3.6.1 Hardware Metrics Check the current state of critical system resources in the Cloud Connector. You can check the current state of critical system resources (disc space, Java heap, physical memory, virtual memory) using pie charts. To access the monitor, choose Hardware Metrics Monitor from the main menu. In addition, the history of CPU and memory usage (physical memory, Java heap) is shown in history graphs below the pie charts (recorded in intervals of 15 seconds). You can view the usage data for a selected time period in each history graph: ● Double-click inside the main graph area to set the start (or end) point, and drag to the left or to the right to zoom in. ○ The entire timeline is always visible in the smaller bottom area right below the main graph. ○ A frame in the bottom area shows the position of the selected section in the overall timeline. ● Choose Undo zooming in... to reset the main graph area to the full range of available data. 518 PUBLIC SAP BTP Connectivity Connectivity
- 519. 1.2.3.6.2 Subaccount-Specific Monitoring Use different monitoring views in the Cloud Connector administration UI to check subaccount-specific activites and data. Content Performance Overview [page 519] Most Recent Requests [page 520] Resource Filter Settings [page 521] Top Time Consumers [page 522] Usage Statistics [page 522] Backend Connections [page 523] Performance Overview All requests that travel through the Cloud Connector to a backend system, as specified through access control, take a certain amount of time. You can check the duration of requests in a bar chart. The requests are not shown individually, but are assigned to buckets, each of which represents a time range. SAP BTP Connectivity Connectivity PUBLIC 519
- 520. For example, the first bucket contains all requests that took 10ms or less, the second one the requests that took longer than 10ms, but not longer than 20ms. The last bucket contains all requests that took longer than 5000ms. In case of latency gaps, you may try to adjust the influencing parameters: number of connections, tunnel worker threads, and protocol processor worker threads. For more information, see Configuration Setup [page 290]. The collection of duration statistics starts as soon as the Cloud Connector is operational. You can delete all of these statistical records by selecting the button Delete All. After that, the collection of duration statistics starts over. Note Delete All deletes not only the list of most recent requests, but it also clears the top time consumers. Back to Content [page 519] Most Recent Requests This option shows the most recent requests: The number of requests that are shown is limited to 50. You can either view all requests or only the ones destined for a certain virtual host, which you can select.You can select a row to see more detail. 520 PUBLIC SAP BTP Connectivity Connectivity
- 521. A horizontal stacked bar chart breaks down the duration of the request into several parts: external (backend), open connection, internal (SCC), SSO handling, and latency effects. The numbers in each part represent milliseconds. Note Parts with a duration of less than 1ms are not included. In the above example, the selected request took 34ms, to which the Cloud Connector contributed 1ms. Opening a connection took 18ms. Backend processing consumed 7ms. Latency effects accounted for the remaining 8ms, while there was no SSO handling necessary and hence it took no time at all. Back to Content [page 519] Resource Filter Settings To further restrict the selection of the listed 50 most recent requests, you can edit the resource filter settings for each virtual host: In the Edit dialog, select the virtual host for which you want to specify the resource filter and choose one or more of the listed accessible resources. This list includes all resources that have been exposed during access SAP BTP Connectivity Connectivity PUBLIC 521
- 522. control configuration (see also: Configure Access Control [page 369]). If the access policy for an accessible resource is set to Path and all sub-paths, you can further narrow the selection by adding one or more sub-paths to the resource as a suffix . Each selected resource/sub-path is listed separately in the resource filter list. Note If you specify sub-paths for a resource, the request URL must match exactly one of these entries to be recorded. Without specified sub-paths (and the value Path and all sub-paths set for a resource), all sub-paths of a specified resource are recorded. Back to Content [page 519] Top Time Consumers This option is similar to Most Recent Requests; however, requests are not shown in order of appearance, but rather sorted by their duration (in descending order). Furthermore, you can delete top time consumers, which has no effect on most recent requests or the performance overview. Back to Content [page 519] Usage Statistics To view the statistical data regarding the traffic handled by each virtual host, you can select a virtual host from the table. The detail view shows the traffic handled by each resource, as well as a 24 hour overview of the throughput as a bar chart that aggregates the throughput (bytes received and bytes sent by a virtual host, respectively) on an hourly basis. Note Currently, this feature is only available for the protocols HTTP(S) and RFC (SNC). Virtual hosts using other protocols are not listed. 522 PUBLIC SAP BTP Connectivity Connectivity
- 523. The data that is collected includes the number of bytes received from cloud applications and the number of bytes sent back to cloud applications. The time of the most recent access is shown for the virtual hosts, and in the detail view also for the resources. If no access has taken place yet, the most recent access is shown as n.a. (not available). Similarly, the number of bytes received and sent of a virtual host is the sum of bytes received and sent of its resources. The tables listing usage statistics of virtual hosts and their resources let you delete unused virtual hosts or unused resources. Use action Delete to delete such a virtual host or resource. Caution ● Usage statistics are collected during runtime only and are not stored when stopping the Cloud Connector. That is, these statistics are lost when the Cloud Connector is stopped or restarted. ● Use care when taking the decision to delete a resource or virtual host based on its usage statistics. For both virtual hosts and resources, you can use a classic filter button to reduce the virtual hosts or resources to those that have never been used (since the Cloud Connector started). For the virtual hosts, a second filter type is available that selects only those virtual hosts that have been used, but include resources never used. This feature facilitates locating obsolete resources of otherwise active virtual hosts. Back to Content [page 519] Backend Connections This option shows a tabular overview of all active and idle connections, aggregated for each virtual host. By selecting a row (each of which represents a virtual host) you can view the details of all active connections as SAP BTP Connectivity Connectivity PUBLIC 523
- 524. well as a graphical summary of all idle connections. The graphical summary is an accumulative view of connections based on the time the connections have been idle. The maximum idle time appears on the rightmost side of the horizontal axis. For any point t on that axis (representing a time value ranging between 0ms and the maximal idle time), the ordinate is the number of connections that have been idle for no longer than t. You can click inside the graph area to view the respective abscissa t and ordinate. Back to Content [page 519] 1.2.3.6.3 Monitoring APIs Use the Cloud Connector monitoring APIs to include monitoring information in your own monitoring tool. Context You might want to integrate some monitoring information in the monitoring tool you use. For this purpose, the Cloud Connector includes a collection of APIs that allow you to read various types of monitoring data. Note This API set is designed particularly for monitoring the Cloud Connector via the SAP Solution Manager, see Configure Solution Management Integration [page 494]. Prerequisites You must use Basic Authentication or form field authentication to read the monitoring data via API. Users must be assigned to the roles sccmonitoring or sccadmin. The role sccmonitoring is restricted to managing the monitoring APIs. Note The Health Check API does not require a specified user. Separate users are available through LDAP only. 524 PUBLIC SAP BTP Connectivity Connectivity
- 525. URL Parameters The API URLs adhere to the following pattern: https://<scchost>:<sccport>/xxx ● Only HTTPS is supported ● <scchost>:<sccport> = cloud connector address ● xxx= path of the calling method Available APIs The following APIs are currently available. ● Health Check [page 525] (available as of version 2.6.0) ● Subaccount data [page 525] (as of 2.10.0) ● Connection data [page 527] (as of 2.10.0) ● Performance data [page 529] (as of 2.10.0) ● Top Time Consumers [page 531] (as of 2.11.0) ● Memory Status [page 533] (as of 2.13.0) ● Certificate Status [page 535] (as of 2.13.0) ● Usage Statistics [page 537] (as of 2.13.0) Health Check (available as of version 2.6.0) Note This API is relevant for the master instance as well as for the shadow instance. Using the health check API, it is possible to recognize that the Cloud Connector is up and running. The purpose of this health check is only to verify that the Cloud Connector is not down. It does not check any internal state or tunnel connection states. Thus, it is a quick check that you can execute frequently: URL https://<scc_host>:<scc_port>/exposed?action=ping Expected Return Code 200 Back to Available APIs [page 525] Back to Context [page 524] List of Subaccounts (available as of version 2.10.0) Note This API is relevant for the master instance only. SAP BTP Connectivity Connectivity PUBLIC 525
- 526. Using this API, you can read the list of all subaccounts connected to the Cloud Connector and view detail information for each subaccount: URL https://<scchost>:<sccport>/api/monitoring/ subaccounts Input None Output JSON document with list of detailed subaccount data, like: ● subaccounts: array of subaccounts for which the data is provided ○ regionHost: host of the region, in which the subaccount is resid ing ○ subaccount: name of subaccount ○ locationID: identifying the location of this Cloud Connector for a specific subaccount ○ tunnel: array of connection tunnels used by the subaccount ○ state: connected or disconnected ○ connectedSince: connection start time ○ connections: number of subaccount connections ○ applicationConnections: array of connections to ap plication instances ○ serviceChannels: type and state of the service channels used (types: HANA database, Virtual Machine or RFC) ○ recoveryAccountState: state and more details about the disaster recovery subaccount, if configured ○ isActive: disaster recovery subaccount is working (true or false) ● version: API version Example: 526 PUBLIC SAP BTP Connectivity Connectivity
- 527. Back to Available APIs [page 525] Back to Context [page 524] List of Open Connections (available as of version 2.10.0) Note This API is relevant for the master instance only. SAP BTP Connectivity Connectivity PUBLIC 527
- 528. The list of connections lets you view all back-end systems connected to the Cloud Connector and get detail information for each connection: URL https://<scchost>:<sccport>/api/monitoring/ connections/backends Input None Output JSON document with list of all open connections and detailed informa tion about back-end systems: ● subaccounts: array of subaccounts for which the data is pro vided ○ backendConnections: array of connections to a specified back-end system ○ virtualBackend: virtual (external) back-end URL ○ internalBackend: internal back-end URL ○ protocol: type of protocol (RFC, HTTP, and so on) ○ idle: number of idle connections ○ active: number of active connections ○ state: connected or disconnected ● version: API version Example: 528 PUBLIC SAP BTP Connectivity Connectivity
- 529. Back to Available APIs [page 525] Back to Context [page 524] Performance Monitor Data (available as of version 2.10.0) Note This API is relevant for the master instance only. Using this API, you can read the data provided by the Cloud Connector performance monitor: URL https://<scchost>:<sccport>/api/monitoring/ performance/backends SAP BTP Connectivity Connectivity PUBLIC 529
- 530. Input None Output JSON document with a list providing the Cloud Connector performance monitor data with detailed information about back-end performance: ● subaccounts: array of subaccounts for which data is provided ○ VirtualHost: host name of the back-end system ○ VirtualPort: port of the back-end system ○ Protocol: type of protocol (RFC, HTTP, and so on) ○ Buckets: array of performance data related to back-end sys tem ○ numberOfCalls: number of calls performed between Cloud Connector and back-end system ○ miniumCallDurationsMs: minimum duration of the executed calls in milliseconds ○ SinceTime: start of performance measurement ● version: API version Example: 530 PUBLIC SAP BTP Connectivity Connectivity
- 531. Back to Available APIs [page 525] Back to Context [page 524] Top Time Consumers (available as of version 2.11.0) Note This API is relevant for the master instance only. Using this API, you can read the data of top time consumers provided by the Cloud Connector performance monitor: SAP BTP Connectivity Connectivity PUBLIC 531
- 532. URL https://<scchost>:<sccport>/api/monitoring/ performance/toptimeconsumers Input None Output JSON document with list of top time consumer data: ● subaccounts: array of subaccounts for which the data is pro vided ○ backendConnections: array of connections to a specified back-end system ○ protocol: type of protocol (RFC, HTTP, and so on) ○ virtualBackend: virtual (external) back-end URL ○ internalBackend: internal back-end URL ○ resource: name of the request resource ○ sentBytes: number of sent bytes ○ receivedBytes: number of received bytes ○ user: name of the request user ○ totalTime: total request time in milliseconds ○ externalTime: in milliseconds ○ genSsoTime: in milliseconds ○ openRemoteTime: in milliseconds ○ validationSsoTime: time for SSO validation in milli seconds ○ latencyTime: latency in milliseconds ● version: API version Example: 532 PUBLIC SAP BTP Connectivity Connectivity
- 533. Back to Available APIs [page 525] Back to Context [page 524] Memory Status (available as of version 2.13.0) Note This API is relevant for the master instance only. This API provides a snapshot of the current memory status of the machine where the Cloud Connector is running: URL https://<scchost>:<sccport>/api/monitoring/ memory Input None SAP BTP Connectivity Connectivity PUBLIC 533
- 534. Output JSON document with memory data: ● physicalKB: usage of the physical memory, split into four cate gories (all sizes in KB): ○ total: total size of the physical memory ○ CloudConnector: size of the physical memory used by the Cloud Connector ○ others: size of the physical memory used by all other proc esses ○ free: size of the free physical memory ● virtualKB : usage of the virtual memory, split into four catego ries (all sizes in KB) ○ total: total size of the virtual memory ○ CloudConnector: size of the virtual memory used by the Cloud Connector ○ others: size of the virtual memory used by all other proc esses ○ free: size of the free virtual memory ● cloudConnectorHeapKB : usage of the Java heap, split into three categories (all sizes in KB): ○ total: total size of the Java heap ○ used: size of the Java heap used by the Cloud Connector ○ free: size of the free Java heap Example: Back to Available APIs [page 525] 534 PUBLIC SAP BTP Connectivity Connectivity
- 535. Back to Context [page 524] Certificate Status (available as of version 2.13.0) Note This API is relevant for the master instance only. Using this API, you can get an overview of the certificates currently employed by the Cloud Connector: URL https://<scchost>:<sccport>/api/monitoring/ certificates Input None SAP BTP Connectivity Connectivity PUBLIC 535
- 536. Output JSON document with data reflecting the current status of all certifi- cates. There are three categories or lists, each of them containing zero or more certificates: ● expired: list of all expired certificates ● expiring: list of all certificates that will expire in less than N days, where N is the number of days specified in the alerting setup regarding certificates that are close to their expiration date. ● ok : list of all certificates that continue to be valid for N days or more, where N is the number of days specified in the alerting setup regarding certificates that are close to their expiration date. A certificate in any of those lists is represented by a JSON object with the following properties: ● type: type of the certificate which can be one of the following strings: ○ UI (for the UI certificate) ○ System (for the system certificate) ○ CA (for the certificate used in connection with principal propa gation/certification authority) ○ subaccount (for subaccount certificates) ● validTo: end date of the respective certificate's validty (as a long integer, i.e. a UTC timestamp) ● subjectDN: subject DN of the respective certificate (included only for non-subaccount certificates) ● subaccountName: name of the subaccount (only for subaccount certificates) ● subaccountRegion: region or landscape host of the the subac count (only for subaccount certificates) ● isDisasterRecoverySubaccount: flag (Boolean value) that indicates that the subaccount is employed for disaster recovery. It can therefore be present only for subaccount certificates. More over, it is added only for disaster recovery subaccounts with its value set to true. URL https://<scchost>:<sccport>/api/monitoring/ certificates/expired Input None Output JSON document (an array) holding the list of all expired certificates. URL https://<scchost>:<sccport>/api/monitoring/ certificates/expiring Input None 536 PUBLIC SAP BTP Connectivity Connectivity
- 537. Output JSON document (an array) holding the list of all certificates that will ex pire in less than N days, where N is the number of days specified in the alerting setup regarding certifi- cates that are close to their expiration date. URL https://<scchost>:<sccport>/api/monitoring/ certificates/ok Input None Output JSON document (array) holding the list of all certificates that continue to be valid for N days or more, where N is the number of days specified in the alerting setup regarding certificates that are close to their expira tion date. Example: Back to Available APIs [page 525] Back to Context [page 524] Usage Statistics (available as of version 2.13.0) Note This API is relevant for the master instance only. SAP BTP Connectivity Connectivity PUBLIC 537
- 538. This API provides usage statistics regarding the systems and resources available in the Cloud Connector: URL https://<scchost>:<sccport>/api/monitoring/ performance/toptimeconsumers Input None 538 PUBLIC SAP BTP Connectivity Connectivity
- 539. Output JSON document (a JSON object) with usage data. There is one prop erty: ● subaccounts: list of subaccounts (a JSON array) Each subaccount in the subaccounts array is represented through an object with the following properties: ● subaccountName: name of the subaccount ● subaccountRegion: region host for the subaccount ● sinceTime: time at which collecting statistics started for this ac count (a UTC timestamp) ● usageStatistics: usage statistics, given as an array. Each element of the usageStatistics array corresponds to one system (virtual host) and is represented through an object with the following properties: ● virtualHost: name of the virtual host ● virtualPort: port of the virtual host ● protocol: protocol this virtual host can process. Note Currently, statistical data is collected only for protocols HTTP, HTTPS, RFC, and RFC SNC, and hence systems relying on other protocols are not listed here. ● bytesReceived: total number of bytes that were received through a call or request ● bytesSent: total number of bytes sent back as a response ● calls: total number of calls or requests ● mostRecentAccess: time of the most recent access (call or re quest) given as a UTC timestamp. Note This property is only available if there has been at least one call or request. ● resources: usage statistics per resource, given as an array (i.e. the distribution of bytes received, sent, as well as number of calls/ requests, across the resources of the respective virtual host). Each element of the resources array holds the usage statistics of a re source, represented through an object with the following properties: ● resourceName: name of the resource (a URL path or the name of a remote function) SAP BTP Connectivity Connectivity PUBLIC 539
- 540. ● enabled: Boolean flag that indicates whether the resource is cur rently active (true) or suspended (false). ● bytesReceived: total number of bytes that were received through a call or request and were handled by this resource. ● bytesSent: total number of bytes sent back as a response in the context of this resource. ● calls: total number of calls or requests handled by this resource ● mostRecentAccess: time of the most recent access (i.e., call or request) given as a UTC timestamp. Note This property is only available if at least one call or request was handled by this resource. Note Usage statistics are collected at runtime and stored in memory. They are lost when stopping or restarting the Cloud Connector. Example: 540 PUBLIC SAP BTP Connectivity Connectivity
- 541. SAP BTP Connectivity Connectivity PUBLIC 541
- 542. Back to Available APIs [page 525] Back to Context [page 524] 1.2.3.7 Alerting Configure the Cloud Connector to send e-mail messages when situations occur that may prevent it from operating correctly. To configure alert e-mails, choose Alerting from the top-left navigation menu. You must specify the receivers of the alert e-mails (E-mail Configuration) as well as the Cloud Connector resources and components that you want to monitor (Observation Configuration). The corresponding Alert Messages are also shown in the Cloud Connector administration UI. E-mail Configuration 1. Select E-mail Configuration to specify the list of em-ail addresses to which alerts should be sent (Send To). Note The addresses you enter here can use either of the following formats: [email protected] or John Doe <[email protected]>. 2. Enter the sender's e-mail address (<Sent From>). 3. In <SMTP Server> provide the host of the mail server. 4. You can specify an <SMTP port>, if the server is not using the default ports. For details, contact your e- mail administrator or provider. 5. Mark the TLS Enabled check box if you want to establish a TLS-encrypted connection. 6. If the SMTP server requires authentication, provide <User> and <Password>. 7. In the Additional Properties section you can provide any property supported by the Java Mail library . All specified properties will be passed to the SMTP client. 8. Select Save to change the current configuration. 542 PUBLIC SAP BTP Connectivity Connectivity
- 543. Note Connections to an SMTP server over SSL/TLS can cause SSL errors if the SMTP server uses an "untrusted" certificate. If you cannot use a trusted certificate, you must import the public part of the issuer certificate to the JDK's trust storage. Usually, the trust storage is done in the file cacerts in the Java directory (jre/lib/security/cacerts). For import, you can use the keytool utility: keytool -import -storepass changeit -file <certificate used by SMTP server> - keystore cacerts -alias <for example, SMTP_xyz> For more information, see https:/ /docs.oracle.com/cd/E19830-01/819-4712/ablqw/index.html . Observation Configuration Once you've entered the e-mail addresses to receive alerts, the next step is to identify the resources and components of the Cloud Connector: E-mail messages are sent when any of the chosen components or resources have malfunctioned or are in a critical state. Note The Cloud Connector does not dispatch the same alert repeatedly. As soon as an issue has been resolved, an informational alert is generated, sent, and listed in Alert Messages (see section below). 1. Select Observation Configuration from the top-right corner of the window. 2. Select the components or resources you want to monitor. ○ High Availability alerts can occur in the context of an active high availability setup, meaning a shadow system is connected. SAP BTP Connectivity Connectivity PUBLIC 543
- 544. ○ Tunnel Health and Service Channels Health refer to the state of the respective connections. Whenever such a connection is lost, an alert is triggered. Note These alerts are only triggered in case of an error or exception, but not upon intentional disconnect action. ○ An excessively high CPU load over an extended period of time adversely affects performance and may be an indicator of serious issues that jeopardize the operability of the Cloud Connector. The CPU load is monitored and an alert is triggered whenever the CPU load exceeds and continues to exceed a given threshold percentage (the default is 90%) for more than a given period of time (the default is 60 seconds). ○ Although the Cloud Connector does not require nor consume large amounts of Disk space, running out of it is a circumstance that you should avoid. We recommend that you configure an alert to be sent if the disk space falls below a critical value (the default is 10 megabytes). ○ The Cloud Connector configuration contains various Certificates. Whenever one of those expires, scenarios might no longer work as expected so it's important to get notified about the expiration (the default is 30 days). 3. (Optional) Change the Health Check Interval (the default is 30 seconds). 4. Select Save to change the current configuration. Alert Messages The Cloud Connector shows alert messages also on screen, in Alerting Alert Messages . You can remove alerts using Delete or Delete All. If you delete active (unresolved) alerts, they reappear in the list after the next health check interval. 544 PUBLIC SAP BTP Connectivity Connectivity
- 545. 1.2.3.8 Audit Logging Audit log data can alert Cloud Connector administrators to unusual or suspicious network and system behavior. Additionally, the audit log data can provide auditors with information required to validate security policy enforcement and proper segregation of duties. IT staff can use the audit log data for root-cause analysis following a security incident. The Cloud Connector includes an auditor tool for viewing and managing audit log information about access between the cloud and the Cloud Connector, as well as for tracking of configuration changes done in the Cloud Connector. The written audit log files are digitally signed by the Cloud Connector so that their integrity can be checked, see Manage Audit Logs [page 545]. Note We recommend that you permanently switch on Cloud Connector audit logging in productive scenarios. ● Under normal circumstances, set the logging level to Security (the default configuration value). ● If legal requirements or company policies dictate it, set the logging level to All. This lets you use the log files to, for example, detect attacks of a malicious cloud application that tries to access on-premise services without permission, or in a forensic analysis of a security incident. We also recommend that you regularly copy the audit log files of the Cloud Connector to an external persistent storage according to your local regulations. The audit log files can be found in the Cloud Connector root directory /log/audit/<subaccount-name>/audit-log_<timestamp>.csv. 1.2.3.8.1 Manage Audit Logs Configure audit log settings and verify the integrity of audit logs. Configure Audit Logs in the Cloud Connector Choose Audit from your subaccount menu and go to Settings to specify the type of audit events the Cloud Connector should log at runtime. You can currently select between the following Audit Levels (for either <subaccount> and <cross-subaccount> scope): ● Security: Default value. The Cloud Connector writes an audit entry (Access Denied) for each request that was blocked. It also writes audit entries, whenever an administrator changes one of the critical configuration settings, such as exposed back-end systems, allowed resources, and so on. ● All: The Cloud Connector writes one audit entry for each received request, regardless of whether it was allowed to pass or not (Access Allowed and Access Denied). It also writes audit entries that are relevant to the Security mode. ● Off: No audit entries are written. SAP BTP Connectivity Connectivity PUBLIC 545
- 546. Note We recommend that you don't log all events unless you are required to do so by legal requirements or company policies. Generally, logging security events only is sufficient. To enable automatic cleanup of audit log files, choose a period (14 to 365 days) from the list in the field <Automatic Cleanup>. Audit entries for configuration changes are written for the following different categories: ● Account: A subaccount configuration was changed. ● RecoveryAccount: A disaster recovery subaccount configuration was changed. ● Configuration: A new subaccount was added or a disaster recovery switch happened. ● BackendMapping: Changes to the virtual to internal system mappings. ● AllowedResource: In a virtual system, changes in the accessible resources. ● DomainMapping: Changes to the domain mappings. ● ServiceChannelConfiguration: The configuration of a service channel was changed. ● SCCPassword: The Cloud Connector administration password was changed. ● SCCUser: The Cloud Connector administration user was changed. ● LDAPConfiguration: Changes to the LDAP settings. ● EmailConfiguration: The Email settings for alerts were changed. ● AlertConfiguration: The observation settings for alerts were changed. ● ScimConfiguration: Something changed in the settings for the cloud user store. ● KerberosConfiguration: The Kerberos configuration was changed. ● SNCSettings: SNC settings of Cloud Connector were changed. ● ProxySettings: The proxy settings were changed. ● SystemCertificate: The system certificate was changed. ● PpcaCertificate: The CA certificate was changed. ● PrincipalPropagationConfiguration: The principal propagation settings were changed. ● TrustSynchronization: The trust configuration for principal propagation was synchronized. ● IdentityProviderTrust: The trust configuration for a specific identity provider was changed. ● ApplicationTrust: The trust configuration to applications was changed. ● TrustedBackendCertificate: The trust store certificate was added or removed. ● SccCustomRoles: Custom role name settings were changed. ● BackendAuthority: RFC-specific user and client settings were adjusted. ● AdvancedConnectivity: Advanced connectivity configuration was changed. ● AdvancedJVM: Advanced JVM configuration was changed. ● ApplicationConfiguration: Application-specific connection configuration was changed. ● PayloadTrace: Payload trace (traffic data) was activated/deactivated. ● CPICTrace: The CPIC trace level was changed. ● AuditLogLevel: The subaccount-specific audit log level was changed. ● CrossAuditLogLevel: The cross-subaccount audit log level was changed. ● AuditLogCleanup: The audit log cleanup setting was changed. In the Audit Viewer section, you can first define filter criteria, then display the selected audit entries. 546 PUBLIC SAP BTP Connectivity Connectivity
- 547. ● In the Audit Type field, you can select whether to view the audit entries for the following: ○ Any entries ○ Only denied requests ○ Only allowed requests ○ Service started ○ Service stopped ○ Cloud Connector changes ○ High Availability ○ Principal Propagation ● In the Pattern field, you can specify a certain string that the detail text of each selected audit entry must contain. The detail text contains information about the user name, requested resource/URL, and the virtual <host>:<port>. Wildcards are currently not supported. Use this feature to do the following: ○ Filter the audit log for all requests that a particular HTTP user has made during a certain time frame. ○ Identify all users who attempted to request a particular URL. ○ Identify all requests to a particular back-end system. ○ Determine whether a user has changed a certain Cloud Connector configuration. For example, a search for string BackendMapping returns all add-, delete- or modify- operations on the Mapping Virtual To Internal System page. ● The Time Range settings specify the time frame for which you want to display the audit events. These filter criteria are combined with a logical AND so that all audit entries that match these criteria are shown. If you have modified one of the criteria, select Refresh to display the updated selection of audit events that match the new criteria. Note To prevent a single person from being able to both change the audit log level, and delete audit logs, we recommend that the operating system administrator and the SAP BTP administrator are different persons. We also suggest that you turn on the audit log at the operating system level for file operations. The Check button checks all files that are filtered by the specified date range. Verify the Integrity of Audit Logs To check the integrity of the audit logs, go to <scc_installation>/auditor. This directory contains an executable go script file (respectively, go.cmd on Microsoft Windows and go.sh on other operating systems). If you start the go file without specifying parameters from <scc_installation>/auditor, all available audit logs for the current Cloud Connector installation are verified. The auditor tool is a Java application, and therefore requires a Java runtime, specified in JAVA_HOME, to execute: ● For Microsoft Windows OS, set JAVA_HOME=<path-to-java-installation> ● For Linux OS and Mac OS X, export: JAVA_HOME=<path-to-java-installation> Alternatively, to execute Java, you can include the Java bin directory in the PATH variable. SAP BTP Connectivity Connectivity PUBLIC 547
- 548. Example In the following example, the Audit Viewer displays Any audit entries, at Security level, for the time frame between December 18 2020, 00:00:00 and December 19, 00:00:00: 1.2.3.9 Troubleshooting To troubleshoot connection problems, monitor the state of your open tunnel connections in the Cloud Connector, and view different types of logs and traces. Note For information about a specific problem or an error you have encountered, see Connectivity Support [page 581]. Monitoring To view a list of all currently connected applications, choose your Subaccount from the left menu and go to section Cloud Connections: 548 PUBLIC SAP BTP Connectivity Connectivity
- 549. The provided information includes: ● Application name: The name of the application, as also shown in the cockpit, for your subaccount ● Connections: The number of currently existing connections to the application ● Connected Since: The earliest start time of a connection to this application ● Peer Labels: The name of the application processes, as also shown for this application in the cockpit, for your subaccount Log and Trace Settings The Log and Trace Files page includes some files for troubleshooting that are intended primarily for SAP Support. These files include information about both internal Cloud Connector operations and details about the communication between the local and the remote (SAP BTP) tunnel endpoint. If you encounter problems that seem to be caused by some trouble in the communication between your cloud application and the on-premise system, choose Log and Trace Files from your Subaccount menu, go to section Settings, and activate the respective traces by selecting the Edit button: ● Cloud Connector Loggers adjusts the levels for Java loggers directly related to Cloud Connector functionality. ● Other Loggers adjusts the log level for all other Java loggers available at the runtime. Change this level only when requested to do so by SAP support. When set to a level higher than Information, it generates a large number of trace entries. ● CPIC Trace Level allows you to set the level between 0 and 3 and provides traces for the CPIC-based RFC communication with ABAP systems. ● When the Payload Trace is activated for a subaccount, all the HTTP and RFC traffic crossing the tunnel for that subaccount going through this Cloud Connector, is traced in files with names traffic_trace_<subaccount id>_on_<regionhost>.trc. Note Use payload and CPIC tracing at Level 3 carefully and only when requested to do so for support reasons. The trace may write sensitive information (such as payload data of HTTP/RFC requests and responses) to the trace files, and thus, present a potential security risk. As of version 2.2, the Cloud Connector supports an implementation of a "four-eyes principle" for activating the trace levels that SAP BTP Connectivity Connectivity PUBLIC 549
- 550. dump the network traffic into a trace file. This principle requires two users to activate a trace level that records traffic data. See Secure the Activation of Traffic Traces [page 515]. ● SSL Trace: When the SSL trace is activated, the ljs_trace.log file includes information for SSL- protected communication. To activate a change of this setting, a restart is required. Activate this trace only when requested by SAP support. It has a high impact on performance as it produces a large amount of traces. ● Automatic Cleanup lets you remove old trace files that have not been changed for a period of time exceeding the configured interval. You can choose from a list of predefined periods. The default is Never. Log and Trace Files View all existing trace files and delete the ones that are no longer needed. 550 PUBLIC SAP BTP Connectivity Connectivity
- 551. To prevent your browser from being overloaded when multiple large files are loaded simultaneously, the Cloud Connector loads only one page into memory. Use the page buttons to move through the pages. Use the Download/Download All icons to create a ZIP archive containing one trace file or all trace files. Download it to your local file system for convenient analysis. Note If you want to download more than one file, but not all, select the respective rows of the table and choose Download All. When running the Cloud Connector with SAP JVM, it is possible to trigger the creation of a thread dump by pressing the Thread Dump button, which will be written to the JVM trace file vm_$PID_trace.log . You will be requested by SAP support to create one if it is expected to help during incident analysis. Note From the UI, you can't delete trace files that are currently in use. You can delete them from the Linux OS command line; however, we recommend that you do not use this option to avoid inconsistencies in the internal trace management of the Cloud Connector. Two buttons may be helpful to solve issues on your own: ● Guided Answers: A new tab or window opens, showing the Cloud Connector section in Guided Answers . It helps you identify many issues that are classified through hierarchical topics. Once you found a matching issue, a solution is provided either directly, or by references to SAP Help Portal, Knowledge Base Articles (KBAs), and SAP notes. ● Support Log Assistant: Opens the support log assistant. There, you can upload Cloud Connector log files and have them analyzed. After triggering the scan, the tool lists all issues for which a solution can be identified. SAP BTP Connectivity Connectivity PUBLIC 551
- 552. Note The support log assistant analyzes the complete log. Therefore, also older issues may be found that are no longer relevant. Once a problem has been identified, you should turn off the trace again by editing the trace and log settings accordingly to not flood the files with unnecessary entries. Use the Refresh button to update the information that appears. For example, you can use this button because more trace files might have been written since you last updated the display. Error Analysis and Support: Which Logs are Relevant? If you contact SAP support for help, please always attach the appropriate log files and provide the timestamp or period, when the reported issue was observed. Depending on the situation, different logs may help to find the root cause. Some typical settings to get the required data are listed below: ● <Cloud Connector Loggers> provide details related to connections to SAP BTP and to backend systems as well as master-shadow communication in case of a high availability setup. However, it does not contain any payload data. This kind of trace is written into ljs_trace.log, which is the most relevant log for the Cloud Connector. ● <Other Loggers> provide details related to the tomcat runtime, in which the Cloud Connector is running. The traces are written into ljs_trace.log as well, but they are needed only in very special support situations. If you don't need these traces, leave the level on Information or even lower. ● Payload data are written into the traffic trace file for HTTP or RFC requests if the payload trace is activated, or into the CPI-C trace file for RFC requests, if the CPI-C trace is set to level 3. ● <TLS trace> is helpful to analyze TLS handshake failures from Cloud Connector to Cloud or from Cloud Connector to backend. It should be turned off again as soon as the issue has been reproduced and recorded in the traces. ● Setting the audit log on level ALL for <Subaccount Audit Level> is the easiest way to check if a request reached the the Cloud Connector and if it is being processed. Related Information Getting Support 552 PUBLIC SAP BTP Connectivity Connectivity
- 553. 1.2.3.10 Process Guidelines for Hybrid Scenarios A hybrid scenario is one, in which applications running on SAP BTP require access to on-premise systems. Define and document your scenario to get an overview of the required process steps. Tasks Document the Landscape of a Hybrid Solution [page 553] Document Administrator Roles [page 554] Document Communication Channels [page 554] Define Project and Development Guidelines [page 555] Define How to Set a Cloud Application Live [page 555] Document the Landscape of a Hybrid Solution To gain an overview of the cloud and on-premise landscape that is relevant for your hybrid scenario, we recommend that you diagrammatically document your cloud subaccounts, their connected Cloud Connectors and any on-premise back-end systems. Include the subaccount names, the purpose of the subaccounts (dev, test, prod), information about the Cloud Connector machines (host, domains), the URLs of the Cloud Connectors in the landscape overview document, and any other details you might find useful to include. An example of landscape overview documentation could look like this: SAP BTP Connectivity Connectivity PUBLIC 553
- 554. Back to Tasks [page 553] Document Administrator Roles Document the users who have administrator access to the cloud subaccounts, to the Cloud Connector operating system, and to the Cloud Connector administration UI. Such an administrator role documentation could look like following sample table: Resource [email protected] [email protected] [email protected] [email protected] Cloud Subaccount (CA) Dev1 X CA Dev2 X CA Test X X CA Prod X Cloud Connector Dev1 + Dev2 X X Cloud Connector Test X X Cloud Connector Prod X Cloud Connector Dev1 + Dev2 file system X X Cloud Connector Test file system X Cloud Connector Prod file system Back to Tasks [page 553] Document Communication Channels Create and document separate email distribution lists for both the cloud subaccount administrators and the Cloud Connector administrators. An example of the documented communication channels could look like this: Landscape Distribution List Cloud Subaccount Administrators DL ACME HCP Subaccount Admins Cloud Connector Administrators DL ACME Cloud Connector Admins 554 PUBLIC SAP BTP Connectivity Connectivity
- 555. Back to Tasks [page 553] Define Project and Development Guidelines Define and document mandatory project and development guidelines for your SAP BTP projects. An example of such a guideline could be similar to the following. Every SAP BTP project in this organization requires the following: ● Use Maven, Nexus, Git-&-Gerrit for the application development. ● Align with accountable manager in projects (including the names). ● Align with accountable security officer in projects (including the names). ● For externally developed source code, an official handover to the organization. ● Fulfill connection restrictions in a three-system landscape, that is, use a staged landscape for dev, test and prod, and, for example, the dev landscape connects only to dev systems, and so on. ● Productive subaccounts cannot use the same Cloud Connector as a dev or test subaccount. Back to Tasks [page 553] Define How to Set a Cloud Application Live Define and document how to set a cloud application live and how to configure needed connectivity for such an application. For example, the following processes could be seen as relevant and should be defined and document in more detail: 1. Transferring application to production: Steps for transferring an application to the productive status on the SAP BTP. 2. Application connectivity: The steps for adding a connectivity destination to a deployed application for connections to other resources in the test or productive landscape. 3. Cloud Connector Connectivity: Steps for adding an on-premise resource to the Cloud Connector in the test or productive landscapes to make it available for the connected cloud subaccounts. 4. On-premise system connectivity: The steps for setting up a trusted relationship between an on-premise system and the Cloud Connector, and to configure user authentication and authorization in the on-premise system in the test or productive landscapes. 5. Application authorization: The steps for requesting and assigning an authorization that is available inside the SAP BTP application to a user in the test or productive landscapes. 6. Administrator permissions: Steps for requesting and assigning the administrator permissions in a cloud subaccount to a user in the test or productive landscape. Back to Tasks [page 553] SAP BTP Connectivity Connectivity PUBLIC 555
- 556. 1.2.4 Security Learn how Cloud Connector features help you manage security. Features Security is a crucial concern for any cloud-based solution. It has a major impact on the business decision of enterprises whether to make use of such solutions. SAP BTP is a platform-as-a-service offering designed to run business-critical applications and processes for enterprises, with security considered on all levels of the on- demand platform: Level Features Application Layer [page 557] ● Frontend security ● Security standard-based application development Service Layer [page 557] ● Identity and access management ● Data protection ● Regulatory compliance management Cloud Infrastructure Layer [page 562] ● Network infrastructure and communication ● Sandboxing ● Intrusion detection and prevention Physical and Environmental Layer [page 563] ● Strict physical access control ● High availability and disaster recovery capabilities The Cloud Connector enables integration of cloud applications with services and systems running in customer networks, and supports database connections from the customer network to SAP HANA databases running on SAP BTP. As these are security-sensitive topics, this section gives an overview on how the Cloud Connector helps maintain security standards for the mentioned scenarios. Target Audience The content of this section concerns: ● System and IT administrators ● Technology consultants ● Solution architects 556 PUBLIC SAP BTP Connectivity Connectivity
- 557. Related Information Security Guidelines [page 563] 1.2.4.1 Application Layer On application level, the main tasks to ensure secure Cloud Connector operations are to provide appropriate frontend security (for example, validation of entries) and a secure application development. Product Security Standard Basically, you should follow the rules given in the product security standard, for example, protection against cross-site scripting (XSS) and cross-site request forgery (XSRF). Scope and Design The scope and design of security measures on application level strongly depend on the specific needs of your application. 1.2.4.2 Service Layer You can use SAP BTP Connectivity to securely integrate cloud applications with systems running in isolated customer networks. Overview After installing the Cloud Connector as integration agent in your on-premise network, you can use it to establish a persistent TLS tunnel to SAP BTP subaccounts. To establish this tunnel, the Cloud Connector administrator must authenticate himself or herself against the related SAP BTP subaccount of which he or she must be a member. Once estabilshed, the tunnel can be used by applications of the connected subaccount to remotely call systems in your network. SAP BTP Connectivity Connectivity PUBLIC 557
- 558. Architecture The figure below shows a system landscape in which the Cloud Connector is used for secure connectivity between SAP BTP applications and on-premise systems. ● A single Cloud Connector instance can connect to multiple SAP BTP subaccounts, each connection requiring separate authentication and defining an own set of configuration. ● You can connect an arbitrary number of SAP and non-SAP systems to a single Cloud Connector instance. ● The on-premise system does not need to be touched when used with the Cloud Connector, unless you configure trust between the Cloud Connector and your on-premise system. A trust configuration is required, for example, for principal propagation (single sign-on), see Configuring Principal Propagation [page 340]. ● You can operate the Cloud Connector in a high availability mode. To achieve this, you must install a second (redundant) Cloud Connector (shadow instance), which takes over from the master instance in case of a downtime. ● The Cloud Connector also supports the communication direction from the on-premise network to the SAP BTP subaccount, using a database tunnel that lets you connect common ODBC/JDBC database tools to SAP HANA as well as other available databases in SAP BTP. . Related Information Network Zones [page 559] Inbound Connectivity [page 559] Outbound Connectivity [page 561] 558 PUBLIC SAP BTP Connectivity Connectivity
- 559. Audit Log [page 561] 1.2.4.2.1 Network Zones Choosing a network zone for the Cloud Connector installation. A company network is usually divided into multiple network zones according to the security level of the contained systems. The DMZ network zone contains and exposes the external-facing services of an organization to an untrusted network, typically the Internet. Besides this, there can be one or multiple other network zones which contain the components and services provided in the company’s intranet. You can set up the Cloud Connector either in the DMZ or in an inner network zone. Technical prerequisites for the Cloud Connector to work properly are: ● The Cloud Connector must have access to the SAP BTP landscape host, either directly or via HTTPS proxy (see also: Prerequisites [page 274]). ● The Cloud Connector must have direct access to the internal systems it shall provide access to. I.e. there must be transparent connectivity between the Cloud Connector and the internal system. It’s a company’s decision, whether the Cloud Connector is set up in the DMZ and operated centrally by an IT department or set up in the intranet and operated by the line of business. Related Information Network Zones [page 285] 1.2.4.2.2 Inbound Connectivity For inbound connections into the on-premise network, the Cloud Connector acts as a reverse invoke proxy between SAP BTP and the internal systems. Exposing Resources Once installed, none of the internal systems are accessible by default through the Cloud Connector: you must configure explicitly each system and each service and resource on every system to be exposed to SAP BTP in the Cloud Connector. You can also specify a virtual host name and port for a configured on-premise system, which is then used in the cloud. Doing this, you can avoid that information on physical hosts is exposed to the cloud. SAP BTP Connectivity Connectivity PUBLIC 559
- 560. TLS Tunnel The TLS (Transport Layer Security) tunnel is established from the Cloud Connector to SAP BTP via a so-called reverse invoke approach. This lets an administrator have full control of the tunnel, since it can’t be established from the cloud or from somewhere else outside the company network. The Cloud Connector administrator is the one who decides when the tunnel is established or closed. The tunnel itself is using TLS with strong encryption of the communication, and mutual authentication of both communication sides, the client side (Cloud Connector) and the server side (SAP BTP). The X.509 certificates which are used to authenticate the Cloud Connector and the SAP BTP subaccount are issued and controlled by SAP BTP. They are kept in secure storages in the Cloud Connector and in the cloud. Having encrypted and authenticated the tunnel, confidentiality and authenticity of the communication between the SAP BTP applications and the Cloud Connector is guaranteed. Restricting Allowed Applications As an additional level of control, the Cloud Connector optionally allows restricting the list of SAP BTP applications which are able to use the tunnel. This is useful in situations where multiple applications are deployed in a single SAP BTP subaccount while only particular applications require connectivity to on-premise systems. Isolation on Subaccount Level SAP BTP guarantees strict isolation on subaccount level provided by its infrastructure and platform layer. An application of one subaccount is not able to access and use resources of another subaccount. Supported Protocols The Cloud Connector supports inbound connectivity for HTTP and RFC, any other protocol is not supported. ● The payload sent via these protocols is encrypted on TLS/tunnel-level. ● For the route from the Cloud Connector to the on-premise systems, Cloud Connector administrators have the choice for each configured on-premise system whether to use HTTP, HTTPS, RFC or RFC over SNC. ● For HTTPS, you can configure a so-called system certificate in the Cloud Connector which is used for the trust relationship between the Cloud Connector and the connected on-premise systems. ● For RFC over SNC, you can configure an SNC PSE in the Cloud Connector respectively. Principal Propagation The Cloud Connector also supports principal propagation of the cloud user identity to connected on-premise systems (single sign-on). For this, the system certificate (in case of HTTPS) or the SNC PSE (in case of RFC) is 560 PUBLIC SAP BTP Connectivity Connectivity
- 561. mandatory to be configured and trust with the respective on-premise system must be established. Trust configuration, in particular for principal propagation, is the only reason to configure and touch an on-premise system when using it with the Cloud Connector. Related Information Configuring Principal Propagation [page 340] 1.2.4.2.3 Outbound Connectivity The Cloud Connector supports the communication direction from the on-premise network to SAP BTP, using a database tunnel. The database tunnel is used to connect local database tools via JDBC or ODBC to the SAP HANA DB or other databases onSAP BTP, for example, SAP Business Objects tools like Lumira, BOE or Data Services. ● The database tunnel only allows JDBC and ODBC connections from the Cloud Connector into the cloud. A reuse for other protocols is not possible. ● The tunnel uses the same security mechanisms as for the inbound connectivity: ○ TLS-encryption and mutual authentication ○ Audit logging To use the database tunnel, two different SAP BTP users are required: ● A platform user (member of the SAP BTP subaccount) establishes the database tunnel to the HANA DB. ● A HANA DB user is needed for the ODBC/JDBC connection to the database itself. For the HANA DB user, the role and privilege management of HANA can be used to control which actions he or she can perform on the database. Related Information Using Service Channels [page 482] 1.2.4.2.4 Audit Log As audit logging is a critical element of an organization’s risk management strategy, the Cloud Connector provides audit logging for the complete record of access between cloud and Cloud Connector as well as of configuration changes done in the Cloud Connector. SAP BTP Connectivity Connectivity PUBLIC 561
- 562. Integrity Check The written audit log files are digitally signed by the Cloud Connector so that they can be checked for integrity (see also: Manage Audit Logs [page 545]). Alerting The audit log data of the Cloud Connector can be used to alert Cloud Connector administrators regarding unusual or suspicious network and system behavior. Additional Use Cases ● The audit log data can provide auditors with information required to validate security policy enforcement and proper segregation of duties. ● IT staff can use the audit log data for root-cause analysis following a security incident. Related Information Audit Logging [page 545] 1.2.4.3 Cloud Infrastructure Layer Infrastructure and network facilities of the SAP BTP ensure security on network layer by limiting access to authorized persons and specific business purposes. Isolated Network The SAP BTP landscape runs in an isolated network, which is protected from the outside by firewalls, DMZ, and communication proxies for all inbound and outbound communications to and from the network. 562 PUBLIC SAP BTP Connectivity Connectivity
- 563. Sandboxed Environments The SAP BTP infrastructure layer also ensures that platform services, like the SAP BTP Connectivity, and applications are running isolated, in sandboxed environments. An interaction between them is only possible over a secure remote communication channel. 1.2.4.4 Physical and Environmental Layer Learn about data center security provided for SAP BTP Connectivity. SAP BTP runs in SAP-hosted data centers which are compliant with regulatory requirements. The security measures include, for example: ● strict physical access control mechanisms using biometrics, video surveillance, and sensors ● high availability and disaster recoverability with redundant power supply and own power generation 1.2.4.5 Security Guidelines Find a checklist of recommended security measures for the Cloud Connector. Topics Hover over the elements for a description. Click an element to find the recommended actions in the table below. ● #unique_158/unique_158_Connect_42_network [page 564] ● #unique_158/unique_158_Connect_42_ui [page 564] ● #unique_158/unique_158_Connect_42_availability [page 566] SAP BTP Connectivity Connectivity PUBLIC 563
- 564. ● #unique_158/unique_158_Connect_42_protocols [page 566] ● #unique_158/unique_158_Connect_42_os [page 564] ● #unique_158/unique_158_Connect_42_oP [page 566] ● #unique_158/unique_158_Connect_42_instances [page 567] ● #unique_158/unique_158_Connect_42_audit [page 565] Recommended Actions Topic Description Recommended Action Network Zone Back to Topics [page 563] Depending on the needs of the project, the Cloud Connector can be either set up in the DMZ and operated centrally by the IT department or set up in the in tranet and operated by the line-of-busi ness. To access highly secure on-premise systems, operate the Cloud Connector centrally by the IT department and in stall it in the DMZ of the company net work. Set up trust between the on-premise system and the Cloud Connector, and only accept requests from trusted Cloud Connectors in the system. OS-Level Protection Back to Topics [page 563] The Cloud Connector is a security-criti cal component that handles the in bound access from SAP BTP applica tions to systems of an on-premise net work. Methods to secure the operating sys tem, on which the Cloud Connector is running, should be applied. Restrict access to the operating system on which the Cloud Connector is instal led to the minimal set of users who should administrate the Cloud Connector. Use the machine which runs the Cloud Connector only for this purpose and don’t reuse it for other scenarios. Use hard-drive encryption for the ma chine that runs the Cloud Connector. This ensures that the Cloud Connector configuration data cannot be read or modified by unauthorized users, even if they obtain access to the hard drive. Turn on the audit log on operating sys tem level to monitor the file operations. Administration UI Back to Topics [page 563] After installation, the Cloud Connector provides an initial user name and pass word and forces the user (Administrator) to change the password upon initial logon. Change the password of the Administrator user immediately after in stallation. Choose a strong password for the user (see also Recommenda tions for Secure Setup [page 299]). 564 PUBLIC SAP BTP Connectivity Connectivity
- 565. Topic Description Recommended Action Configure a corporate LDAP system for the user management of the Cloud Connector administrator users. This guarantees that users of the Cloud Connector administration UI are named users and can be traced via the Cloud Connector audit log (see Use LDAP for Authentication [page 503]). You can access the Cloud Connector administration UI remotely via HTTPS. After installation, it uses a self-signed X. 509 certificate as SSL server certifi- cate, which is not trusted by default by Web browsers. Exchange the self-signed X.509 certifi- cate of the Cloud Connector adminis tration UI by a certificate that is trusted by your company and the company’s approved Web browser settings (see [Deprecated] Replace the Default SSL Certificate [page 306]). For high-security scenarios, limit the access to the Cloud Connector admin istration UI to localhost (see also Rec ommendations for Secure Setup [page 299]). Use a JVM that allows to limit the ci phers to a set considered safe (see Rec ommendations for Secure Setup [page 299]). A list of cipher suites, which are currently considered safe, is available in Use Secure Cipher Suites . Audit Logging Back to Topics [page 563] For end-to-end traceability of configura- tion changes in the Cloud Connector, as well as communication delivered by the Cloud Connector, switch on audit log ging for productive scenarios. Switch on audit logging in the Cloud Connector: set audit level to “All” (see Recommendations for Secure Setup [page 299] and Manage Audit Logs [page 545]) Cloud Connector administrators must ensure that the audit log files are prop erly archived and are not lost, to con form to the local regulations. To gain end-to-end traceability, you should switch on audit logging also in the connected on-premise systems. SAP BTP Connectivity Connectivity PUBLIC 565
- 566. Topic Description Recommended Action High Availability Back to Topics [page 563] To guarantee high availability of the connectivity for cloud integration sce narios, run productive instances of the Cloud Connector in high availability mode, that is, with a second (redun dant) Cloud Connector in place. Use the high availability feature of the Cloud Connector for productive scenar ios (see Install a Failover Instance for High Availability [page 508]). Supported Protocols Back to Topics [page 563] HTTP, HTTPS, RFC and RFC over SNC are currently supported as protocols for the communication direction from the cloud to on-premise. The route from the application VM in the cloud to the Cloud Connector is al ways encrypted. You can configure the route from the Cloud Connector to the on-premise system to be encrypted or unen crypted. The route from the Cloud Connector to the on-premise system should be en crypted using TLS (for HTTPS) or SNC (for RFC). Trust between the Cloud Connector and the connected on-premise systems should be established (see Set Up Trust for Principal Propagation [page 341]). Configuration of On-Premise Systems Back to Topics [page 563] When configuring the access to an in ternal system in the Cloud Connector, map physical host names to virtual host names to prevent exposure of infor mation on physical systems to the cloud. Use hostname mapping of exposed on- premise systems in the access control of the Cloud Connector (see Configure Access Control (HTTP) [page 370] and Configure Access Control (RFC) [page 377]). When configuring the access to an in ternal system, restrict access to those resources which are actually required by the cloud applications. Do not ex pose the complete system. Narrow access to on-premise systems to resources required by the relevant cloud applications in the access control of the Cloud Connector (see Configure Access Control (HTTP) [page 370] and Configure Access Control (RFC) [page 377]). To allow access only for trusted appli cations of your SAP BTP subaccount to on-premise systems, configure the list of trusted applications in the Cloud Connector. Narrow the list of cloud applications which are allowed to use the on-prem ise tunnel to the ones that need on- premise connectivity (see Set Up Trust for Principal Propagation [page 341]). 566 PUBLIC SAP BTP Connectivity Connectivity
- 567. Topic Description Recommended Action Cloud Connector Instances Back to Topics [page 563] You can connect a single Cloud Connector instance to multiple SAP BTP subaccounts. Subaccounts can be created by SAP BTP users as a self service. Different subaccounts are often used to sepa rate development, test and produc tion. Do not mix productive Cloud Connector usages with development or test sce narios. Use different Cloud Connector instan ces to separate productive and non- productive scenarios. Related Information Recommendations for Secure Setup [page 299] Secure the Activation of Traffic Traces [page 515] 1.2.5 Upgrade Upgrade your Cloud Connector and avoid connectivity downtime during the update. The steps for upgrading your Cloud Connector are specific to the operating system that you use. Previous settings and configurations are automatically preserved. Caution Upgrade is supported only for installer versions, not for portable versions, see Installation [page 273]. Before upgrading, please check the Prerequisites [page 274] and make sure your environment fits the new version. We recommend that you create a Configuration Backup [page 498] before starting an upgrade. Avoid Connectivity Downtime If you have a single-machine Cloud Connector installation, a short downtime is unavoidable during the upgrade process. However, if you have set up a master and a shadow instance, you can perform the upgrade without downtime by executing the following procedure: 1. Shut down the shadow instance. SAP BTP Connectivity Connectivity PUBLIC 567
- 568. 2. Perform the upgrade on the shadow instance. (Follow the relevant procedure below.) 3. Restart the shadow instance and connect to the master instance. 4. Perform a Switch Roles operation by pressing the corresponding button in the master administration UI. The master instance has now changed into a shadow instance. 5. Shut down the new shadow instance and perform the upgrade procedure on it as well. Caution When upgrading from a version prior to 2.13, reset the high availability settings in both instances after upgrading the first instance. Re-establish the master-shadow connection directly after the upgrade of the second one. 6. Restart the new shadow instance, connect it to the new master, and then perform again the Switch Roles operation. Result: Both instances have now been upgraded without connectivity downtime and without configuration loss. For more information, see Install a Failover Instance for High Availability [page 508]. Microsoft Windows OS 1. Uninstall the Cloud Connector as described in Uninstallation [page 570] and make sure to retain the existing configuration. 2. Reinstall the Cloud Connector within the same directory. For more information, see Installation on Microsoft Windows OS [page 292]. 3. Before accessing the administration UI, clear your browser cache to avoid any unpredictable behavior due to the upgraded UI. Linux OS 1. Execute the following command: : rpm -U com.sap.scc-ui-<version>.rpm Note Daemon extensions (as of Cloud Connector version 2.12.3) All extensions to the daemon provided via scc_daemon_extension.sh mechanism will survive a version update. An upgrade to version 2.12.3 will already consider an existing file, even though previous versions were not supporting that feature. 2. Before accessing the administration UI, clear your browser cache to avoid any unpredictable behavior due to the upgraded UI. 568 PUBLIC SAP BTP Connectivity Connectivity
- 569. 1.2.6 Update the Java VM How to update the Java VM used by the Cloud Connector. Sometimes you must update the Java VM used by the Cloud Connector, for example, because of expired SSL certificates contained in the JVM, bug fixes, deprecated JVM versions, and so on. ● If you make a replacement in the same directory, shut down the Cloud Connector, upgrade the JVM, and restart the Cloud Connector when you are done. ● If you change the installation directory of the JVM, follow the steps below for your operating system. Make sure that the JVM has been installed successfully. Note A Java Runtime Environment (JRE) is not sufficient. You must use a JDK or SAP JVM. Microsoft Windows OS 1. Make sure that the current user has administrative privileges. 2. Shutdown the Cloud Connector (for example, by stopping the corresponding Windows service or by double-clicking the Stop SAP Cloud Connector shortcut). 3. Open the registry editor (regedit32) and locate the following registry entry: HKEY_LOCAL_MACHINE SOFTWARESAPCloud Connector. 4. Change the value JavaHome to reflect the installation directory of the new Java VM. Note The bin subdirectory must not be part of the JavaHome value. If the JavaHome value does not yet exist, create it here with a "String Value" (REG_SZ) and specify the full path of the Java installation directory, for example: C:Program Filessapjvm. 5. Close the registry editor and restart the Cloud Connector. Linux OS 1. Open a shell as root user. 2. In this shell, set the environment variable JAVA_HOME, pointing to the installation directory of the new Java VM, for example, in tcsh: setenv JAVA_HOME /opt/sap/sapjvm 3. Execute the command System V init distributions: service scc_daemon stop SAP BTP Connectivity Connectivity PUBLIC 569
- 570. systemd distributions: systemctl stop scc_daemon 4. Execute the command System V init distributions: /opt/sap/scc/daemon.sh reinstall systemd distributions: /opt/sap/scc/daemon.sh reinstallSystemd 5. Execute the command System V init distributions: service scc_daemon start systemd distributions: systemctl start scc_daemon Both Operating Systems After executing the above steps, the Cloud Connector should be running again and should have picked up the new Java version during startup. You can verify this by logging in to the Cloud Connector with your favorite browser, opening the About dialogue and checking that the field <Java Details> shows the version number and build date of the new Java VM. After you verified that the new JVM is indeed used by the Cloud Connector, delete or uninstall the old JVM. 1.2.7 Uninstallation Uninstall an installer version or portable version of the Cloud Connector. ● If you have installed an installer variant of the Cloud Connector, follow the steps for your operating system to uninstall the Cloud Connector. ● To uninstall a developer version, proceed as described in section Portable Variants. Microsoft Windows OS 1. In the Windows software administration tool, search for Cloud Connector (formerly named SAP HANA cloud connector 2.x). 2. Select the entry and follow the appropriate steps to uninstall it. 3. When you are uninstalling in the context of an upgrade, make sure to retain the configuration files. Linux OS To uninstall Cloud Connector 2.x, execute the following command: rpm -e com.sap.scc-ui 570 PUBLIC SAP BTP Connectivity Connectivity
- 571. Caution This command also removes the configuration files. Mac OS X There is no installer variant for Mac OS X, only a portable one. Portable Variants (Microsoft Windows OS, Linux OS, Mac OS X) If you have installed a portable version (zip or tgz archive) of the Cloud Connector, simply remove the directory in which you have extracted the Cloud Connector archive. Related Information Installation [page 273] 1.2.8 Frequently Asked Questions Answers to the most common questions about the Cloud Connector. Technical Issues Does the Cloud Connector send data from on-premise systems to SAP BTP or the other way around? The connection is opened from the on-premise system to the cloud, but is then used in the other direction. An on-premise system is, in contrast to a cloud system, normally located behind a restrictive firewall and its services aren’t accessible thru the Internet. This concept follows a widely used pattern often referred to as reverse invoke proxy. Is the connection between the SAP BTP and the Cloud Connector encrypted? Yes, by default, TLS encryption is used for the tunnel between SAP BTP and the Cloud Connector. SAP BTP Connectivity Connectivity PUBLIC 571
- 572. If used properly, TLS is a highly secure protocol. It is the industry standard for encrypted communication and also, for example, as a secure channel in HTTPS. Keep your Cloud Connector installation updated and we will make sure that no weak or deprecated ciphers are used for TLS. Can I use a TLS-terminating firewall between Cloud Connector and SAP BTP? This is not possible. Basically, this is a desired man-in-the-middle attack, which does not allow the Cloud Connector to establish a mutual trust to the SAP BTP side. What is the oldest version of SAP Business Suite that's compatible with the Cloud Connector? The Cloud Connector can connect an SAP Business Suite system version 4.6C and newer. Which JRE versions are supported to run the Cloud Connector? Supported JRE Version 6 7 8 Cloud Connector Ver sion < 2.7.2 Yes Yes No = 2.7.2 Yes Yes Yes >= 2.8 No Yes Yes >=2.12.3 No No Yes Restriction Support for Java 7 has been discontinued. For more information, see Prerequisites [page 276]. Tip We recommend that you always use the latest supported JRE version. Caution Version 2.8 and later of theCloud Connector may have problems with ciphers in Google Chrome, if you use the JVM 7. For more information read this SCN Article . Which configuration in the SAP BTP destinations do I need to handle the user management access to the Cloud User Store of the Cloud Connector? See Configure an On-Premise User Store [page 480]. 572 PUBLIC SAP BTP Connectivity Connectivity
- 573. Is the Cloud Connector sufficient to connect the SAP BTP to an SAP ABAP back end or is SAP BTP Integration needed? It depends on the scenario: For pure point-to-point connectivity to call on-premise functionality like BAPIs, RFCs, OData services, and so on, that are exposed via on-premise systems, the Cloud Connector might suffice. However, if you require advanced functionality, for example, n-to-n connectivity as an integration hub, SAP BTP Integration – Process Integration is a more suitable solution. SAP BTP Integration can use the Cloud Connector as a communication channel. How much bandwidth does the Cloud Connector consume? The amount of bandwidth depends greatly on the application that is using the Cloud Connector tunnel. If the tunnel isn’t currently used, but still connected, a few bytes per minute is used simply to keep the connection alive. What happens to a response if there's a connection failure while a request is being processed? The response is lost. The Cloud Connector only provides tunneling, it does not store and forward data when there are network issues. Where should I install the Cloud Connector? For productive instances, we recommend installing the Cloud Connector on a single purpose machine. This is relevant for Security [page 556]. For more details on which network zones to choose for the Cloud Connector setup, see Network Zones [page 285]. How many servers do I need to deploy the Cloud Connector? We recommend that you use at least three servers, with the following purposes: ● Development ● Production master ● Production shadow Note Do not run the production master and the production shadow as VMs inside the same physical machine. Doing so removes the redundancy, which is needed to guarantee high availability. A QA (Quality Assurance) instance is a useful extension. For disaster recovery, you will also need two additional instances; another master instance, and another shadow instance. What are the hardware requirements to deploy the Cloud Connector? See: Prerequisites [page 274]. SAP BTP Connectivity Connectivity PUBLIC 573
- 574. Can I send push messages from an on-premise system to the SAP BTP through the Cloud Connector? No, this is not supported by the Cloud Connector. Is NTLM supported for authorization against the proxy server? No, the Cloud Connector currently supports only basic authentication. What operating systems are supported by the Cloud Connector? See Prerequisites [page 274]. What processor architectures are supported by the Cloud Connector? We currently support 64-bit operating systems running only on an x86-64 processor (also known as x64, x86_64 or AMD64). See: Prerequisites [page 274]. Can I use the Cloud Connector without an ABAP back end? Yes, you should be able to connect almost any system that supports the HTTP Protocol, to the SAP BTP, for example, Apache HTTP Server, Apache Tomcat, Microsoft IIS, or Nginx. Can I authenticate with client certificates configured in SAP BTP destinations at HTTP services that are exposed via the Cloud Connector? No, this is not possible. For client certificate authentication, an end-2-end TLS communication is required. This is not the case, because the Cloud Connector needs to inspect incoming requests in order to perform access control checks. Administration Are there Audit Logs for changes in the Cloud Connector? Yes, find more details here: Manage Audit Logs [page 545]. Is it possible to split authorization? 574 PUBLIC SAP BTP Connectivity Connectivity
- 575. No, currently there is only one role that allows complete administration of the Cloud Connector. Can I configure multiple administrative subaccounts? Yes, to enable this, you must configure an LDAP server. See: Use LDAP for Authentication [page 503]. How can I reset the Cloud Connector's administrator password when not using LDAP for authentication? Visit https:/ /tools.hana.ondemand.com/#cloud to download the portable version of the Cloud Connector. Extract the users.xml file in the config directory to the config directory of your Cloud Connector installation, then restart the Cloud Connector. This resets the password and user name to their default values. You can manually edit the file; however, we strongly recommend that you use the users.xml file. How do I create a backup of the Cloud Connector configuration? Package the following three folders, located in your Cloud Connector installation directory, into an archive file: ● config ● config_master ● scc_config These folders contain all the relevant configuration information. As the layout of the configuration files may change between versions, we recommend that you don't restore a configuration backup of a Cloud Connector 2.x installation into a 2.y installation. Can I create a backup of the complete installation? Yes, you can create an archive file of the installation directory to create a full backup. Before you restore from a backup, note the following: ● If you restore the backup on a different host, the UI certificate will be invalidated. ● Before you restore the backup, you should perform a “normal” installation and then replace the files. This registers the Cloud Connector at your operating systems package manager. Why do I need a user ID during configuration? This user opens the tunnel and generates the certificates that are used for mutual trust later on. The user is not part of the certificate that identifies the Cloud Connector. In both the Cloud Connector UI and in the SAP BTP cockpit, this user ID appears as the one who performed the initial configuration (even though the user may have left the company). SAP BTP Connectivity Connectivity PUBLIC 575
- 576. What happens to a Cloud Connector connection if the user who created the tunnel leaves the company? This does not affect the tunnel, even if you restart the Cloud Connector. What do changes in major or minor version numbers mean? The semantics of Cloud Connector versions are explained in detail here . For how long does SAP continue to support older Cloud Connector versions? Each Cloud Connector version is supported for 12 months, which means the cloud side infrastructure is guaranteed to stay compatible with those versions. After that time frame, compatibility is no longer guaranteed and interoperability could be dropped. Furthermore, after an additional 3 month, the next feature release published after that period will no longer support an upgrade from the deprecated version as a starting release. What is the difference between “subaccount name” and “subaccount user”? SAP BTP customers can purchase subaccounts and deploy applications into these subaccounts. Additionally, there are users, who have a password and can log in to the cockpit and manage all subaccounts they have permission for. ● A single subaccount can be managed by multiple users, for example, your company may have several administrators. ● A single user can manage multiple subaccounts, for example, if you have multiple applications and want them (for isolation reasons) to be split over multiple subaccounts. Find your account name by taking the following steps: 1. Open the SAP BTP cockpit. 2. Log in with your subaccount user. 3. You’ll see the subaccount name in the top left section of the screen. For trial users, the account name is typically your user name, followed by the suffix “trial”: 576 PUBLIC SAP BTP Connectivity Connectivity
- 577. Features Does the Cloud Connector work with the SAP BTP Cloud Foundry environment? As of version 2.10, the Cloud Connector can establish a connection to regions based on the SAP BTP Cloud Foundry environment. Newer regions, however, require a Cloud Connector version 2.11 or higher. Does the Cloud Connector work with SAP S/4HANA Cloud? As of version 2.10, the Cloud Connector offers a Service Channel to S/4HANA Cloud instances, given that they are associated with the respective SAP BTP subaccount. For more information, see Using Service Channels [page 482]. Also supported as of version 2.10: S/4HANA Cloud communication scenarios invoking HTTP services or remote-enabled function modules (RFMs) in on-premise ABAP systems. Does the Cloud Connector work with the SAP BTP ABAP environment? As of version 2.11, the Cloud Connector supports communication from and to the SAP BTP ABAP environment, when using the Neo Connectivity service. Using the Cloud Foundry Connectivity service requires a Cloud Connector version 2.12.3 or higher. How do I bind multiple Cloud Connectors to one SAP BTP subaccount? SAP BTP Connectivity Connectivity PUBLIC 577
- 578. As of version 2.9, you can connect multiple Cloud Connectors to a single subaccount. This lets you assign multiple separate corporate network segments. Those Cloud Connectors are distinguishable based on the location ID, which you must provide to the destination configuration on the cloud side. Note During an upgrade, location IDs provided in earlier versions of the Cloud Connector are dropped to ensure that running scenarios are not disturbed. Is WebSocket communication through the Cloud Connector supported? Yes, this is possible as of version 2.12. Is there any plan to add traffic management functionality in Cloud Connector? No, this functionality is not currently planned. Can I use the Cloud Connector for any protocol? As of version 2.10, this is possible using the TCP channel of the Cloud Connector, if the client supports a SOCKS5 proxy to establish the connection. However, only the HTTP and RFC protocols currently provide an additional level of access control by checking invoked resources. You can also use the Cloud Connector as a JDBC or ODBC proxy to access the HANA DB instance of your SAP BTP subaccount (service channel). This is sometimes called the “HANA Protocol”. Can I check the communication of the service channel? No, the audit log monitors access only from SAP BTP to on-premise systems. Troubleshooting How do I fix the “Could not open Service Manager” error message? You are probably seeing this error message due to missing administrator privileges. Right-click the cloud connector shortcut and select Run as administrator. If you don’t have administrator privileges on your machine you can use the portable variant of the Cloud Connector. Note The portable variants of the Cloud Connector are meant for nonproductive scenarios only. 578 PUBLIC SAP BTP Connectivity Connectivity
- 579. How do I set JAVA_HOME and PATH correctly? For the portable versions, JAVA_HOME must point to the installation directory of your JRE, while PATH must contain the bin folder inside the installation directory of your JRE. The installer versions automatically detect JVMs in these locations, as well as in other places. When I try to open the Cloud Connector UI, Google Chrome opens a Save as dialog, Firefox displays some cryptic signs, and Internet Explorer shows a blank page, how do I fix this? This happens when you try to access the Cloud Connector over HTTP instead of HTTPS. HTTP is the default protocol for most browsers. Adding “https:/ /” to the beginning of your URL should fix the problem. For localhost, you can use https:// localhost:8443/. 1.3 Connectivity via Reverse Proxy An alternative approach compared to the SSL VPN solution that is provided by the Cloud Connector is to expose on-premise services and applications via a reverse proxy to the Internet. This method typically uses a reverse proxy setup in a customer's "demilitarized zone" (DMZ) subnetwork. The reverse proxy setup does the following: ● Acts as a mediator between SAP BTP and the on-premise services ● Provides the services of an Application Delivery Controller (ADC) to, for example, encrypt, filter, route, or check inbound traffic The figure below shows the minimal overall network topology of this approach. On-premise services that are accessible via a reverse proxy are callable from SAP BTP like other HTTP services available on the Internet. When you use destinations to call those services, make sure the configuration of the ProxyType parameter is set to Internet. SAP BTP Connectivity Connectivity PUBLIC 579
- 580. Advantages Depending on your scenario, you may benefit from the reverse proxy: ● Network infrastructure (such as a reverse proxy and ADC services): since it already exists in your network landscape, you can reuse it to connect to SAP BTP. There's no need to set up and operate new components on your (customer) side. ● A reverse proxy is independent of the cloud solution you are using. ● It acts as single entry point to your corporate network. Disadvantages ● The reverse proxy approach leaves exposed services generally accessible via the Internet. This makes them vulnerable to attacks from anywhere in the world. In particular, Denial-of-Service attacks are possible and difficult to protect against. To prevent attacks of this type and others, you must implement the highest security in the DMZ and reverse proxy. For the productive deployment of a hybrid cloud/on- premise application, this approach usually requires intense involvement of the customer's IT department and a longer period of implementation. ● If the reverse proxy allows filtering, or restricts accepted source IP addresses, you can set only one IP address to be used for all SAP BTP outbound communications. A reverse proxy does not exclusively restrict the access to cloud applications belonging to a customer, although it does filter any callers that are not running on the cloud. Basically, any application running on the cloud would pass this filter. ● The SAP-proprietary RFC protocol is not supported, so a cloud application cannot directly call an on- premise ABAP system without having application proxies on top of ABAP. ● No easy support of principal propagation authentication, which lets you forward the cloud user identity to on-premise systems. ● You cannot implement projects close to your line of business (LoB). Note Using the Cloud Connector mitigates all of these issues. As it establishes the SSL VPN tunnel to SAP BTP using a reverse invoke approach, there is no need to configure the DMZ or external firewall of a customer network for inbound traffic. Attacks from the Internet are not possible. With its simple setup and fine- grained access control of exposed systems and resources, the Cloud Connector allows a high level of security and fast productive implementation of hybrid applications. It also supports multiple application protocols, such as HTTP and RFC. 580 PUBLIC SAP BTP Connectivity Connectivity
- 581. 1.4 Connectivity Support Support information for SAP BTP Connectivity and the Cloud Connector. Troubleshooting Locate the problem or error you have encountered and follow the recommended steps: ● Frequently Asked Questions [page 571] (Cloud Connector) ● Operations [page 502] (Cloud Connector) ● Cloud Connectivity: Guided Answers ● Getting Support (SAP Support Portal, SAP BTP community) SAP Support Information If you cannot find a solution to your issue, collect and provide the following specific, issue-relevant information to SAP Support: ● The Java EE code that throws an error (if any) ● A screenshot of the error message for the failed operation or the error message from the HttpResponse body ● Access credentials for your cloud or on-premise location You can submit this information by creating a customer ticket in the SAP CSS system using the following components: Component Purpose Connectivity Service BC-CP-CON For cloud-side issues with cloud to on-premise connectivity, where: ● The environment is unknown or ● The issue is not related to a specific environment BC-CP-CON-CF For cloud-side issues with cloud to on-premise connectivity in the SAP BTP Cloud Foundry environment. BC-CP-CON-S4HC For cloud-side issues with cloud to on-premise connectivity in an S/4HANA Cloud system. BC-CP-CON-ABAP For cloud-side issues with cloud to on-premise connectivity in the SAP BTP ABAP environment. BC-NEO-CON For cloud-side issues with cloud to on-premise connectivity in the SAP BTP Neo environment. SAP BTP Connectivity Connectivity PUBLIC 581
- 582. Component Purpose Destinations BC-CP-DEST For issues with destination configurations, where: ● The environment is unknown or ● The issue is not related to a specific environment BC-CP-DEST-CF For general issues with the Destination service in the SAP BTP Cloud Foundry environment, like: ● REST API ● Instance creation, etc. BC-CP-DEST-CF-CLIBS For client library issues with the Destination service in the SAP BTP Cloud Foundry environment. BC-CP-DEST-CF-TOOLS For issues with the management of destination configura- tions via tools like the SAP BTP cockpit (Cloud Foundry en vironment). BC-CP-DEST-NEO For issues with destination configurations or: ● Management tools ● Client libraries, etc. related to destinations in the SAP BTP Neo environment. Cloud Connector BC-MID-SCC For connectivity issues related to installing and configuring the Cloud Connector, configuring tunnels, connections, and so on. If you experience a more serious issue that cannot be resolved using only traces and logs, SAP Support may request access to the Cloud Connector. Follow the instructions in these SAP notes: ● To provide access to the Administration UI via a browser, see 592085 . ● To provide SSH access to the operating system of the Linux machine on which the connector is installed, see 1275351 . Related Information Release and Maintenance Strategy [page 582] 1.4.1 Release and Maintenance Strategy Find information about SAP BTP Connectivity releases, versioning and upgrades. 582 PUBLIC SAP BTP Connectivity Connectivity
- 583. Release Cycles Updates of the Connectivity service are published as required, within the regular, bi-weekly SAP BTP release cycle. New releases of the Cloud Connector are published when new features or important bug fixes are delivered, available on the Cloud Tools page. Cloud Connector Versions Cloud Connector versions follow the <major>.<minor>.<micro> versioning schema. The Cloud Connector stays fully compatible within a major version. Within a minor version, the Cloud Connector will stay with the same feature set. Higher minor versions usually support additional features compared to lower minor versions. Micro versions generally consist of patches to a <master>.<minor> version to deliver bug fixes. For each supported major version of the Cloud Connector, only one <major>.<minor>.<micro> version will be provided and supported on the Cloud Tools page. This means that users must upgrade their existing Cloud Connectors to get a patch for a bug or to make use of new features. Cloud Connector Upgrade New versions of the Cloud Connector are announced in the Release Notes of SAP BTP. We recommend that Cloud Connector administrators regularly check the release notes for Cloud Connector updates. New versions of the Cloud Connector can be applied by using the Cloud Connector upgrade capabilities. For more information, see Upgrade [page 567]. Note We recommend that you first apply upgrades in a test landscape to validate that the running applications are working. There are no manual user actions required in the Cloud Connector when the SAP BTP is updated. SAP BTP Connectivity Connectivity PUBLIC 583
- 584. Important Disclaimers and Legal Information Hyperlinks Some links are classified by an icon and/or a mouseover text. These links provide additional information. About the icons: ● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements with SAP) to this: ● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information. ● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct. ● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information. Videos Hosted on External Platforms Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within the control or responsibility of SAP. Beta and Other Experimental Features Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up. The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP. Example Code Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct. Gender-Related Language We try not to use gender-specific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders. 584 PUBLIC SAP BTP Connectivity Important Disclaimers and Legal Information
- 585. SAP BTP Connectivity Important Disclaimers and Legal Information PUBLIC 585
- 586. www.sap.com/contactsap © 2021 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies. Please see https:/ /www.sap.com/about/legal/trademark.html for additional trademark information and notices. THE BEST RUN