Consuming the Connectivity Service

Tasks

Task Type	Task
Operator and/or Developer	Overview
Operator and/or Developer	Prerequisites
Developer	Basic Steps Read Credentials from the Environment Variables Provide the Destination Information Set up the HTTP Proxy for On-Premise Connectivity
Operator and/or Developer	Additional Steps Authentication against the On-Premise System Specify a Cloud Connector Location ID Multitenancy in the Connectivity Service

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.

Back to Tasks

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 and Configuration.
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.
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.

Back to Tasks

Basic Steps

To consume the Connectivity service from your Cloud Foundry application, perform the following basic steps:

Back to Tasks

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");

This code stores a JSON object in the credentials variable. Additional parsing is required to extract the value for a specific key.

Back to Tasks

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).
The required authentication type for the on-premise system. See HTTP Destinations.
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.
(Optional) You can use a location Id. For more details, see section Specify a Cloud Connector Location ID.

We recommend that you use the Destination service (see Consuming the Destination Service) 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

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);

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.ClientCredentialsOAuth2AuthorizedClientProvider;
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;
        }
 
        @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());

Back to Tasks

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.

Back to Tasks

Specify a Cloud Connector Location ID

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

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