Skip to Content

*********** Updates ************

Last update on 09.01.2017

See details at the end of the blog

*******************************

 

In the first part of the blog, I’ve described how to establish a secure tunnel between the SAP Cloud Platform Trial (Cloud Foundry environment) and the Cloud Connector. In addition to that we have configured an Access Control so that we can now access and consume securely data from an on-premise system.

In the second part I will explain how to configure SAP Cloud Platform Connectivity so that a web application can consume the odata service of the existing on-premise system.

Note: many configuration steps of this blog will be done via the SAP Cloud Platform cockpit. Be aware that you can do exactly the same thing via the Command Line Interface of Cloud Foundry. More details about the CLI can be found here.

 

First let’s take a moment to see how it works for basic authentication:

SAP-CP-Connectivity-CF.png

1. User calls the webApp through the AppRouter, which provides a central point of entry to business applications.

2. The request is redirected to XSUAA and the user needs to login. Then a JWT1 (JSON Web Token) is created and sent to AppRouter. JWT1 is then cached by the AppRouter.

3. AppRouter forwards the request to the relevant Web-app URL which is defined as destination, it also passes the JWT1 token with credentials.

4a. The WebApp requests a JWT2 to access the destination instance. JWT2 should be cached for better performance.

4b. In parallel the WebApp requests a JWT3 to access the connectivity instance. JWT3 should be cached for better performance.

5. The WebApp requests destination configuration by sending JWT2.

6. The WebApp sends request to the connectivity instance with JWT3 and the Authorization header.

7. SAP Cloud Platform Connectivity forwards request to the Cloud Connector.

8. Cloud Connector sends request to the on-premise system.

Now that you know how it works, let see what are the steps needed to configure such a scenario:

  1. Creation of the destination and the destination instance
  2. Creation of the connectivity instance
  3. Creation of the XSUAA instance
  4. Configuration and deployment of the AppRouter
  5. Configuration and deployment of the WebApp

Then let’s do it together and start with the destination…

 

1. Creation of the destination and the destination instance

The destination service, which is available (beta) since October 2017, allows you to store securely settings such as your credentials, the protocol, the URL of the on-premise system, and the proxy type. Destinations are defined on the Subaccount level and you can integrate them in your application on the space level. You can find more details in the official documentation: https://help.sap.com/viewer/cca91383641e40ffbe03bdc78f00f681/Cloud/en-US/7e306250e08340f89d6c103e28840f30.html

 

To create a destination, go the SAP Cloud Platform cockpit and navigate to your Subaccount. Then go to “Destinations (beta)” under “Connectivity” and create a new destination.

Configure now your destination so that you can consume the data from the virtual host previously defined in the Cloud Connector.

Note: if you are using the app available in the sharepoint, be sure to use the same name of the destination or change it in the webApp directly.

 

Now that we have the destination defined, we can create a destination instance in the space. Go to the section “Services Marketplace” under the “Services” tab and click on the Destination tile.

Then click on the “Instances” section and create a new instance.

Keep “lite” as plan and click “Next”. Then skip the next 2 wizard options (Parameters, Application assignment) and add an instance name (e.g. “destination-demo-lite”). There are different ways to bind the application to the destination service. We will do it later on by adding the name of the destination instance in the manifest of the application. During the deployment of the app, the binding will be then added automatically.

 

2. Creation of the connectivity instance

SAP Cloud Platform Connectivity provides a standard HTTP proxy for on-premise connectivity to be accessible by any application. Proxy host and port are available in the credentials of the bound connectivity service via the environment variable “VCAP_SERVICES”. More details on how to interpret VCAP_SERVICES can  found in the official CF documentation.

In order to consume the data coming from the on-premise in the application via the HTTP proxy, we need to create an SAP Cloud Platform Connectivity instance and bind it to the application. When a binding is created the application gets connectivity credentials in its environment variables. More details about it here.

Ok, let’s create an connectivity instance as we did for the destination instance! Go to the “Services Marketplace” under the “Services” tab and click on the Connectivity tile.

Then click on the “Instances” section and create a new instance.

Keep “lite” as plan and click “Next”. Then skip the next 2 wizard options (Parameters, Application assignment) and add an instance name (e.g. “connectivity-demo-lite”). Like the others instances, the binding will be done by adding the instance in the manifest of the application later on.

 

 

3. Creation of the Authorization & Trust Management instance (aka. XSUAA)

This central identity management service for the Cloud Foundry environment manages application authorizations and the trust to identity providers.

By calling the application, the user will be redirected to the XSUAA and will be prompt to give his credentials. It will then achieve certain checks like verifying the OAuth client, client’s scopes, user’s scopes (Scopes are permissions to access one or more resources). Assuming everything is fine, the user will be authenticated and the XSUAA will redirect the browser to the application.

In a second step the application will take the client Id and the client secret and will talk directly with the XSUAA to get an access token. Then the application will sent both tokens as HTTP header so that it can consume the backend system via the SAP Cloud Platform Connectivity.

The next step is then to create an instance for the XSUAA. We open the SAP Cloud Platform cockpit and go to the “Services Marketplace” under the “Services” tab and click on the XSUAA tile.

Then click on the “Instances” section and create a new instance.

In the wizard we keep “application” as service plan and click “Next”. Then we add the following parameters in the editor and then click on “Next”.

{
        "xsappname" : "connectivity-app-demo",
        "tenant-mode": "dedicated"
}

In the last step of the wizard, we can add an instance name (e.g. “xsuaa-demo”). The same name will be added in the manifest of the application later on.

Note: As mentioned before, we will bind the instance at the end, once we have deployed the application.

4. Configuration and deployment of the application router

For this demo I have preconfigured a standard application router. Is it really needed? No but it makes my life easier and it’s a kind of best practise in the Cloud Foundry world. So in our scenario the application router is the component that acts as our oAuth Client. Concretely that means that by calling the application router in the browser, the end-user will be redirected to the XSUAA in order to login.

Note: probably you want to try it by yourself and you need maybe a standard application router. No problem, SAP provides an NPM registry under the following URL: https://npm.sap.com/

Use the following command to configure the NPM registry for your user

npm config set @sap:registry https://npm.sap.com/

Use the install command to download the approuter and its dependencies

npm install @sap/approuter

Now let configure the manifest file of the application router before we deploy it.

  1. Name of the application router
  2. Hostname of the application router (be aware that it should be unique, then you can for example add you trial-user to the name. In my case it would be “approuter-demo-p193274639trial”)
  3. URL of the web application (based on the app name that will be defined in the application’s manifest). Don’t forget to update the url with your hostname (appname+trial-user-name)
  4. Name of the XSUAA instance (the name has been previously defined in the SAP Cloud Platform cockpit by creating the XSUAA instance)

Here is the code of our application router manifest:

---
applications:

- name: approuter-demo
  host: approuter-demo-p193274639trial
  buildpack: nodejs_buildpack
  memory: 128M
  path: ./
  env:
    NODE_TLS_REJECT_UNAUTHORIZED: 0
    destinations: >
      [

           {"name":"dest-to-app", "url" :"https://connectivity-app-demo-p193274639trial.cfapps.eu10.hana.ondemand.com", "forwardAuthToken": true },
           {"name":"ui5", "url":"https://sapui5.hana.ondemand.com/1.42.6/resources/"}
      ]
  services:
    - xsuaa-demo

In order to deploy the application router, we go to the “Applications” section in the SAP Cloud Platform cockpit. There we can click on “Deploy Application” and add the archive file and the manifest.

As we have defined the XSUAA service in the manifest, the binding will be done automatically. You can verifying it by clicking on the application router name and then on the “Service Bindings” section.

 

5. Configuration and deployment of the web application

The web application consists of 2 groups:

  1. JAVA logic to handle the JWT token and create a request via the HTTP Proxy of the SAP Cloud Platform Connectivity
  2. UI5 Frontend to display the result of the request in a table (Products and prices)

 

The manifest file of the application should also be configured:

  1. Name of the application
  2. Hostname of the application(again here the hostname should be unique. So add you trial-user to the name. In my case it would be “connectivity-app-demo-p193274639trial”)
  3. Name of the XSUAA instance defined previously
  4. Name of the Connectivity instance defined previously
  5. Name of the Destination instance defined previously

Here is the code of the manifest:

---
applications:

- name: connectivity-app-demo
  host: connectivity-app-demo-p193274639trial
  buildpack: java_buildpack
  memory: 512M
  instances: 1
  path: target/connectivity.war
  env:
        # Accept any OAuth client of any identity zone 
        SAP_JWT_TRUST_ACL: '[{"clientid":"*","identityzone":"*"}]'
       # Useful on a dev environment
       SKIP_SSL_VALIDATION: false
       xsuaa_connectivity_instance_name: "xsuaa-demo"
       xsuaa_destination_instance_name: "xsuaa-demo"
      JAVA_OPTS: '-Xss349k'
      services:
      - xsuaa-demo
      - connectivity-lite
      - destination-lite

Note: by changing the name of the application, a change needs to be done in the file application.properties. You can find it here: /src/main/webapp/security/xs-security.json.

# parameters of the app
xs.appname=connectivity-app-demo

Before deploying the web application, let take time to see where the magic happens. The most important file is the connectivity servlet, which is responsible to propagate the user JWT token via headers.

// get value of  "onpremise_proxy_host" and "onpremise_proxy_port"
 ...

// set up the on-premise HTTP Proxy
URL url = new URL("http://virtualhost:1234");
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(connProxyHost, connProxyPort));
urlConnection = (HttpURLConnection) url.openConnection(proxy);
 
// insert the necessary headers in the request
urlConnection.setRequestProperty("SAP-Connectivity-Authentication", "Bearer " + jwtToken1);
urlConnection.setRequestProperty("Proxy-Authorization", "Bearer " + jwtToken2);

// Optionally, if configured, add the SCC location ID
urlConnection.setRequestProperty("SAP-Connectivity-SCC-Location_ID", "New York");

For more details, you can can download the full code at the bottom of the page.

In order to deploy the web application, we go again to the “Applications” section in the SAP Cloud Platform cockpit. And again we click on “Deploy Application” and add the archive file and the manifest.

To verify that the manifest has taken care of the binding, we can check the “Service Bindings” section of the web application if the services have been added.

That’s all! Now we can call the application in the browser. In order to get the URL, we go to the “applications” tab and click on the “approuter-demo”. Here we can find the URL of the application router.

The route to the web application has been configured in the /approuter/xs-app.json file of the application router,  so that we need to add “/app/” at the end of the URL.

{
        "welcomeFile": "index.html",
        "routes": [{
                "source": "/app",
                "target": "/",
                "destination": "dest-to-app"
                  }
        ]
}

Click on the link “Go to App” to called the URL: https://approuter-demo.cfapps.eu10.hana.ondemand.com/app/ 

Note: by calling this URL, the destination “dest-to-app” defined in the manifest of the appRouter” will be called. Here again a copy of the manifest.

---
...
    destinations: >
      [

           {"name":"dest-to-app", "url" :"https://connectivity-app-demo-p193274639trial.cfapps.eu10.hana.ondemand.com", "forwardAuthToken": true },
           {"name":"ui5", "url":"https://sapui5.hana.ondemand.com/1.42.6/resources/"}
      ]
 ...

 

By opening this URL in the browser, the user will be redirected to the XSUAA in order to login.

After the login, the XSUAA redirects the user to the web application, which called the odata services of the on-premise system via the Cloud Connector. Here is then the result.

You want to try it by your own or you want to see the code in details. No problem, you can download the code here. Some improvements need to be done for sure (for example the way to save the backend credentials 😉 So at least I hope it helps you to better understand how to use the the SAP Cloud Platform Connectivity in the Cloud Foundry environment.

In the next part of this blog serie, I will explain how to replace basic authentication with principal propagation.

Stay tuned and send me your feedback.

Matthieu

 

Here again the Repository with the code:

https://sap-my.sharepoint.com/personal/matthieu_pelatan_sap_com/_layouts/15/guestaccess.aspx?folderid=09e2d3ae2fae844e19f134b979e4bb14d&authkey=AUH9e1uSywTRMNej9sklypk&expiration=2018-04-03T22%3A00%3A00.000Z&e=cc64b2cb8e184c96987d48f5805b1655

 

*********** Updates ************

10.11.2017: Due to new buildpack, the manifest file of the web application has been updated.

27.11.2017: Extract the SAPUI5 Library of the webApp + Adding a destination for SAPUI5 in the manifest of AppRouter.

15.12.2017: Adding the steps for using the SAP Cloud Platform Destination Service.

09.01.2017: Small improvements in the blog for a better understanding, for example adding the p-user to the hostname in the manifest.

**********************************

 

To report this post you need to login first.

30 Comments

You must be Logged on to comment or reply to a post.

  1. Gennady Maly

    Question about “you can can download the full code at the bottom of the page”. What link on this page could be used exactly?

    thanks and regards,

    Gennady

     

    (0) 
    1. Matthieu Pelatan Post author

      Hi Gennady,

      you can find the link at the bottom of the page:

      You want to try it by your own or you want to see the code in details. No problem, you can download the code here

      Let me know if you have problem with the link.

      Best,

      Matthieu

      (0) 
  2. Serban Petrescu

    Hi Matthieu,

    I am not able to find any documentation on the Principal Propagation for CF. Based on the Cloud Connector itself, I guess it should be possible (I see that you added support for the JWT-based SSO by extracting the principal from the token).

    Could you indicate where we could find some documentation on this feature? Also, is this feature “official” or still “beta” (i.e. work-in-progress)?

    Thanks,
    Serban

    (0) 
    1. Matthieu Pelatan Post author

      Hi Serban,

      indeed Principal Propagation works already in the Cloud Foundry environment. We working on the 3rd part of the blog, which will describe it in details. Stay tuned…

      Matthieu

      (2) 
  3. Petr Shumilov

    Hi Matthieu,

    I am developing node.js application in the Cloud Foundry environment and I need to able connectivity with on-promise OData service (through SAP Gateway). I followed your instructions but when I started implement proxy connection one thing made me confused. I did not understand how determine jwtToken1. Where and how i can get it? I read your java code and this doc but still did not understand. I hope you can help me))

    Thank you in advance,
    intern Petr

    (1) 
    1. Gennady Maly

       

      Petr, as far as I can see, a jwt determination example code is in the code provided my Matthieu “at the bottom of the page” (at the end of his blog) in the ConnectivityServlet.java file,

      getClientOAuthToken() function

       

      (0) 
  4. Simen Huuse

    Hi Matthieu! Great blog!

    Do you have any info on when the connectivity services will become available for the US West (CA) Beta site?

     

    All the best,

    @simenhuuse

    (0) 
  5. Yangyang Chen

    Hi Matthieu,

     

    Thank you for this wonderful blog!

     

    We are wondering whether we can directly consume Connectivity service from UI level? If not, can we implement similar logic in NodeJS instead of Java code?

     

    Thanks in advance

     

    yangyang

    (1) 
  6. Bert Deterd

    Made a small npm package scc-connector which might be of help if you want to build a plain Node.js app for cloud foundry sap cloud platform with xsuaa and connectivity.

    (0) 
  7. Tobias Trapp

    Hi Matthieu,

    great and very helpful blog!

    One question concerning your code example:

    There’s a dependency to group “com.sap.xs2.security”, artifact “java-container-security”, which doesn’t seem to be public available. Are there any plans to move this into Maven Central or are there any alternatives?

    I’m doing something similar to your example but making use of Spring instead of the Servlet API and there I’m having trouble with the Spring Security configuration. I guess, that this is provided by the formerly mentioned artifact…

    Thanks,

    Tobi

    (0) 
  8. Sarthak Sharma

    Hi Matthieu,

     

    An execellent tutorial. It did help me in past. However, currently I’m working on a UI5 application on CF which needs to connect to another CF application through destinations. I understand the process to use destinations in CF is different than in Neo. There’re references for making a request through destination using JAVA, however, I couldn’t find any resources on how to do so in UI5 application. Can you please assist me with this? Or, do I’ve to create an MTA project, make the request through JAVA code and display the data in UI5 application? Any help will be much appireciated.

    Kind Regards,

    Sarthak

    (0) 
    1. Philipp Stehle

      Yes, you’ll need an application acting as a proxy here.
      It’s not necessary to write this application using Java, but it has to run in the cloud (not in the users browser).

      There are two (maybe more) solutions:

      1. A very simple application, which allows your UI5 application to fetch the connectivity details and the UI5 applications connects directly to your second CF application.
      2. A (quite more complex) application which fetches the connectivity details and executes the request on behalf of the UI5 application and redirects the result.

      While the first solution should be easier to implement and provide better performance, it is not usable if the CF application requires authentication using some kind of technical user (as those credentials would be exposed to the users browser).

      (1) 
      1. Liam Zhang

        Hi Philipp,

        As described in sample code, only ‘HTTP’ protocol supported here.

        // set up the on-premise HTTP Proxy

        URL url = new URL(“http://virtualhost:1234”);

         

        My question is, can we use ‘https’ protocol as virtual host principle?

        URL url = new URL(“https://virtualhost:1234″);

         

        (0) 
    2. Sarthak Sharma

      Thanks a lot Philipp Stehle and Liam Zhang for your suggestions. Yes, these are probable solutions, however, I found an easier and safer solution to this. Just add a destination in the env variable in the application manifest file which works similar to adding destinations in Neo environment. Moreover, you can use this destination in UI5 application the same way as in Neo environment. Here’s a sample code for reference:

      – name: cf-ui-app
      buildpack:nodejs_buildpack
      memory:128M
      instances:1
      env:
      destinations:>
      [
      {
      “name”:”dest”,
      “url”:”https://<app-url>.cfapps.eu10.hana.ondemand.com/”,
      “forwardAuthToken”:true
      }
      ]
      (0) 
  9. Parul Agrawal

     

    Hi Matthieu,

    I am done with the part 1 of this blog https://blogs.sap.com/2017/07/09/how-to-use-the-sap-cloud-platform-connectivity-and-the-cloud-connector-in-the-cloud-foundry-environment-part-1/

    In the part 2 of this blog, I am done with the step 1 : ‘Creation of the destination and the destination instance’.

    But when I following the step 2 for ‘Creation of the connectivity instance’ , I am not able to create the destination service either via SCP cloud foundry trial account or through the command prompt as well( CLI ).

    I am getting the below mentioned error :

    “Unable to create service instance. We are sorry, but we have encountered an internal error. If the problem persists, please create a support ticket.

    Service broker error: Org with guid [e3eb2f49-05ea-40a6-be7e-5f5e1b55ac57] is not registered in tenant-onboarding service. Instance creation not allowed.”

    Below is the screenshot for reference :

     

     

    Is there anything which I missed or something needs to maintained in cloud foundry trial account with respect to registration, configuration ?

    Would you please provide some insights on this ?

    Thanks you.

    Best Regards, Parul

    (0) 
  10. Ramesh Kumar

    Hi Matthieu,

    The Source code link given at the bottom of the page has expired. Can i request you to please restore the link ?

    Thanks,

    Ramesh

     

    (0) 
      1. Ramesh Kumar

        Hi Matthieu,

         

        I tried to connect my UI application using the reference from the source code given at end of the page. Below are the destination and manifest i am using. The app router works fine as well as the UI application works fine but the application is not able to get Destination from the cockpit and further doesn’t connect to the onPremise system. Is there anything missing?

         

        Manifest.yml file for connectivity app :

         


        applications:

        – name: connectivity-app-demo
        host: connectivity-app-demo-Masterdata
        buildpack: java_buildpack
        memory: 512M
        instances: 1
        path: target/connectivity-sample.war
        env:
        # Accept any OAuth client of any identity zone
        SAP_JWT_TRUST_ACL: ‘[{“clientid”:”*”,”identityzone”:”*”}]’
        # Useful on a dev environment
        SKIP_SSL_VALIDATION: false
        xsuaa_connectivity_instance_name: “xsuaa-demo”
        xsuaa_destination_instance_name: “xsuaa-demo”
        JAVA_OPTS: ‘-Xss349k’
        services:
        – xsuaa-demo
        – connectivity-demo-lite
        – destination-demo-lite

         

        neo-app.json route definition:

         

        {
        “path”: “/MASTERPROJECT”,
        “target”: {
        “type”: “destination”,
        “name”: “abapBackend1”,
        “entryPath”: “/sap/opu/odata/sap/CPD_MASTERPROJECT_OVERVIEW_SRV/”
        },
        “description”: “MASTERPROJECT”
        },

        approuter-manifest.yml file :

         


        applications:

        – name: connectvity-demo-approuter
        host: connectvity-demo-approuter
        buildpack: nodejs_buildpack
        memory: 128M
        path: ./
        env:
        NODE_TLS_REJECT_UNAUTHORIZED: 0
        destinations: >
        [
        {“name”:”dest-to-app”, “url” :”https://connectivity-app-demo-masterdata.cfapps.eu10.hana.ondemand.com”, “forwardAuthToken”: true },
        {“name”:”ui5″, “url”:”https://sapui5.hana.ondemand.com/1.46.6/resources/”}
        ]
        services:
        – xsuaa-demo

         

         

        (0) 
  11. Guilherme Dellagustin

    Hi Matthieu,

    Even though it may be obvious that JWT in this context means a JSON Web Token, I would suggest that in your first mention you change it to:

    “Then a JWT1 (JSON Web Token) is created and sent to AppRouter. JWT1 is then cached by the AppRouter.”

    Linking it to https://jwt.io/

    Good job keeping this blog, it is very helpful and easy to follow.

    (0) 

Leave a Reply