SAP Community - Serverless Computing

Event-driven architecture – now available for SAP ECC users

2020-07-01T10:30:19+02:00

Overview

Wikipedia defines an event as a “significant change in state”. If for example a Material Master is being updated, other processes in other systems need to be informed. This whole journey of generating the event, channeling and processing is called Event-driven architecture (EDA).

According to industry analysts, customers and user group feedback, event-driven architecture is already an important topic and will most likely become even more central in the future. As an example I still remember the last DSAG annual meeting in Mannheim (sitting in the keynote together with 1000nds of people…), listening to the great Keynote from Steffen Pietsch (in German only, from 0:32:00 on).

Event-driven architecture with SAP

In the last couple of years, SAP has put a lot of effort into providing holistic support for EDA, just to mention a few highlights:

Enabled Backend Systems
- S/4HANA Enterprise Events
  - On Premise
  - Cloud
- SAP SuccessFactors
- SAP Subscription Billing
- SAP Marketing Cloud

Central Event Bus
- SAP Cloud Platform Enterprise Messaging as the central Event-Bus
  - AMQP Adapter for SAP Cloud Platform Integration
- SAP API Business Hub

Connected Systems
- AMQP or Cloud Events Trigger at Cloud Functions inside the SAP Cloud Platform Extension Factory, serverless runtime
- SAP Cloud Application Programming Model

One missing – but important – stakeholder was the group of the SAP ECC customers. To let this group also participate on event-driven architecture we just released the ABAP Add-On SAP NetWeaver, add-on for event enablement. This Add-On works as an SDK, customers will be able to enable objects with just a few clicks, generating their own content (events). Of course the events generated in an SAP ECC System will follow the same standard (https://cloudevents.io/) as events coming from an S/4HANA System.

What is the benefit, especially for SAP ECC customers?

Event-driven architecture in general is offering a lot of advantages like decoupling or the avoiding of polling. With this new Add-On, SAP ECC customers particularly, will be able to leverage SAP Cloud Platform as an extension platform even more – as now the event-centric pattern is also supported in addition to REST / OData via SAP Gateway. In combination with SAP S/4HANA this will open up some great new opportunities:

In order to serialize activities during the SAP S/4HANA Migration, it is now easier to port existing event-driven extensions from SAP ECC to SAP Cloud Platform. A guide on the general topic of side-by-side extensions is available here

This will bring back your SAP ECC System closer to the standard – and this will then reduce complexity during the migration to SAP S/4HANA

As SAP S/4HANA already supports events, the switch to SAP S/4HANA will be easy – if you already designed the cloud extension with the SAP S/4HANA Events and OData services accordingly.

Several missions are available showing in more detail on how to extend an S/4HANA System based on event-driven architecture (e.g https://discovery-center.cloud.sap/#/missiondetail/3156/3192). We are currently working on the same scenario – only using an SAP ECC system instead of an S/4HANA system.

Summary

The Add-On SAP NetWeaver, add-on for event enablement (ASANWEE) is available for NetWeaver 7.31 and higher (Documentation) and is based on an ABAP Add-On from the partner company ASAPIO (https://www.asapio.com/en/index.html), but adapted for the usage with the SAP Cloud Platform.

2020 - Dec 22nd - Update:

Mission now available:
- Public Mission Board link: https://discovery-center.cloud.sap/missiondetail/3338/3384
- Public Github link : https://github.com/SAP-samples/cloud-extension-ecc-business-process/tree/mission/mission

Mentioned at TechEd Keynote 2020: https://youtu.be/wP0pL_Ps1dM?t=1195

2021 - June 1st - Update

AddOn is now also available for S/4HANA
- https://blogs.sap.com/2021/06/01/sap-netweaver-addon-for-event-enablement-now-also-released-for-s-4hana/
- https://www.sap.com/dmc/exp/2021-06-sapphireinnovation-news/sap-enhances-support-for-event-based-integration/

Writing Function-as-a-Service [5]: Top Secret

2020-07-07T13:37:43+02:00

With other words:

Secrets and Config Maps
in
SAP Cloud Platform Serverless Runtime
What's that?

This blog is part of a series of tutorials explaining how to write serverless functions using the Functions-as-a-Service offering in SAP Cloud Platform Serverless Runtime

Quicklinks:
Quick Guide
Sample Code

So what about those Secrets and Config Maps?w
Short answer:
To me, they look like simple property files

Example:
We want to write a function which needs to call a different REST endpoint
We don’t want to hardcode the URL and credentials in the code
So we're looking for a way to store such info outside the code, somehow in some property files
In the server-and-file-system-less Function world, there’s a special mechanism to do so.

In this blog, we’re going through a simple example.
We're going to define a Secret and access it from within the code

Note:
This blog shows the usage of Extension Center, but everything can be done in your local dev environment as well

Prerequisites

You should already be familiar with the Function-as-a-Service part of SAP Cloud Platform Extension Center, serverless runtime
Otherwise, see series of tutorials

Create Project

We can create a new Extension (Functions project) or reuse an existing project

In my example, using "Template with function":
Extension name: topsecret
Runtime: nodejs10
Function name : secretfunction
HTTP trigger name : showsecret

After project creation, we want to define secret and config map.
Currently, there’s no UI support, so we have to create files and folders and edit the faas.json manually

Define secret

First of all, we have to understand that a secret is a logical artifact, handled by the FaaS runtime
A secret points to a folder, where a file is located (can be multiple)
That file contains the secret information

To me, a secret is like a secret treasure map. It doesn’t contain the treasure itself, only the path
The hidden treasure can be found there and it contains …. tasty cat food

So let's create files and folders first

Note:
As usual, by choosing silly names, I’ve tried to make clear that you’re free to choose the file and folder names
There’s only one exception:
The “data” folder must have name as “data”

Create Folder
To create a folder, select the Code folder, then press the create-folder symbol
Enter folder name as data
Then click on the new data folder and create a subfolder called donotopenthisfolder
Click on folder donotopenthisfolder and press the file symbol
Enter file name as hiddensecret.json

Enter secret values
Now open the file hiddensecret.json
Paste the following content:

{

  "Max": {

    "username": "max@maxmail.com",

    "password": "max123"

  },

  "Joe": {

    "username": "joe@joemail.com",

    "password": "joe123"

  }

}

That’s not it
I mean, we've only created a file with secret info.
That's not THE secret yet
Although the file is located in a folder which nobody would dare to open

Note:
Make sure to press “Save And Deploy” from time to time

Define Config Map

A config map is similar like a secret, but not so top secret.
We use config maps to store any configuration info which we don’t want to hardcode in the javascript module
Again, a config map is a file, located in a subfolder of the “data” folder

Create folder
Select the folder data and create a subfolder with name cfg
Select the folder cfg and create a file with name addressconfig.json

Enter configuration values
Paste the following content which contains an example for possible REST endpoint URLs

{

  "dev": {

    "user": "Max",

    "url": "http://maxservice/endpoint"

  },

  "prod": {

    "user": "Joe",

    "url": "http://joeservice/endpoint"

  }

}

Create another folder
Select the folder cfg and create a file with name addresstext.de

Enter configuration value
This file contains an example for plain text in German language:

Guten Morgen

Note:
Finally, our FaaS project should look like this:

Now really define Secret and Config Map

Up to now we’ve only created files.
Now we need to declare them in the manifest file, such that the FaaS runtime can take care of them
So now we really DEFINE the secret and config maps

We open faas.json
Since we’ve used the template to create the extension project, the file initially would look like this:

We can see the elements which sound promising: “secrets” and “configs”
And we can see that the secrets are defined and where they are referenced:
A function has to declare which secret and config it wants to use

So now we can go ahead and enter the declarations and usages

As mentioned, a secret is a logical artifact which is defined as an entry in faas.json
To make it less logical and more physical, it has the source property which points to a directory.
It is the directory which contains the files with configuration info

"secrets": {

  "mysecret": {

    "source": "./data/donotopenthisfolder"

  }

},

And the secret has a name of our choice, such that it can be referenced.

BTW, same procedure with config

Next step:
If we want to access secret info from the implementation of our function, we need to explicitly reference it.
To reference a secret, we just write the name in an array (can reference multiple secrets)

"functions": {

   "secretfunction": {

      "secrets": ["mysecret"],

Finally, the full faas.json looks as follows

{

	"project": "topsecret",

	"version": "0.0.1",

	"runtime": "nodejs10",

	"library": "./lib",

	"secrets": {

        "mysecret": {

          "source": "./data/donotopenthisfolder"

        }

	},

	"configs": {

        "myconfiguration": {

          "source": "./data/cfg"

        }

	},

	"functions": {

		"secretfunction": {

			"module": "index.js",

			"handler": "handler",

			"secrets": ["mysecret"],

			"configs": ["myconfiguration"]

		}

	},

	"triggers": {

		"showsecret": {

			"type": "HTTP",

			"function": "secretfunction"

		}

	}

}

Note: saveanddeploy

View the values

Now let’s explore what we’ve just defined
In Extension Center, click on Form View, then “Secrets” tab and finally on the icon to view the details
The content of the secret is visualized in a nice way:

The dialog is well aware that the value of a secret is secret
Anyways, I still believe it looks like cat food in a treasure chest...

Let’s also view the details of the config:

We can see that we have 2 config maps and that one has json content and the second one has string content (german string, BTW)

Note the terminology:
The file name is the key, the file content is the value
In fact, it is a (config) map with key and value
We will need that later

Access secret and config in function code

We didn’t create the secret only for playing hide and seek
We want to access it in the impementation and extract the value

How to do this?

It is done with support of FaaS runtime, which offers a convenient API for it
When the runtime invokes our handler function, it passes an object to us which contains all required info: the context object

How to use it?

The convenience API offers access to the value of the secret, based on the name of the secret

context.getSecretValue...

Furthermore, we can choose if we want the response as plain String or as JSON

context.getSecretValueJSON(…)

Next, we have to pass the information about which secret we want to use
Since there can be multiple secrets defined in faas.json and referenced by any function, we have to pass the secret name as first param

Remember that the secret basically is a folder, such that we also have to pass the file name as second param:

context.getSecretValueJSON('mysecret', 'hiddensecret.json')

As a response we get a JSON object (depending on the API-method we’ve chosen)
Example for node10 syntax:

const credentials = await context.getSecretValueJSON('mysecret', 'hiddensecret.json');

The API overview can be found in the SAP Help Portal
Example for the syntax

getSecretValueJSON(name, key)

Explanation:
As already explained, the
“name” is the secret name (pointing to a folder)
“key” is the file name

Now we can open our function in the Code editor and replace the generated content with the following snippet:

module.exports = { 

	handler: async function (event, context) { 

        const credentials = await context.getSecretValueJSON('mysecret', 'hiddensecret.json');

        const config = await context.getConfigValueJSON('myconfiguration', 'addressconfig.json')

        const greeting = await context.getConfigValueString('myconfiguration', 'addresstext.de');

    

        const url = config.dev.url;

        const user = credentials.Max.username

        const pwd = credentials.Max.password

        

        console.log(`Calling URL: '${url}' with user '${user}' and password '${pwd}' and greeting '${greeting}'`)

        return "Top Secret";

	} 

 }

The example shows the usage of API for secret and configs and it shows how the different content is accessed: JSON and String
The example assumes that we would use the info for sending a request to a REST endpoint…
But we can skip that and just write the info to the log

Note: saveanddeploy

Run

After paste and save and deploy, we can invoke the function with the generated HTTP trigger URL
Our browser response contains just a silly text.
Now we regret that we’ve written the info text to the log instead to the HTTTP response
So we have to continue cligging digging for the treasure chest
Finally we find it:

What we see:
The secret information was extracted from the secret and config maps
Good job done nicely by the FaaS runtime
Maybe we think that it wasn’t a good idea to write the sensitive info to the log – but who cares what is done in a simple example?
We can also see that the runtime provides some info about the used environment, which is the nodejs runtime and the existing secrets and configs
This is another convenient service for us

Summary

We've learned that secrets and config maps are elements in the faas.json which point to simple property files
And we've learned how to access the content of such files from the implementation code

Quick Guide

Create files and folders to store the desired config data
Concrete: create "data" folder and another subfolder and store the files there

Define the secret in the faas.json
"secrets": {
"mysecret": {
"source": "./data/donotopenthisfolder"
}
},

Reference it from function in faas.json
"secrets": ["mysecret"],

In code:
Use helper methods to access the secret, and pass secret name and file name:
context.getSecretValueJSON('mysecret', 'filename.json')

Appendix: All Sample Project Files

For your convenience, see here the project structure:

faas.json

{

	"project": "topsecret",

	"version": "0.0.1",

	"runtime": "nodejs10",

	"library": "./lib",

	"secrets": {

        "mysecret": {

          "source": "./data/donotopenthisfolder"

        }

	},

	"configs": {

        "myconfiguration": {

          "source": "./data/cfg"

        }

	},

	"functions": {

		"secretfunction": {

			"module": "index.js",

			"handler": "handler",

			"secrets": ["mysecret"],

			"configs": ["myconfiguration"]

		}

	},

	"triggers": {

		"showsecret": {

			"type": "HTTP",

			"function": "secretfunction"

		}

	}

}

package.json

{}

index.js

module.exports = { 

	handler: async function (event, context) { 

        const credentials = await context.getSecretValueJSON('mysecret', 'hiddensecret.json');

        const config = await context.getConfigValueJSON('myconfiguration', 'addressconfig.json')

        const greeting = await context.getConfigValueString('myconfiguration', 'addresstext.de');

    

        const url = config.dev.url;

        const user = credentials.Max.username

        const pwd = credentials.Max.password

        

        console.log(`Calling URL: '${url}' with user '${user}' and password '${pwd}' and greeting '${greeting}'`)

        return "Top Secret";

	} 

 }

Appendix: The Hidden Secret

Writing Function-as-a-Service [6]: values.yaml

2020-07-10T10:36:45+02:00

This blog is part of a series of tutorials explaining how to write serverless functions using the Functions-as-a-Service offering in SAP Cloud Platform Serverless Runtime
Nice.

Quicklinks:
Quick Guide

In the previous tutorial we learned how to extract secret sensitive values from the code into some property files
We defined secret and config maps to store the sensitive values
Nice.
But when the time has come to move from silly prototypes to productive projects, then we want… no: YOU want (because I continue with silly examples) to upload your project to GIT (or similar) and you don’t want to upload files with passwords etc

FaaS has a solution for it: it supports values-files
Nice.

How does it work?
We extract the sensitive info from the “secret”-file into a values-file
That values-file is not uploaded to GIT
The “secret”-file (which is uploaded to GIT) contains placeholder instead of passwords
During deployment, the placeholders are replaced by the values from the values-file
That’s all.
Nice.

Now we only need to go through a silly example to learn how to do it
Nice.

Note that this tutorial is only possible for local development, such that it is a

Prerequisite

to go through the 2 local tutorials, to learn about xfsrt-cli and faas-sdk

Another prerequisite is the usual blabla that you have to be familiar, etc, so please don’t ask me “What is FaaS”, and instead go through some of my tutorials

Although this tutorial is based on the previous one, you can skip that silly top-secret-blog and use your own project, as long as it has any secrets and configs

Create Project

Sorry for the wrong wording:
we don’t create a project, we download the project which we created in previous blog, from Extension Center to our local file system
We go to Extension Center, open our project and press the “download” button

And extract the project to a location of our boring choice.
The boring choice, like in my example: C:\topsecret
The project looks like this:

Create values file

Correct wording.
But not good.
In fact, we don’t create that file:
We let the faas-sdk generate it

On command line, we jump into the project folder, then execute the following command:

faas-sdk init-values -y ./_tmp/mydeployvalues.yaml

The syntax:
faas-sdk init-values --deploy-values <yourFilePath>

Note:
We can use abbreviation -y

Note:
File extension (currently) must be .yaml

The command will generate the .yaml file with the given name in the specified folder.
If you don’t specify a folder, then a folder with name “deploy” will be generated.

In our example, the result looks like this:

In our case, we get a warning.
Reason: for a config map, we used a file extension which is unknown to the parser.
It was skipped, but that doesn’t matter for us. it doesn’t contain sensitive information, so we don’t need to extract the content into the values-file

What has happened?
The init-values command parses the faas.json file and collects all secrets and configs which are declared there (also registered services).
In addition, all files which are found are listed as keys with the file-content as values
All is pulled out of the project and pushed into one values-file

In our example, it looks like this:

We can see the silly names which we had chosen in the previous blog for secret names and file names.
We can see that the file content has been copied into this file, along with file names and secret names

Replace the values

The title of this chapter could also be replaced by:
“Extract the values”
Or
“Move the sensitive content from all files of secrets and config maps to the new values-file”

Anyways, the next step is to fill the generated values-file with the sensitive information

In our case, it is already there.
But if you start a project from scratch - in future - you might create the secrets with placeholders instead of passwords

OK, in our example, we now have to delete all passwords etc from our secrets and configs

We open hiddensecret.json, delete the values for "username" and "password" and replace them with anything silly that comes into our mind

Similar with file addressconfig.json

That’s it

Deploy

This title is correct and good
But before we deploy….
Wrong: nothing needs to be done before deployment
But when we deploy, we have to tell the deployer where to find the values
Because the deployer will replace the silly placeholders with the serious values.
So we have to add the -y flag to the deploy command (or --deploy-values)
As such, in our example, the deploy command looks like this:

xfsrt-cli faas project deploy -y ./_tmp/mydeployvalues.yaml

The syntax:
xfsrt-cli faas project deploy --deploy-values <yourFilePath>

After deployment we call the function and check the log to verify if the values really have been replaced

Looks as expected.
Isn’t it a nice feature? Our placeholders are replaced with the real values during deployment

If you don’t believe it and if you think it was just an illusion or a coincidence… try it with different values in the values-file

Summary

We’ve learned how to move sensitive information out of the secrets into a values file
Reason: secrets are part of the dev project and need to be uploaded to GIT
The values-file mechanism helps to keep sensitive information out of GIT
The FaaS SDK supports with generation of the values-file
The XFRST-CLI allows to deploy with values-files parameter
The Extension Center does (currently) not offer any support here
Nice.

Quick Guide

Project: remove the passwords (etc) from secrets (etc), replace with placeholder
Laptop: generate values-file with command (run in project root):
faas-sdk init-values -y ./mypath/mydeployvalues.yaml
FaaS: deploy the project with configured values-file
xfsrt-cli faas project deploy -y ./mypath/mydeployvalues.yaml

Writing Function-as-a-Service [7]: How to use Platform Services

2020-07-16T16:12:31+02:00

This blog is part of a series of tutorials explaining how to write serverless functions using the Functions-as-a-Service offering in SAP Cloud Platform Serverless Runtime

Quicklinks:
Quick Guide
Sample Project

In a previous blog, we had a little introduction into the usage of secrets and config maps
Today, I’d like to go through an example which shows how to connect a function to a service running in SAP Cloud Platform, Cloud Foundry Environment
As an example, we’re going to use the Destination service and call a configured destination
Any useful purpose to do that?
Surprisingly: yes
This example could be enhanced to a checktool which runs every night and checks if the destinations are still responding as expected
Why useful?
It would help with troubleshooting and early identify errors
Indeed
Anyways, this sample can be modified to use any other platform service

Prerequisites

To follow this tutorial, you should be familiar with FaaS (see series)
The function code is based on Node.js
As usual, this tutorial can be followed in Extension Center or with local dev environment

Overview

Configure Destination in the cloud cockpit
Create Destination Service Instance and Service Key
Create Destination Configuration

Create function which uses the destination
Create Function Project with secret and config map
Implement Function, calling destination service, using secret

Run the sample

1. Configure Destination in the cloud cockpit

In our example, we want to use destinations from our function.
Destinations are usually used whenever a cloud app calls a URL of an external service.
With destinations, we can avoid hardcoding URLs, it solves CORS issues and maintenance

1.1. Create Destination Service Instance

So the first step is to create a service instance of "Destination" service
In your Space, go to Service Marketplace and search for the tile "Destination"
If you don't find it, you might need to add "Entitlement" (see here for general description)
When creating the service instance,
no params are required
and the name can be destinationinstance

1.2. Create Service Key

In the server-more world, we would deploy an app, with manifest, where we would define a binding to the service instance. Then, in the code, we access the service-credentials via env variables

In the serverless world, we don't deploy an app, so we don't have binding and no env variables
That's why we need to create a service key for the service instance.
The service key provides us with same credentials which we would get with binding

We click on the created instance name
Then choose “Service Keys” in the left pane
Finally we press “Create Service Key” and enter a name like skfordestination
Now we can view the content of the service key

I’ve marked the relevant properties
But for the moment, we leave it like it is
We don't close the browser window, as we'll need the service key content later

Why?
We need these credentials to call the destination programmatically

1.3. Create Destination Configuration

Until now we’ve only created a destination service instance
Yes, it was necessary, otherwise we couldn't read the destination configuration
Now we create a configuration for a destination that should point to any URL

In the cockpit, we need to go to our subaccount, then expand “Connectivity”, click on “Destinations” and press “New Destination”

We create a destination of our choice, it doesn’t matter which URL, we won’t really use it seriously.
The screenshot shows an example

The above example points to an existing URL.
It specifies user credentials which aren't required. Just as example for later usage in the code

To illustrate the advantage of a destination:
The admin can decide to change the host of the destination to a different country, for example, (or landscape upgrade), and our function code wouldn't need to be adapted

2. Create Function which uses the Destination

Nest step is to create a function which programmatically uses the destination

2.1. Create Project Artifacts

I assume that you're familiar with Function-as-a-Service in serverless runtime, so let's only roughly go through the required steps
Please refer to the appendix for the file content

2.1.1. Create Project

We create a project with name destichecker and runtime nodejs10
Can be a project on local machine, or an "Extension" if you use the Extension Center

2.1.2. Define Secret

We define a secret (with name "destinationsecret") in the faas.json
We create data folder and secrets subfolder and create a file (with name destsrv.json) to carry the secret content
In our example, the file content is the content of the service key
As such, we go to our cloud cockpit and view the service key which we created above
We can just copy the whole content (yes, everything, including all the stuff which we’re not interested in) and we paste it into the file for our secret
And we save

2.1.3. Define Config Map

We define a config in the faas.json
In the data folder, we create a file (destcfg.json) to carry some configuration values
In our example, we store the name(s) of the destination configuration(s) created above
Make sure to copy&paste the destination name correctly

2.1.4. Create Function

In our faas.json, we define a function (e.g. "checkdestfun") with module and handler and reference to the secret and the config.
We create the lib folder (because predefined in the generated faas manifest) and the javascript file (destichecker.js)
The javascript file contains the handler and some silly test code (for a first test)

2.1.5. Define Trigger

To test our example, we create a HTTP trigger (with name "checkdest"), later we can create an additional timer trigger to let our function do its useful work on a regular basis
Later?
Yes, but not in this blog

2.1.6. Try the Function

After verifying that our faas.json looks like the one in the appendix, we deploy our function project and invoke it with the HTTP trigger URL
e.g.
https://123-faas-http.tenant.eu10.functions.xfs.cloud.sap/checkdest
It should work as expected

2.2. Implement Function

Now we come to the implementation part.
This is about how to use the destination service programmatically.
The code is not specific for serverless functions.
The only difference is that we get the credentials - which are required to call the destination service - from the FaaS runtime instead of accessing the environment variables

What our function should do:
. Access the service credentials
. Call the destination service to get the configured destinations
. Afterwards, read the destination configuration to get the URL and authentication
. Finally, execute the URL

2.2.1. Access the Service Credentials

Above, we created a Service Key
Then stored the content (JSON) in a secret
Now we use the API of the FaaS runtime to obtain the properties which we need from the service key:

const credentials = await context.getSecretValueJSON('destinationsecret', 'destsrv.json')



const destSrvUrl = credentials.uri

const oauthUrl = credentials.url

const clientId = credentials.clientid

const clientSecret = credentials.clientsecret

Similar approach to get the destination name from the config map

2.2.2. Call the Destination Service

The Destination Service itself is protected with OAuth.
As such, we need 2 steps for calling the Destination Service:
1. Fetch JWT token
Here we need the info from the service key (clientid, clientsecret and oauthUrl)

const _fetchJwtToken = async function(oauthUrl, oauthClient, oauthSecret) {

...	

   const options = {

      host:  oauthUrl.replace('https://', ''),

      path: '/oauth/token?grant_type=client_credentials&response_type=token',

      headers: {

         Authorization: "Basic " + Buffer.from(oauthClient + ':' + oauthSecret).toString("base64")

2. Call Destination Service
Once we have the JWT token, we can use the Url from service key to call the service, and we use the destinationName which we had stored in a config map

const _readDestinationConfig = async function(destinationName, destUri, jwtToken){

...	

   const options = {

      host:  destUri.replace('https://', ''),

      path:  '/destination-configuration/v1/destinations/' + destinationName,

      headers: {

         Authorization: 'Bearer ' + jwtToken

2.2.3. Read Destination Configuration

The result of the call to the Destination Service is the destination configuration for the requested destination name
In our Example, the destination configuration is simple.
We need the URL and the authentication info
We don't need to encode the user and password, this is done conveniently by the destination service

destiConfi.destinationConfiguration.URL 

destiConfi.authTokens[0].http_header.value

2.2.4. Call the target endpoint

Now we have all information we need to call the endpoint which is configured in the destination configuration
Usually, in a destination configuration, we would extract only the variable part of a URL.
Which usually would be the host.
That's what we've done in our example
As such, in the code, we have to append all stable segments to the URL which we obtained from the destination configuration.
In our example, we call the info about "Cat" (hardcoded)

const _callEndpoint = async function(url, auth){

...

   const options = {

      host:  url.replace('https://', ''),

      path:  '/Cat',

      headers: {

         Authorization: auth.http_header.value

See appendix for full file content

2.2.5. Small Recap

In our function implementation, we want to call a target URL
The full URL is not stored in our function project.
We want to use a Destination
To call the destination service, we use credentials which we had stored in a secret
First get a token
Then use it to get the destination config
Then read the config info to call the target endpoint

3. Run the sample

So finally, we copy all the function code from the appendix.
After deploy, we open the URL of our function and we get the expected result

Of course, the next step would be to improve our checker:
Refactor the code, use config map for destination name, support multiple/all destinations check, support control URL parameters, send JSON response, support timer trigger,store check results in servless BackendService
etc
However, no next steps in this blog nor in future blogs

Summary

In this tutorial we've learned how to consume the destination service from a serverless function
The sample code can easily be adapted to any other service of SAP Cloud Platform
The essential learning was to copy a service key to the function project

Quick Guide

To consume a service in a function we have to:
- create service key for the service we want to use
- copy the service key into a file in the FaaS project
- define a secret which points to that file
- in the function code, access the secret
- use the credentials properties in order to call the cloud service

All Sample Project Files

Project Structure

faas.json

{

  "project": "destichecker",

  "version": "0.0.1",



  "runtime": "nodejs10",

  "library": "./lib",



  "secrets": {

    "destinationsecret": {

      "source": "./data/secrets"

    }

  },

  "configs": {

    "destinationconfig": {

      "source" : "./data"

    }

  },

  "functions": {

    "checkdestfun": {

      "module": "destichecker.js",

      "handler": "doDestinationCheck",

      "secrets": ["destinationsecret"],

      "configs": ["destinationconfig"]

    }

  },



  "triggers": {

    "checkdest": {

      "type": "HTTP",

      "function": "checkdestfun"

    }

  }

}

package.json

{}

destsrv.json

{

	"uaadomain": "authentication.eu10.hana.ondemand.com",

	"tenantmode": "dedicated",

	"clientid": "sb-clone123!b22273|destination-xsappname!0000",

	"instanceid": "34ea5555-bbbb-bbbb-9999-4444200bbbbb",

	"verificationkey": "-----BEGIN PUBLIC KEY-----MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAwThn6OO9kj0bchkOGkqYBnV1dQ3zU/xxxxxxx+5/yDZUc0IXXyIWPZD+XdL+0EogC3d4+fqyvg/BF/F0t2hKHWr/UTXE6zrGhBKaL0d8rKfYd6olGWigFd+3+24CKI14zWVxUBtC+P9Fhngc9DRzkXqhxOK/EKn0HzSgotf5duq6Tmk9DCNM4sLW4+ERc6xzrgbeEexakabvax/Az9WZ4qhwgw+fwIhKIC7WLwCEJaRsW4m7NKkv+++++LKYesuQ9SVAJ3EXV86RwdnH4uAv7lQHsKURPVAQBlranSqyQu0EXs2N9OlWTxe8SoKJnRcRF2KxWKs355FhpHpzqyZflO5l98+O8wOsFjGpL9d0ECAwEAAQ==-----END PUBLIC KEY-----",

	"xsappname": "clone34ea5555b4ee4bbb9999db444444b888!b22222|destination-xsappname!b000",

	"identityzone": "myzone",

	"clientsecret": "c2D3E4F5G6A1B2C3D4E5=",

	"tenantid": "628e9f87-e539-49fc-a54f-1a1a1a1a1a",

	"uri": "https://destination-configuration.cfapps.eu10.hana.ondemand.com",

	"url": "https://mysubaccount.authentication.eu10.hana.ondemand.com"

}

destcfg.json

{

	"name": "dest_wiki_en"

}

destichecker.js

const https = require('https');



// main entry

const _doDestinationCheck = async function (event, context) {

	

	// we stored the desired destination name in a config map  

    const config = await context.getConfigValueJSON('destinationconfig', 'destcfg.json')

	const destinationName = config.name



	// use faas API to get credentials stored in secret

	const credentials = await context.getSecretValueJSON('destinationsecret', 'destsrv.json')

	const destSrvUrl = credentials.uri

	const oauthUrl = credentials.url

	const clientId = credentials.clientid

	const clientSecret = credentials.clientsecret

	

	// execute required steps to call the target URL

	const jwtToken = await _fetchJwtToken(oauthUrl, clientId, clientSecret)

	const destiConfi = await _readDestinationConfig(destinationName, destSrvUrl, jwtToken)

	const result = await _callEndpoint(destiConfi.destinationConfiguration.URL, destiConfi.authTokens[0])

	

	return `Check Result:\n${result.message}`

} 



// JWT token is required to call the Destination Service

const _fetchJwtToken = async function(oauthUrl, oauthClient, oauthSecret) {

	return new Promise ((resolve, reject) => {

	   	const options = {

		  	host:  oauthUrl.replace('https://', ''),

		  	path: '/oauth/token?grant_type=client_credentials&response_type=token',

		  	headers: {

			 	Authorization: "Basic " + Buffer.from(oauthClient + ':' + oauthSecret).toString("base64")

		  	}

	   	}

	   	https.get(options, res => {

		  	res.setEncoding('utf8')

		  	let response = ''

		  	res.on('data', chunk => {

				response += chunk

			})

			res.on('end', () => {

				try {

					const responseAsJson = JSON.parse(response)

					const jwtToken = responseAsJson.access_token            

					if (!jwtToken) {

						return reject(new Error('Error while fetching JWT token'))

					}

					resolve(jwtToken)

				} catch (error) {

					return reject(new Error('Error while fetching JWT token'))               

				}

			})

		})

	   .on("error", (error) => {

		  console.log("Error: " + error.message);

		  return reject({error: error})

	   });

	})   

 }

 

// Call Destination Service. Result will be an object with Destination Configuration info

const _readDestinationConfig = async function(destinationName, destUri, jwtToken){

	return new Promise((resolve, reject) => {

		const options = {

			host:  destUri.replace('https://', ''),

			path:  '/destination-configuration/v1/destinations/' + destinationName,

			headers: {

				Authorization: 'Bearer ' + jwtToken

			}

		}		

		https.get(options, res => {

			res.setEncoding('utf8')

			let response = ''

			res.on('data', chunk => {

			  	response += chunk

			})   

			res.on('end', () => {

			   	try {

				  	const destInfo = JSON.parse(response);						

				  	resolve(destInfo)

			   	} catch (error) {

				  	return reject(new Error('Error while parsing destination configuration'))               

			   	}

			})

		})

		.on("error", (error) => {

			console.log("Error while calling Destination Service : " + error.message);

			return reject({error: error})

		});		  

	})

}



// call the URL extracted from Destination Config. Manually append required URI segments

const _callEndpoint = async function(url, auth){

	return new Promise((resolve, reject) => {

		const options = {

			host:  url.replace('https://', ''),

			path:  '/wiki/Cat',

			headers: {

				Authorization: auth.http_header.value

			}

		}		

		https.get(options, res => {

			const status = res.statusCode

			if(status < 400){

				resolve({message: `Successfully called destination with target URL: ${url}${res.req.path}`})

			}else{

				reject({error: {message: `Invalid Url: ${url} with status ${status}`}})

			}

		})

		.on("error", (error) => {

			reject({error: error})

		});		  

	})

}



// export the handler function with readable alias

module.exports = {

	doDestinationCheck : _doDestinationCheck

}

Writing Function-as-a-Service [8]: How to (easily) use Platform Services

2020-07-23T17:18:59+02:00

With other words:

How to write serverless function
in
SAP Cloud Platform Serverless Runtime
and using
Service Registration
aka
Credential Store
to reference
Platform Services

This blog is part of a series of tutorials explaining how to write serverless functions using the Functions-as-a-Service offering in SAP Cloud Platform Serverless Runtime

Quicklinks:
Local development
Quick Guide
Sample Project

The previous blog was not good
Why?
Too complicated
The same can be achieved more easily using the Service Registration feature offered by FaaS
What's this?
Let's see:

In the previous blog,
we created a service instance and service key
we created a project
we created a file to store the service key
we created a secret pointing to the file

To facilitate using a service instance, FaaS offers a feature to register a service instance in FaaS
This means that we don't need to create a secret anymore
We just reference the registered service
Furthermore, the service is registered globally in FaaS, making it available for all projects

In this tutorial, we're going to learn how to use the service registration feature in the Extension Center but also how to achieve the same with the command line client for local development

As example, we're going to use the platform service Enterprise Messaging, and we'll connect our function to it.
Our scenario is:

Whenever a message is sent to Messaging,
then our function will be triggered
and it will do nothing

Prerequisites

Access to FaaS which is currently only available in productive landscape

Basic knowledge about Node.js

Access to Extension Center is not required, everything can be done with local dev environment

To follow this tutorial, it is necessary to be able to use SAP Cloud Platform Enterprise Messaging

Preparation

In this tutorial, we want to learn how to register a service instance.
As such, the first step is to create such instance
A nice side-effect: we learn how to connect FaaS to Enterprise Messaging

If you aren't familiar at all with messaging, you can have a look in a rough description I wrote here

Command line users see here

1. Create instance of service Enterprise Messaging

We create an instance of the Enterprise Messaging service.
We use the following JSON parameters:

{

	"options": {

		"management": true,

		"messagingrest": true,

		"messaging": true

	},

	"rules": {

		"topicRules": {

			"publishFilter": [

				"${namespace}/*"

			],

			"subscribeFilter": [

				"${namespace}/*"

			]

		},

		"queueRules": {

			"publishFilter": [

				"${namespace}/*"

			],

			"subscribeFilter": [

				"${namespace}/*"

			]

		}

	},

	"version": "1.1.0",

	"emname": "faas_msg_client",

	"namespace": "comp/busi/crm"

}

And as name for the service instance, we enter faas_msg_instance

Note:
As you know, I like to use silly names in my tutorials, I believe it makes the learning easier, because the name always tells what it is about and it makes clear that an arbitrary name can be chosen
Of course, it is not recommended to use silly names in productive environment

Note:
If you don't find the Messaging service, you might need to configure Entitlements

2. Create Service Key for the instance

After creating the service instance, we need a Service Key.
It provides credentials which allow to access the service externally, without binding an application

To create a service key, we have to click on the newly created service instance
In our example, we enter the name as faas_service_key
We don’t close the browser page, we will need to view the service key content later on

3. Configure Messaging

After creating the messaging instance, we can open the messaging dashboard.

We go to messaging client created above (property "emname": faas_msg_client)

We create queue with name queue/for/faas
This will result in full queue name comp/busi/crm/queue/for/faas
The queue is used for receiving and queuing messages.

That's it for the preparation.

Small Recap:
We've created messaging instance and service key
We've created a queue in our client

Extension Center

Now we want to use this service in a Function
I've promised that it is easy.
Yes

1. Register Service Instance

FaaS provides built-in support for connecting to Platform services
Prerequisites are: service instance and service key
Fortunately, we just created both in the chapter above
So we’re lucky enough to use them
The FaaS feature to support the Platform services includes a kind of service registration
Independent of any specific function project, we can register a service instance in the FaaS runtime
It will safeguard the service instance credentials against any malicious phishing hooks
No secret required, no tedious copy&pasting of clientids and so on
And whenever we need it, we can just use it

I like to compare it to a dog show in a circus:
If you say "hepp", the dog will jump, etc
If you say “enterprise-messaging”, the function will connect to the registered service instance
(BTW, why I’ve never seen a cat show in a circus…?)

How to register a service instance?

In Extension Center, we don’t click on “Extensions”
We don’t create any project
Instead, on the left menu pane, we expand “Configurations” and click on “Extensions”
Yes, it's quite similar name
The "Extension Credentials" screen is shown

Here we can store credentials of a service instance. As mentioned above, the service key of a service instance is used for external access.
Since we cannot bind a function to a service, it will always be external.
Problem?
No.

In the “Extension Credentials” screen we can register a service instance.
It is clear that changes in this screen are not related to individual projects.
Services are registered globally in FaaS and can be used by multiple projects (extensions)
With other words: using the Extension Center, we can store credentials.

So let's go ahead and press “New Credentials”
In the creation dialog, we have to enter following values:

Type:
This is the service offering of the SAP Cloud Platform, the service names as displayed in the service marketplace. Luckily, we have tool support, such that we don't need to look up the type names.
For our example, we choose "enterprise-messaging"

Service Instance:
Here we enter the name of the instance of the Enterprise Messaging service which we created in the preparation section above.
In our example: faas_msg_instance

Service Key:
Similarly, we enter the name of the service key created above
In our example: faas_service_key

Credentials:
Here we enter the value of the service key.
Remember I told you to not close the browser window...?

2. Use Registered Service

As we’ve seen, the service is registered in the FaaS runtime on global level
With other words, we've stored service credentials in the Extension Center
Now we can use it in a project
So let’s create a new Faas Project, or, with other words, a new Extension

Create Extension

In our example, we create an extension that consumes messages from a message queue and writes any silly statement to the log

In the creation wizard, we choose use the "Blank Template"
And we give a name like "tracker"

Create Function

We create a new Function with the following sample values:

Function Name	tracker-func
Module Name	trackerimpl.js
Handler Name	msgreceiver

The function implementation could be as follows:

module.exports = { 

   msgreceiver: function (event, context) { 

      console.log(event.data)

   } 

}

As usual, to keep the code simple and readable, the function implementation does:
nothing.
Just log the payload of the received message
In a productive scenario, the function would do anything more interesting, process the message and call any other component of the extension scenario
(Otherwise it would be a shame: wake up the function, just to do nothing...)

Create AMQP Trigger

In Extension Center, press "Add Trigger" and choose type AMQP
Step through the wizard and enter the following values:

Step 1:
Trigger Name: amqp-tracker-tricker

Step 2:
Incoming link name: msg-to-faas-link
Source Address: queue:comp/busi/crm/queue/for/faas
With other words: the full queue name as created in the preparation section, preceded by "queue:"
To add the link, we press the PLUS icon

Step 3: Outgoing Link:
We don't enter anything here
Only press “step 4”

Step 4: Rules
Filter: msg-to-faas-link
Invoke Function: tracker-func
On failure: reject message
And we press the +

Step 5: Credentials
Press “use existing credentials store”
Type: enterprise-messaging
Instance: faas_msg_instance
Key: faas_service_key

Finally confirm and close the wizard

We can check the extension project to verify what the wizard has done for us:

In file system:
Created folders to carry config files
Created config files to carry the configs
Created configs for the messaging trigger, containing the config we entered in the wizard

In faas.json:
Defined a reference to the service which we registered in FaaS (Credentials store)
Defined a config map (generated name)
Defined the trigger which uses the config and the service-reference

Small recap
Connecting a function to messaging involves:
Create and use service registration (alternatively, use secret)
Create AMQP triger and configure it with queue / topic names and rules

3. Run the scenario

Remember the scenario:
A message is sent to the Messaging service, which causes the AMQP-trigger to wake up the function
Fortunately, the dashboard offers a little tool which allows to send messages.

So we go to the Enterprise Messaging dashboard
To send a message to the queue which we defined above:
We select the messaging client created above
We select the Tab “Test”
We choose Action as “Publish Message to a Queue”
Then we select our queue
Obviously, we enter a silly useless message
Finally, we press “Publish”

What's happening now?

The Test tool has sent a message to the queue
We can see in the same tool ui, that the “Number of Messages” has been increased from 0 to 1
The message would wait there in the queue until it is picked up
(That’s why a queue is called queue)
Now, we have somebody who is watching that queue and picks the messages which are dropped there:
Yes.
Us.
OK, but also the AMQP trigger is watching the queue (we configured it)
And whenever an innocent message falls into the queue, the trigger will wake up the function
Before it wakes up the function, the trigger checks the rules, of course
The function then receives the message in the parameter “event”
Like that, the function implementation can access the message payload
That's what we did
And the function can do something with the payload
That's what we didn’t do
Since the trigger has picked the message from the queue, the “Number of Messages” in the dashboard is reduced from 1 to 0
We can check that in the dashboard (Queues tab)

What we need to check as well: the FaaS log
Here we can see the log output which was written by our function.

This makes our little scenario complete:
A message is sent to Enterprise Messaging and the connected FaaS reacts and reads the message

Local Development

The following description is meant for those of you who are used to work locally and interact with FaaS using the command line
Since you're anyways the experts, I'm only giving some useful commands
No explanations

Preparation

Create instance of Enterprise Messaging service:

cf cs enterprise-messaging default faas_msg_instance -c <jsonFileWithParams>

Create service key

cf csk messaginginstance serviceKeyForMessaging

View the created service key

cf service-key faas_msg_instance faas_service_key

It is not required to copy the content
However, we will need to view the ID of the messaging service instance
So don't close this command shell

1. Register Service Instance

Very first step: login to cloud foundry using the CF CLI

cf login

First step: login to the FaaS runtime using the FaaS CLI

xfsrt-cli login

Or we might want to check to which subaccount our FaaS CLI is currently pointing at

xfsrt-cli target

Now, to register an existing instance of Enterprise Messaging in FaaS, we use the following command

xfsrt-cli faas service register -s faas_msg_instance -b faas_service_key

Syntax:

xfsrt-cli faas service register
--service-name <name of instance>
--service-binding <name of service key>

Note:
You need to be logged in Cloud Foundry using the CF CLI
If not, you might get an error message and it might be required to execute the service-registration command twice

Note:
The FaaS CLI is so convenient that it proposes the existing service instances, so we can skip the parameters of the command

I have to repeat that the FaaS CLI is a really great and convenient tool

Few more commands:

To view already registered service instances:

xfsrt-cli faas service list

To unregister a service instance

xfsrt-cli faas service delete

then wait and choose the desired service

2. Use Registered Service

Create a project

On our local file system, we create a project based on the sample code in the appendix

To use the registered service, we define a reference to it

"services": {

   "cs1": {

      "type": "enterprise-messaging",

      "instance": "a1b2c3d4-a1b2-1234-a1b2-a1b2c3d4e5f6",

      "key": "faas_service_key"

Then we can use the service reference in our trigger:

"triggers": {

   "amqp-tracker-tricker": {

      "type": "AMQP",

      "service": "cs1",

Note:
In the faas.json, which is the manifest of our project, we define a reference to a registered service. Like that, we can use it in our project. The reference points to the registered service instance. It has to point to the unique name of the service instance. Otherwise there might be name clashes. As such, we have to look for the instance ID. We find it in the service key content

Deploy

Jump into the project root directory (same folder where faas.json is located) and execute

xfsrt-cli faas project deploy

Note:
Even for service references it is possible to provide deploy values, as described here

3. Run the scenario

To run our scenario, send messages from Enterprise Messaging Dashboard and make sure that they are consumed (number of messages in the queue must decrease to 0)

Check the logs to view if our function works as expected
Jump into the project folder (to make the command easier), then execute

xfsrt-cli faas project logs

In the logs we can see the payload of the messages that we send

Summary

In this tutorial we've learned how to register an existing service instance in FaaS
With other words, we've learned how to store credentials in Extension Center
And we've learned how to use them in a FaaS project
To showcase it, we've used an instance of Enterprise Messaging service.
More precisely, we've used the registered service from an AMQP trigger

Troubleshooting

If you have headache because messages aren't arriving in Messaging Queue, you should check this guide

Quick Guide

An existing service instance can be registered globally in FaaS (service key is required)
In Extension Center, it is done via top level menu "Configuration"
With command line: xfsrt-cli faas service register

To use the registered service (credentials) in a faas.json:
Define new service reference under element "services"
Use service reference from trigger definition
Also (not covered in this blog), the stored credentials can be accessed from function code

Appendix: All Sample Project Files

I’ve downloaded the project from Extension Center and for your convenience, pasting the file content here
Note that I would have chosen different names, where it is visible that names were generated by Extension Center

Note:
In the faas.json we have to enter the ID of the instance of the Enterprise Messaging service.
When registering the service instance, we can choose the instance by name
However, when defining the reference in the faas.json, we have to enter the ID
To retrieve the ID, proceed as follows
Go to chapter "Preparation->Create Service Key" and copy the value of property instanceid
If you coincidentally closed the window, proceed as follows
Open the content of the service key with command csk
Then search for the property instanceid (usually at the end of the json )
The value of the instanceid usually looks like this:
a1b2c3d4- a1b2- a1b2- a1b2- a1b2c3d4e5f6
This has to be entered as value for the property instance in the faas.json

package.json

{}

faas.json

{

	"project": "tracker",

	"version": "0.0.1",

	"runtime": "nodejs10",

	"library": "./lib",

	"configs": {

		"amqp-tracker-tricker-config": {

			"source": "./data/amqp-tracker-tricker-config"

		}

	},

	"functions": {

		"tracker-func": {

			"module": "trackerimpl.js",

			"handler": "msgreceiver",

			"timeout": 180

		}

	},

	"triggers": {

		"amqp-tracker-tricker": {

			"type": "AMQP",

			"service": "cs1",

			"config": "amqp-tracker-tricker-config"

		}

	},

	"services": {

		"cs1": {

			"type": "enterprise-messaging",

			"instance": "c2ab778a-0c68-4523-b7df-ce188bc67337",

			"key": "faas_service_key"

		}

	}

}

amqp.json

{

	"incoming": {

		"msg-to-faas-link": {

			"sourceAddress": "queue:comp/busi/crm/queue/for/faas"

		}

	}

}

bind.json

{

	"functions": {

		"tracker-func": {}

	},

	"rules": [

		{

			"filter": {

				"incoming": "msg-to-faas-link"

			},

			"action": {

				"function": "tracker-func",

				"failure": "reject",

				"content": "application/json"

			}

		}

	]

}

trackerimpl.js

module.exports = { 

   msgreceiver: function (event, context) { 

      console.log(event.data)

   } 

}

Params for messaging instance:

{

	"options": {

		"management": true,

		"messagingrest": true,

		"messaging": true

	},

	"rules": {

		"topicRules": {

			"publishFilter": [

				"${namespace}/*"

			],

			"subscribeFilter": [

				"${namespace}/*"

			]

		},

		"queueRules": {

			"publishFilter": [

				"${namespace}/*"

			],

			"subscribeFilter": [

				"${namespace}/*"

			]

		}

	},

	"version": "1.1.0",

	"emname": "faas_msg_client",

	"namespace": "comp/busi/crm"

}

Writing Function-as-a-Service [9]: How to call OAuth-protected endpoint

2020-08-19T10:32:42+02:00

This blog is part of a series of tutorials explaining how to write serverless functions using the Functions-as-a-Service offering in SAP Cloud Platform Serverless Runtime

Quicklinks:
Quick Guide
Sample Code

Introduction

In function code we can do basically anything that is possible in Node.js
Sounds good, but sometimes there are hurdles
Like the (necessary but tedious) security aspects
If we do a demo and call a REST service endpoint from within a function:
then that endpoint will always be open, to make the demo small and nice
However, usually, REST endpoints are protected and users need to authenticate with user/password
-> That’s easy, just provide basic auth
Other endpoints require an apiKey
-> No prob, we set it as header
Prof endpoints are protected with OAuth authentication
-> Here it gets more complicated, but I showed it in previous blog
Really prof endpoints are OAuth protected and require authorization
-> This is a bit more tricky and requires some config in addition to the OAuth flow

Why tricky? Just assign a role to the user...?
Stop:
A function is not a user and we cannot assign the required role to the function like we would assign it to a user
Luckily, this tutorial shows how to achieve that:
Write a function that calls an endpoint that is protected with OAuth and requires scope

With other words, about the tricky part:
How to assign a scope to a function in client-credentials flow

Remember OAuth 2.0:

In order to access a resource (REST endpoint), we need a JWT token.
We get that token from “Authorization Server” (XSUAA)
To get it, there are several “grant types”:
- “Resource Owner Password Credentials”: human user authenticates with password (login screen) and token contains scopes based on his roles
- “client credentials”: from app to app, no login
(see here for more info)

In our scenario, the function runs without user context
As such we’re talking about “client credentials” flow
We don’t have user password.
We cannot get a user password by opening a login screen

Of course, we know how to obtain a JWT token from XSUAA service instance
But that token doesn’t contain the scope which is required by the protected REST endpoint

So what needs to be done in order to get a JWT token containing a certain scope?
The trick is in the configuration of the xsuaa instances

Note:
Of course, it is possible to call a function from e.g. a UI5 application, which is user centric and has user login
In that scenario, the function would receive the JWT token from the UI5 application, so nothing needs to be done
So no tutorial required
This tutorial is for the non-user-centric scenario, no UI, no user, no fun

Prerequisites

– Access to SAP Cloud Platform, productive account. Trial is (currently) not supported
– Instance of Serverless Runtime (see Preparation blog)
– Cloud Foundry CLI installed locally (see same Preparation blog)
– Functions CLI available locally (see still same link)
– Node.js installed
– Basic knowledge of writing functions in SAP Cloud Platform serverless runtime

Overview

In the first part of this tutorial, we’re creating a very basic app which exposes an endpoint which is protected with OAuth and which requires a certain scope
In the second part, we’re creating a Function which tries to call that endpoint

Part 1: The Protected App
Create xsuaa, define scope
Create app, check scope

Part 2: The Calling Function
Create xsuaa, define authority
Create Function, do OAuth flow

Preparation: Create Project Structure

In our example, we're using one root Project C:\tmp_faas_callsafe
containing 2 working directories,
for the secure app C:\tmp_faas_callsafe\safeapp
and for the Function C:\tmp_faas_callsafe\unsafefunction
So let's create the folder structure:

Beautiful.

Part 1: The Protected App

We use Node.js and express to create a simple app which provides a REST endpoint
We use passport and @sap/xssec to protect it with OAuth 2.0
We use manual code to enforce the required authorization
We use an instance of XSUAA service for managing the OAuth flow

1.1. Security Configuration

Security for our app is carried out by an instance of XSUAA
We configure it with the following params

{

  "xsappname" : "xsappforsafeapp",

  "tenant-mode" : "dedicated",

  "scopes": [{

      "name": "$XSAPPNAME.scopeformysafety",

      "grant-as-authority-to-apps" : [ "$XSAPPNAME(application, xsappforfaas)"]

  }]

}

This content can be pasted during instance creation in cloud cockpit, but for better handling, we store above content in a file with a name of our choice.
In my example, the file has a silly name to avoid confusion: xs-security-safe.json

Short explanation

xsappname
The name of the security artifact (Internally, it is treated like an application).
Security artifacts to be distinguished by XSUAA and by us.

scope
We declare: we require that anybody who calls our endpoint should have special permission.
To distinguish “our” permission from others, we give a name to “our” special permission
This is the "scope".
Note: we aren’t defining a “role”. This means that no human user will be able to call our endpoint
In our tutorial we don’t need it
So let’s keep the file short and focus on the essential

"grant-as-authority-to-apps"
This is the essential line:
Instead of assigning a “role” to a human user, we assign it to an application.
Because that’s what we want to learn in this tutorial: how a function from FaaS can call a protected app that requires a special "scope"
Our app is protected with oauth and requires a scope.
And "grant" is the mechanism how an external application (FaaS in our case) can get the permission/authorization to call the protected endpoint
Note:
We have to understand that we’re not assigning the scope to the name of a deployed Node.js application (or whatever)
What we’re explicitly writing here: the name of the security artifact. The name of the security artifact is the value of the property xsappname
To avoid confusion, I always give stupid names to all artifacts, that makes it easier to distinguish.
As such, if a name starts with xsapp..., it is the name of a security artifact
In the current tutorial, we will create a second instance of xsuaa and we will name it xsappforfaas
So that's what we write here: We "grant" the new scope to the security artifact with name xsappforfaas
Note:
The syntax for defining the permitted application:
"$XSAPPNAME(<service_plan>, <name_of_xsapp_attribute>)"
Note:
In the section below, there will be a note to type the value of xsappname exactly like here
Or we can say: here we have to type the value of xsappname exactly like we’ll type it in the section below
Doesn't matter: No typos allowed for xsappname attribute, otherwise we'll get errors

Anyways, creating a file is not enough: this isn’t a deployment artifact, it is just a source file containing the security description
So now we have to go ahead and create an instance of XSUAA service
As everybody knows, it can be done in the cockpit (then point to this file) or on command line (and point to this file)
In my example, we jump into C:\tmp_faas_callsafe\safeapp and run the following command

cf cs xsuaa application xsuaaforsafetyapp -c xs-security-safe.json

1.2. Create Application

Now it is time to protect our created application
Sorry, my fault
I wanted to say:
Now it is time to create our protected application

We've already created the project structure, we only need to copy and paste the file contents from the appendix

As usual, the app does nothing.
Only be there
And be protected

So what we have to do:
In order to "be there" we have to do nothing
In order to “be protected” we have to do two things:

We have to “wish” that the caller has that scope when he or it calls our endpoint
We have to enforce that the caller has the "wished" scope

This is done manually by checking the scope and refusing the access to our endpoint
To manually check the scope, we have to do 2 things:

We have call a helper to do the work (check scope)
We have to act upon the result:
If we don’t like the result of the scope check, we say it

This has been confusing.
Let's try again:

The "passport" node module does the authentication check before our code is reached

const jwtStrategy = new JWTStrategy(xsuaaCredentials)

passport.use(jwtStrategy)

...

app.use(passport.authenticate('JWT', { session: false }));

The "passport" module itself is configured with specific xsuaa implementation for OAuth
As such, passport can check if a JWT token is present and if it is valid
Afterwards, our endpoint-implementation is invoked and we can check manually if the JWT token contains the scope that we wish.
We use a helper method for that check:

const fullScopeName = xsuaaCredentials.xsappname + '.scopeformysafety'

if(! req.authInfo.checkScope(fullScopeName)){

   return res.status(403).json({

      message: "We don't like the scopes in the JWT token"

Our error response is not polite, but clear

1.3. Deploy and Run the App

We create a manifest.yml file according to the appendix section.
It might be required to change the app name in the manifest, in case it is already taken

In the manifest, we declare that we want to bind the app to the instance of XSUAA service which we created above
Like that, our app has access to the XSUAA server which is necessary to protect our app with OAuth 2.0

We deploy the app to our SAP Cloud Platform space, located in the same subaccount like our serverless runtime instance

After deployment, we can try to invoke our endpoint in the browser

https://safetyapp.cfapps.eu10.hana.ondemand.com/securedEntry

The response is Unauthorized with status code 401
This response sounds quite polite, so it is not ours... it is provided by the FWK which we’ve used
Since we’ve invoked the endpoint in the browser, there’s no JWT token present at all, so our call is immediately rejected

1.4. Small Recap

We’ve created an instance of XSUAA service
We’ve configured it with our desired scope and grant
We’ve created an application with an endpoint, to be secured
We’ve bound it to the instance of XSUAA, such that XSUAA can help in protecting the app
In the code, we’ve added authentication and implemented authorization check

Part 2: The Calling Function

Now we’re coming to the main part of our tutorial:
How to access the secured app from within a function?

Basically, our function has to perform the OAuth flow.
It has to go to XSUAA and ask for a JWT token.
Then go to the safeguarded app and handover the token
And it has to pray that the token contains the required scope

Aha!

How to ensure that the JWT token contains the required scope?
Praying is good – but in this tutorial we’re learning the security mechanism

2.1. Security Configuration

We create an instance of XSUAA service, dedicated for our function.
Again, this xsuaa instance is configured with params stored in a json file.

The file is located in the working directory for the function unsafefunction and we name this file xs-security-faas.json, to make sure that we don’t mix it.

The content is copied from the appendix and looks like this:

{

  "xsappname" : "xsappforfaas",

  "tenant-mode" : "dedicated",

  "authorities":["$XSAPPNAME(application,xsappforsafeapp).scopeformysafety"]

}

The security configuration contains the essential line, to acquire the “authority”.
Basically, once created, the security artifact already HAS the authority “…scopeformysafety”, because it is GRANTED by the other XSUAA security artifact, the other xsapp
Remember the attribute grant-as-authority-to-apps
Nevertheless, the faas-xsapp has to explicitly "accept" the granted scope

The syntax:
$XSAPPNAME(<service_plan>,<name_of_foreign_xsapp>).<name_of_foreign_scope>

To create the XSUAA-instance for FaaS, we jump into the function folder unsafefunction and we execute the following command:

cf cs xsuaa application xsuaaforfaas -c xs-security-faas.json

As usual, in order to use it from FaaS, we need to create a service key:

cf csk xsuaaforfaas servicekeyforfaas

Of course, both can be done from the Cloud Cockpit, if you prefer:

First create the service instance of XSUAA, along with above JSON parameters
Then click on the new instance and create a service key with above name

2.2. Create Function

At this point, we’ve already learned everything we’re supposed to learn in this tutorial:
We’ve done the security configuration which allows to call an app from a function
We could say good-bye now, or good night… but that wouldn’t be good
So let’s quickly finish

2.2.1. Register Service Instance

We know how to use a service instance from FaaS: There are 2 ways, the second one is more comfortable: The service registration allows to store service credentials in FaaS itself
It can be done in Extension Center, but currently not all service types are supported.
So let's use the command line

First we do the login

xfsrt-cli login

Then we run the interactive service registration command

xfsrt-cli faas service register

When prompted, we choose the instance xsuaaforfaas from the list

Note:
If you don’t see it, although it is created and shown by the CF CLI, then you’ve probably forgotten to create a service key

After creation, we may view the content of the service key

cf service-key xsuaaforfaas servicekeyforfaas

2.2.2. Declare Usage

Once the service instance is registered in FaaS, we have to declare the usage of it in our faas project.
In faas.json, we need to reference the registered service by its guid
To get that guid, we ask the FaaS itself, with the command

xfsrt-cli faas service list -o yaml

The result of this command prints all registered services and additional information, like the guid:

Note:
The parameter -o yaml (alternatively, -o json) specifies the format of the output

We copy the guid from the service-section
In faas.json, we can now add the following section

  "services": {

    "regxsuaa":{

      "type": "xsuaa",

      "instance": "ab11ab11-ab11-ab11-ab11-ab11ab11ab11",

      "key": "servicekeyforfaas"      

    }

  }

Here we declare that in the project we're using that concrete registered service, and we assign a name to it

2.2.3. Declare Usage Usage

Next: declare the usage of the declared usage
In faas.json, we’ve declared the usage of the registered service and we’ve assigned an alias: “regxsuaa”
Now we can declare that our function declaration wants to make use of that registered service instance

  "functions": {

    "oauthcallerfun": {

      "module": "caller.js",

      "handler": "doCallProtectedSrv",

      "services": ["regxsuaa"]

    }

}

2.3. Implement Function

Coming to the function code, in folder
C:\tmp_faas_callsafe\unsafefunction\lib
and file
caller.js

High-level overview of what the code is doing:
Nothing

I mean, there’s nothing new in this section, the interesting trick, to get the scenario running, was in the configuration of the xsuaa.
So we can go ahead and copy the code from the appendix

Less-high-level overview:
It does nothing but executing the OAuth flow and calling our app (which does nothing)
It does nothing with the result, only return it

Detailed overview:

1. Access the registered service instance to obtain the credentials for XSUAA Authorization server

const xsuaaServiceKey = await context.getServiceCredentialsString('regxsuaa')	

const xsuaaCredentials = JSON.parse(xsuaaServiceKey)

const oauthUrl = xsuaaCredentials.url

const clientId = xsuaaCredentials.clientid

const clientSecret = xsuaaCredentials.clientsecret

2. Call the XSUAA server to get a JWT token

const jwtToken = await _fetchJwtToken(oauthUrl, clientId, clientSecret)

3. Use the JWT token to call the silly endpoint

const result = await _callEndpoint(jwtToken)

The implementation of this function is a normal request (using native module to avoid dependency)
The URL of the protected endpoint is hard-coded here

const options = {

   host: 'safetyapp.cfapps.eu10.hana.ondemand.com',

   path: '/secureEntry',

   headers: {

      Authorization: 'Bearer ' + jwtToken

   }

}		

https.get(options, res => {

   let response = ''

   res.on('data', chunk => {

      response += chunk

   })

   res.on('end', () => {

         resolve({message: `Function called protected service. Endpoint response: \n${response}`})

. . .

4. Get the response and return it

return result.message

2.4. Deploy and Run the Function

To deploy the function project we jump into folder C:\tmp_faas_callsafe\unsafefunction
and execute

xfsrt-cli faas project deploy

Afterwards, we can invoke the function via HTTP trigger.
The URL looks similar like this:

https://abc123-faas-http.tenant.eu10.functions.xfs.cloud.sap/callendpoint/

As a result, we get the response of our function which contains the response of our protected app

Summary

If an OAuth-and-scope-protected app should be called by a function (no user-login), two configuration steps are required:

The app has to explicitly “grant” the scope to the function

The function has to accept it

These configuration steps are done in the xs-security.json files of the 2 XSUAA instances

In this tutorial, we’ve learned how to protect an app with OAuth 2 and how to enforce a scope. And we’ve learned how to call such protected app from a serverless function

Quick Guide

An app that requires OAuth and scope, can allow to be accessed by other app (without user-login)
The xsappname of consuming app has to be entered

  "scopes": [{

      "grant-as-authority-to-apps" : [ "$XSAPPNAME(application, xsappforfaas)"]

An app or function that wants to call the protected (and granting) app, has to declare the access

"authorities":["$XSAPPNAME(application,xsappforsafeapp).scopeformysafety"]

Appendix: All Project Files

Here you can find all the code required for this tutorial, ready for copy&paste
You only need to adapt:
- the app name in the manifest
- the instanceID in the faas.json

For your convenience, see here the Project Structure again:

Part 1: The Protected App

These are the files of the app which provides an endpoint and which is called by the function
These files are located in the folder "safeapp"

xs-security-safe.json

{

  "xsappname" : "xsappforsafeapp",

  "tenant-mode" : "dedicated",

  "scopes": [{

      "name": "$XSAPPNAME.scopeformysafety",

      "grant-as-authority-to-apps" : [ "$XSAPPNAME(application, xsappforfaas)"]

  }]

}

manifest.yml

---

applications:

- name: safetyapp

  memory: 128M

  buildpacks:

    - nodejs_buildpack

  services:

    - xsuaaforsafetyapp

package.json

{

  "main": "server.js",

  "dependencies": {

    "@sap/xsenv": "latest",

    "@sap/xssec": "latest",

    "express": "^4.16.3",

    "passport": "^0.4.1"

  }

}

server.js

const express = require('express');

const passport = require('passport');

const xsenv = require('@sap/xsenv');

const JWTStrategy = require('@sap/xssec').JWTStrategy;



const xsuaaService = xsenv.getServices({ myXsuaa: { tag: 'xsuaa' }});

const xsuaaCredentials = xsuaaService.myXsuaa; 

const jwtStrategy = new JWTStrategy(xsuaaCredentials)

passport.use(jwtStrategy);



const app = express();

app.use(passport.initialize());

app.use(passport.authenticate('JWT', { session: false }));



// our protected endpoint

app.get('/secureEntry', function(req, res){       

   console.log('===> Endpoint has been reached. Authentication ok. Now checking authorization')



   const fullScopeName = xsuaaCredentials.xsappname + '.scopeformysafety'

   if(! req.authInfo.checkScope(fullScopeName)){

      return res.status(403).json({

         error: 'Unauthorized',

         message: "We don't like the scopes in the JWT token"

      })      

   }



   res.send('Successfully passed security control' );

});



// start server

app.listen(process.env.PORT, () => {})

Part 2: The Calling Function

These are the files required for the function
They are located in the folder "unsafefunction"

xs-security-faas.json

{

  "xsappname" : "xsappforfaas",

  "tenant-mode" : "dedicated",

  "authorities":["$XSAPPNAME(application,xsappforsafeapp).scopeformysafety"]

}

faas.json

{

  "project": "calloauth",

  "version": "0.0.1",

  "runtime": "nodejs10",

  "library": "./lib",

  "functions": {

    "oauthcallerfun": {

      "module": "caller.js",

      "handler": "doCallProtectedSrv",

      "services": ["regxsuaa"]

    }

  },



  "triggers": {

    "callendpoint": {

      "type": "HTTP",

      "function": "oauthcallerfun"

    }

  },

  "services": {

    "regxsuaa":{

        "type": "xsuaa",

        "instance": "ab12ab12-ab12-ab12-ab12-ab12ab12ab12",

        "key": "servicekeyforfaas"      

    }

  }

}

package.json

{}

caller.js

const https = require('https');



// main entry

const _faasHandler = async function (event, context) {



	const xsuaaServiceKey = await context.getServiceCredentialsString('regxsuaa')	

	const xsuaaCredentials = JSON.parse(xsuaaServiceKey)

	const oauthUrl = xsuaaCredentials.url

	const clientId = xsuaaCredentials.clientid

	const clientSecret = xsuaaCredentials.clientsecret	

	

	// call the target endpoint

	const jwtToken = await _fetchJwtToken(oauthUrl, clientId, clientSecret)

	const result = await _callEndpoint(jwtToken)

	

	return result.message

} 



const _fetchJwtToken = async function(oauthUrl, oauthClient, oauthSecret) {

	return new Promise ((resolve, reject) => {

	   	const options = {

		  	host:  oauthUrl.replace('https://', ''),

		  	path: '/oauth/token?grant_type=client_credentials&response_type=token',

		  	headers: {

			 	Authorization: "Basic " + Buffer.from(oauthClient + ':' + oauthSecret).toString("base64")

		  	}

	   	}

	   	https.get(options, res => {

		  	res.setEncoding('utf8')

		  	let response = ''

		  	res.on('data', chunk => {

				response += chunk

			})

			res.on('end', () => {

				try {

					const responseAsJson = JSON.parse(response)

					const jwtToken = responseAsJson.access_token            

					if (!jwtToken) {

						return reject(new Error('Error while fetching JWT token'))

					}

					resolve(jwtToken)

				} catch (error) {

					return reject(new Error('Error while fetching JWT token'))               

				}

			})

		})

	   .on("error", (error) => {

		  console.log("Error: " + error.message);

		  return reject({error: error})

	   });

	})   

 }

 

const _callEndpoint = async function(jwtToken){

	return new Promise((resolve, reject) => {

		const options = {

			host: 'safetyapp.cfapps.eu10.hana.ondemand.com',

			path: '/secureEntry',

			headers: {

				Authorization: 'Bearer ' + jwtToken

			}

		}		

		https.get(options, res => {

			res.setEncoding('utf8')

			let response = ''

			res.on('data', chunk => {

			  response += chunk

			})

			res.on('end', () => {

				const status = res.statusCode

				if(status < 400){

					resolve({message: `Function called protected service. Endpoint response: \n${response}`})

				}else{

					reject({error: {message: `Error calling endpoint with status ${status}`}})

				}

		  	})

		})

		.on("error", (error) => {

			reject({error: error})

		});		  

	})

}



// export the handler function with readable alias

module.exports = {

	doCallProtectedSrv : _faasHandler

}

Writing Function-as-a-Service [10]: Call protected endpoint across Subaccounts

2020-08-27T10:02:41+02:00

This blog is part of a series of tutorials explaining how to write serverless functions using the Functions-as-a-Service offering in SAP Cloud Platform Serverless Runtime

Quicklinks:
Quick Guide
Sample Code

Introduction

In the previous tutorial we‘ve learned how to call a service which is protected with OAuth and requires a scope.
The challenge was:
-> how can the function possess the scope?
The solution was:
-> configuration of both xs-security.json files

BUT:
There was a precondition:
-> both app and function have to live in the same subaccount

This is necessary because the central XSUAA of the subaccount creates one oauth-client for each instance and assigns the granted scope to the other client.
Thus, it has to resolve the names of the scope and involved clients
This is possible because the name of the scope is made unique and identifiable by adding the variable $XSAPPNAME to the scope name.
As we all know, the value of the variable is not just the same as the name of the property xsappname
The value of $XSAPPNAME is generated at runtime and contains some mystic suffix !t1234

OK.
Today we want to call from the function to a service which lives in a different subaccount.
So now, the XSUAA has to find not only the correct scope and oauth-client.
It has to find it in a different subaccount (identityzone)

How to do it?
-> communicate with the other central XSUAA

How to find that one?
-> By the unique identifier of the subaccount (identityzone)

As such, we have to add the subaccountID to the GRANT statement

And that’s already all for today

Nevertheless, let’s make it real

Overview

In this tutorial, we’re going to learn how to assign a scope to an application in a different subaccount

The scenario is almost the same as in the previous tutorial.
We can either re-use it and do the required little changes
Or create the project as described below, everything based on the previous blog

In the first part of this tutorial, we’re creating a very basic app which exposes an endpoint which is protected with OAuth and which requires a certain scope
In the second part, we’re creating a Function which tries to call that endpoint

Part 1: The Protected App
Create xsuaa, define scope
Create app, check scope

Part 2: The Calling Function
Create xsuaa, define authority
Create Function, do OAuth flow

Prerequisites

If you’re new to the topic, the previous tutorial is a prerequisite, along with all its prerequisites and blablabla

In addition:
To follow this tutorial, we need 2 different subaccounts.
In my example, I’m using my trial account, in addition to my FaaS-account (containing the instance of SAP Cloud Platform serverless runtime)
Limitation:
Both accounts have to live in the same data center (in my example, eu10)

Preparation: Create Project Structure

Same preparation like in previous blog: create files and folders

In addition:
We need to find the ID of the FaaS-subaccount.
It is easy to find: just open the subaccount in the cloud cockpit
Which subaccount?
We need the ID of the subaccount where the FaaS is located

Part 1: The Protected App

Almost same as part 1 of previous tutorial
Really only the xs-security.json file is little bit different

1.1. Security Configuration

This is the essential section of this tutorial:
Here we’re using the subaccount ID:
-> grant the scope to an oauth-client living in the specified subaccount

{

  "xsappname" : "xsappforsafeapp",

  "scopes": [{

      "name": "$XSAPPNAME.scopeformysafety",

      "grant-as-authority-to-apps" : [ "$XSAPPNAME(application, 12ab12ab-34cd-56ef-34cd-12ab12ab12ab, xsappforfaas)"]

  }]

}

Syntax:

"grant-as-authority-to-apps" : [ 

  "$XSAPPNAME(<service_plan>, <subaccount_id>, < xsappname_of_caller >)"

]

After clarifying the new security descriptor, we create an instance of XSUAA in our Trial account (or whatever account you’ve chosen)

We have to make sure that we're targeting the different account, e.g. trial
To change location:

cf t -o p123456trial

see:

OK, for your convenience, here's again the command to create a service instance:
In my example, we jump into C:\tmp_faas_callsafe\safeapp and run the following command

cf cs xsuaa application xsuaaforsafetyapp -c xs-security-safe.json

1.2. Create Application

No change needed to the app.
Just take the sample code (Part 1) from previous tutorial

1.3. Deploy and Run the App

Yapp, just deploy it to the different account.
No need to run it, we did it in the previous torture

1.4. Small Recap

We deploy a protected app to trial account.
We specify that the Function of FAC account is allowed to call us
So we add a statement to grant access to the calling xsapp
And here is the place to enter the ID of the FAC account

Part 2: The Calling Function

Again, all the same as in one of the other boring tutorials

2.1. Security Configuration

In part 1 we learned how to grant a scope to an xsuaa instance in a different subaccount
Now we’re on the receiving side: we receive the granted scope and we need to accept it
In the previous tutorial, we used the following statement:

"authorities":["$XSAPPNAME(application,xsappforsafeapp).scopeformysafety"]

Now we would need to make clear where to find that foreign xsapp
However, I haven’t found a way to add the subaccountID in this statement
OK, no prob.
-> we have to fall back to the generic statement:

"authorities":["$ACCEPT_GRANTED_AUTHORITIES"]

Using this statement, we accept all scopes granted by anybody to our app (xsapp, to be more precise)

So now we open the file xs-security-faas.json, in folder unsafefunction and enter the following content

{

  "xsappname" : "xsappforfaas",

  "tenant-mode" : "dedicated",

  "authorities":["$ACCEPT_GRANTED_AUTHORITIES"]

}

Note:
This statement doesn't apply only for different subaccounts, it can be used in any scenario

As usual. this JSON config can be used to create or update an instance of XSUAA.

Before executing a command, don't forget that this time, we have to make sure that we target the subaccount where FaaS is living

To create the XSUAA-instance for FaaS, we jump into the function folder unsafefunction then:

cf cs xsuaa application xsuaaforfaas -c xs-security-faas.json

And create a service key:

cf csk xsuaaforfaas servicekeyforfaas

BUT:
If you have the scenario in place, It is enough to update the existing service:

cf update-service xsuaaforfaas -c xs-security-faas.json

2.2. Create Function

All the same as in previous hands-on. It shouldn’t be necessary to do any change, register or deploy.
But it might be necessary to repeat steps, if the xsuaa instance was deleted, etc
Or to adapt the code, if the name of the protected app was changed in trial

Otherwise, we can just use the deployed function, if remaining from the previous blog

Or we create everything from scratch, based on the sample code Part 2

And then, finally, we invoke the function and are happy to see the same result which we had before
No shame to be happy:
We’ve learned the little trick which enables us to cross the borders of subaccounts

Summary

In this blog we’ve learned almost nothing
Just adding a cryptic guid in the middle of a cryptic statement
Luckily, the blog post hasn’t been too long…

Quick Guide

The protected app which is called by the Function has to grant the scope to the Function
If both are not located in the same subaccount, then the subaccountID of the Function has to be added (ID can be found in the cockpit)

xs-security.json of protected app:

"scopes": [{

      "name": "$XSAPPNAME.scopeformysafety",

      "grant-as-authority-to-apps" : [ 

         "$XSAPPNAME(application, 12345678-abcd-..., xsappforfaas)"

The calling Function has to accept the grant. In case of different subaccounts, the generic statement has to be used to accept all granted scopes

xs-security.json: of Function

"authorities":["$ACCEPT_GRANTED_AUTHORITIES"]

Links

Same as in previous tuutorial

Appendix: All Project Files

The whole project can be found in previous tutorial

However, we have to adjust the following files in both projects

Part 1: The Protected App

These files are located in the folder "safeapp"

xs-security-safe.json

{

  "xsappname" : "xsappforsafeapp",

  "tenant-mode" : "dedicated",

  "scopes": [{

      "name": "$XSAPPNAME.scopeformysafety",

      "grant-as-authority-to-apps" : [ 

         "$XSAPPNAME(application, 1a2b3c4d-0000-1111-aaaa-..., xsappforfaas)"

      ]

  }]

}

Part 2: The Calling Function

They are located in the folder "unsafefunction"

xs-security-faas.json

{

  "xsappname" : "xsappforfaas",

  "tenant-mode" : "dedicated",

  "authorities":["$ACCEPT_GRANTED_AUTHORITIES"]

}

SAP Cloud Platform [Extension Factory], serverless runtime | Function-as-a-Service | FaaS

2020-09-21T14:49:15+02:00

SAP Cloud Platform Extension Factory, serverless runtime

SAP Cloud Platform Serverless Runtime

SAP Cloud Platform Functions - Beta

Function-as-a-Service

FaaS

I'm confused...
What’s the difference?

To give a short answer: It’s all the same
(almost)
At the end, we can write some javascript code and it runs in a serverless environment

What is it, precisely?

It is a service offering in the SAP Cloud Platform, Cloud Foundry environment

But why that strange name?

While the name itself, Serverless Runtime, might still sound confusing, it makes more sense if we compare it to other “runtime” offerings in SAP Cloud Platform:

Application Runtime
The classic way of writing e.g. a java web application and deploying it to the cloud where it runs on classic java server with underlying JRE. The application developer takes care of operating and maintaining, etc.
Agree that these efforts are already less that in the even more classical onPrem world

Serverless Runtime
Here the developer doesn’t need to care about the runtime, meaning that he writes the code and the environment takes care about scaling etc just like it is expected of a serverless environment.
And, as expected, it causes cost only when running
This is the right choice for lightweight extensions, small portions of javascript code
It is nicely coupled with other offerings like Enterprise Messaging, Backend Service, OData Provisioning

Kyma Runtime
Bigger, more powerful, more flexible, more costly

While the Serverless Runtime is a "service" offering, it also provides a subscription-based tool:
The Extension Center

Nice, but where are the functions?

The screenshot helps us to understand:

The name "Serverless Runtime" is an umbrella for several capabilities that can be used to build serverless extensions.
Writing functions is only one of the capabilities, provided by "Serverless Runtime"
We don't see any "Function" in the Extension Center UI. Instead, a function project is called "Extension".

Why?

We understand that this is not a general worldwide FaaS technology product. Functions are meant to be part of a serverless extension scenario.
An extension scenario which is meant to be simple and still provides the possibility to write code.
And in fact: it is REALLY easy

Blablabla...

Really.
Try to imagine this example scenario:
Get notified about Backend changes with Enterprise Messaging
On every change, a Function is triggered
It can call an API with OData provisioning to get more details
The function can store data with Backend Service

Such a powerful extension scenario can be realized completely serverless, with few lines of code and little configuration
No local dev, no operation, no maintenance, no database trouble, no scaling headaches.
And at low cost, as everything has to be payed only when it does its work

OK, cool.
But what if the scenario grows and the offerings don't cover the required functionality?

In that case, the function can be easily and seamlessly migrated to Kyma

Sounds like a marketing slogan...

It can be easily proven:
Both Kyma and Functions have the same underlying technology (Kybernetes)

Cool, thanks

Cool, time to close the blog....

Ehmmm - didn't you forget anything?

Thank you for reading

Welcome. Missing info: which is the CORRECT name?

SAP Cloud Platform Serverless Runtime

Last question: how can we learn more?

This announcement blog gives an introduction and overview about Serverless Runtime
SAP Help Portal: Serverless Runtime official docu
Recommended series of tutorials which explain in detail how to implement functions

Thanks

Writing Function-as-a-Service [11]: How and Why access HTTP API

2020-10-15T09:57:49+02:00

This blog is part of a series of tutorials explaining how to write serverless functions using the Functions-as-a-Service offering in SAP Cloud Platform Serverless Runtime

Quicklinks:
Quick Guide
Sample Code

Introduction

In this blog we're talking about functions with HTTP trigger only. These are functions that are invoked with HTTP request.
In such scenarios, the function returns a value which ends up in the response body of the calling client (e.g. browser)
Sometimes, the function handler code needs more information that it gets from the FaaS runtime
Also, it may need to write custom info to the response

For these cases, the FaaS runtime allows access to the underlying native node.js HTTP API
For those of you who require such functionality, I’m providing a silly example, to make your life easier

First of all, 2 basic info that we have to understand:

In most cases, access to the underlying HTTP API is not needed.
As such, if we need it, we have to enable it
That’s done in faas.json, for each function definition

The underlying HTTP API is the standard node.js http module
As such, no special tutorial needed here, please refer to the standard documentation
Here: https://nodejs.org/api/http.html

And there’s one more basic info
We cannot mix both approaches
Either use the standard FaaS convenience methods OR use the HTTP API
With "FaaS convenience methods" I mean the following
Use return value to set the response:
return ‘Error, invalid function invocation’
Use convenience method to set the status
event.setUnauthorized()
With other words: if we want to add custom header to the response, we cannot use event.setUnauthorized() to set the status. We have to set the status with response.writeHead(400)

Overview

How to use HTTP API

Example use cases

Create sample function

Run sample function

Prerequisites

If you're new to Serverless Runtime, Function-as-a-Service, you should check out the overview of blogs and read all of them...

How to use HTTP API

First of all, the access to the API needs to be enabled.
This is done in a function definition in faas.json

"functions": {

   "function-with-httpapi": {

      "httpApi": true

Once enabled, the http property of event will be filled with request and response objects

module.exports = async function (event, context) {

    const request = event.http.request

    const response = event.http.response

The request object represents the class http.ClientRequest
and the response object the http.ServerResponse

And that's it about accessing the HTTP API

Example use cases

Now let's see why and how we might need to use it

A few example use cases where we need access to HTTP API:

HTTP method

Query parameters

Request Headers

Trigger name

Response Headers

Response Body

Response Status

HTTP method

Sometimes we need to know with which HTTP verb we've been invoked. For instance, if our function should distinguish between GET or POST, etc
We can throw an error, or react accordingly

const httpMethod = request.method

if (httpMethod != 'POST'){

    response.writeHead(405, {

        'Content-Type': 'text/plain',

        'Allow': 'POST'

    });

    response.write('Request failed. Method not allowed. See response headers for hint');

    response.end();

Query parameters

Query parameters are the params that can be added to a URL after the ?
Multiple parameters are appended with &
E.g.
xxxxx?customerName=otto&userid=123

They’re accessed via the query property

const name = event.http.request.query.customerName

It returns the value of the param

Request Headers

We can find the headers sent with the request in the headers property

request.headers

Trigger name

Two interesting headers are those provided by the FaaS runtime, giving info about the used trigger

const triggerName = request.headers['sap-faas-http-trigger-name']

const triggerPath = request.headers['sap-faas-http-trigger-path']

What is the difference?
/
Yes, the slash makes the path
In our example, the trigger name is customlogin and the path customlogin/

Response Headers

In case of response object, we're interested in modifying it.
For instance, we might want to send some additional information in the response header, as it might be required by the caller of our function
To add own headers to the response:

response.set('MyHeader', 'MyValue')



response.append('CustomHeader', 'CustomValue')

Alternatively, set multiple headers and status at once

response.writeHead(403, {

    'Content-Type': 'text/plain',

    'FailureHint': 'Authorization required, see docu'

});

Response Body

In most cases, we set the response body using the standard way in FaaS: as return value
However, we might need to switch to http API, due to requirements of caller who might need some custom text in the response body in case of failure, etc
If this is the case we can use standard way of http.ServerResponse class

response.write('Error. Don't ask admin. Don't see log for no info')

Note:
As mentioned, we cannot mix the used APIs.
If we set a header in the response, then we have to use this way of writing response

Response Status

There can be several reasons why we might wish to set the response status code.
For instance, if we don’t support all the HTTP methods, then we have to set the response status to 405, which means Method not allowed
Also, we might have special requirements to the incoming call, so we would have to decide on our own to set the status code to 400, Bad Request
Please see Links section for reference

Setting the response status code to a custom value can be again done in several ways

E.g. directly setting the property value:

response.statusCode = 405

Or again using the convenience method, where we can set a custom header at the same time:

response.writeHead(405, {

   'Content-Type': 'text/plain',

Create sample Function

To make things less theoretical, you can find here a reusable sample project, which is meant to showcase how the HTTP API can be used.
As usual, it is a small silly sample, without real use case, but focusing on demonstrating some capabilities for your convenience, so you can easily copy&paste and adapt for your own needs

Please refer to the Appendix for the full sample code

Note:
In case that it doesn’t suit your needs, you can send me a personal message

In this example, we’re simulating a kind of strange special login process for a customer app
The user of the function is required to pass a couple of pieces of login information:

Customer Name as query param
Customer Password as request header
Authorization scope as body in a POST request
As such, only POST is supported
In addition, our function simulates usage of multiple endpoints and only one of them is meant for productive usage with login
As such, the function code has to access request header to determine the used trigger

Code walkthrough

Our function does nothing than accessing the HTTP API and using it for some login-checks
In case of success, it does nothing, just return some silly text

Preparation

First we declare the usage of the HTTP API in faas.json

"functions": {

   "function-with-httpapi": {

      "httpApi": true

Then we can access the HTTP API in function code.
Otherwise, the object would be empty

const request = event.http.request

const response = event.http.response

Now, in our function, we can implement custom checks which wouldn't be possible without the HTTP API.
Our function contains 4 checks:

1. Check for correct HTTP verb:

const httpMethod = request.method

if (httpMethod != 'POST'){

    response.writeHead(405, {

        'Content-Type': 'text/plain',

        'Allow': 'POST'

    });

    response.write('Request failed. Method not allowed. See response headers for hint');

2. Check for desired productive endpoint

In faas.json we’ve defined 2 triggers.
The only reason for the second one (nologin) is to be able to run this check

const triggerName = request.headers['sap-faas-http-trigger-name']

if(triggerName != 'customlogin'){

    response.statusCode = 400

3. Check for authentication

Note that we don’t verify the customer name, only password – for the sake of simplicity
We need to access the request header

const customerAuth = request.headers['customer-auth']

if(! customerAuth){

    response.writeHead(401, {

        'Content-Type': 'text/plain',

        'FailureHint': 'Required: request header customer-auth containing customer password'

    });

4. Check scope

We use this to show how to access the request body

if((! request.body) || (JSON.parse(request.body).customerAccess != 'true')){

    response.writeHead(403, {

        'FailureHint': 'Authorization required...'

Success response

If the request has passed all checks, then we do nothing,
Just note that here we’re using the standard way of using a function:
The response body is sent as return value of the function
When I mentioned earlier that we cannot mix the HTTP API with standard API, I meant we cannot mix in one response definition. But here, in case of success, we don't do any custom header setting, etc, so we can just return a text

const customerName = request.query.customerName 

return `Function called successfully. Customer '${customerName}' is welcome.`

Run the sample Function

Let's deploy and run the sample action, to see our HTTP API implementation in action
After deploy, we want to see if your checks are executed properly and if we get the expected results in response body , status and header

➡️1. Wrong HTTP verb

In our first example, we choose to use a wrong HTTP method, to see our first check working

Request
URL	https://...faas.../customlogin/
Verb	GET
Header	-
Body	-
Response
Body	Error text
Status	405
Header	allow

See result:

➡️2. Wrong endpoint

Now we use the correct HTTP method, but the wrong trigger

Request
URL	https://...faas.../nologin/
Verb	POST
Header	-
Body	-
Response
Body	Error text
Status	400
Header	-

See result:

➡️3. Missing authentication

Next try: correct endpoint, but we don't send the required authentication data

Request
URL	https://...faas.../customlogin/
Verb	POST
Header	-
Body	-
Response
Body	Error text
Status	401
Header	failurehint

See result:

➡️4. Missing authorization

We send a request with mostly correct settings, only the scope, to be passed in the request body, is missing

Request
URL	https://...faas.../customlogin/
Verb	POST
Header	customer-auth : abc123
Body	-
Response
Body	Error text
Status	403
Header	failurehint

See result:

➡️5. Successful call

Finally we send a request with correct settings, including the name parameter in the URL

Request
URL	https://...faas.../customlogin/?customerName=otto
Verb	POST
Header	customer-auth : abc123
Body	{ "customerAccess" : "true" }
Response
Body	Success text
Status	200
Header	-

See result:

Summary

In this tutorial, we’ve learned which steps are required to access the HTTP API
This is probably not necessary in most use cases of serverless function
But sometimes it required, so we need to know how it works

We've learned that we need to enable it first in faas.json
Then we can access it via the event.http property
And we've understood that we can use the standard node.js http methods

Quick Guide

faas.json:

"my-function": {

   "httpApi": true

Function code:

const request = event.http.request

const response = event.http.response

Appendix: All Project Files

Here you can find the project files used for the sample, ready for copy&paste

faas.json

{

  "project": "httpapiproject",

  "version": "1",

  "runtime": "nodejs10",

  "library": "./src",

  "functions": {

    "function-with-httpapi": {

      "module": "mymodule.js",

      "httpApi": true

    }

  },

  "triggers": {

    "customlogin": {

      "type": "HTTP",

      "function": "function-with-httpapi"

    },

    "nologin": {

      "type": "HTTP",

      "function": "function-with-httpapi"

    }

  }

}

package.json

Adding dev dependency for local testing

{

  "devDependencies": {

    "@sap/faas": ">=0.7.0"

  }

}

mymodule.js

module.exports = async function (event, context) {



    // to access HTTP API, add param to function definition in faas.json: "httpApi": true

	const request = event.http.request

	const response = event.http.response

    

    // check request method

    const httpMethod = request.method

    if (httpMethod != 'POST'){

        response.writeHead(405, {

            'Content-Type': 'text/plain',

            'Allow': 'POST'

        });

        response.write('Request failed. Method not allowed. See response headers for hint');

        response.end();

        return

    }



	// check which HTTP trigger was used

    const triggerName = request.headers['sap-faas-http-trigger-name']

    if(triggerName != 'customlogin'){

        response.statusCode = 400

        response.write("Endpoint not supported. Use 'customlogin' endpoint")

        response.end();

        return

    }



	// check authentication via request header

    const customerAuth = request.headers['customer-auth']

    if(! customerAuth){

        response.writeHead(401, {

            'Content-Type': 'text/plain',

            'FailureHint': 'Required: request header customer-auth containing customer password'

        });

        response.write('Request failed. Unauthorized. Customer login data missing. See hint for more info');

        response.end();

        return

    }



    // check authorization via request body 

    if((! request.body) || (JSON.parse(request.body).customerAccess != 'true')){

        response.writeHead(403, {

            'Content-Type': 'text/plain',

            'FailureHint': 'Authorization for customer required: Request body with customer JSON access must be true'

        });

        response.write('Request failed. Forbidden. Customer authorization not sufficient. See hint for more info');

        response.end();

        return    

    }



    // use standard way of writing response

    const customerName = request.query.customerName 

    return `Function called successfully. Customer '${customerName}' is welcome.`

};

Writing Function-as-a-Service [13]: Secure scenario with scope and consumer

2020-10-29T15:06:37+01:00

This blog is part of a series of tutorials explaining how to write serverless functions using the Functions-as-a-Service offering in SAP Cloud Platform Serverless Runtime

Quicklinks:
Quick Guide
Sample Code

Introduction

In the previous blog we’ve learned the basics about protecting a function with OAuth
What we didn’t learn: our function didn’t require a scope
In this blog, let’s learn how to enforce a scope in the JWT token and
- assign the scope to our user and call the function (REST client)
- call the function from a client application (node.js)

Overview

Small recap:
In the previous tutorial, we’ve created a very silly small function and we’ve used framework functionality to protect it with small configuration snippet.
Furthermore, we created a very basic instance of XSUAA and connect the function to it
That was enough to protect our function with OAuth 2.0
The FaaS Runtime took care of rejecting HTTP requests which didn't send a valid JWT token
The FaaS Runtime used the connected XSUAA instance for validation
That was OK.
Fair enough for the beginning
Now, in today's tutorial we’re going to
- add a scope
- and in the function we check if the scope exists in the JWT

These are the steps we're going to cover:

Create XSUAA

Create Function
Implement scope check

Call Function in user centric scenario

Call Function with client app

Prerequisites

Basic understanding of OAuth, see easy intro and description for using REST client

Previous blog

HTTP API blog post

1. Create Instance of XSUAA

We need an instance of XSUAA which is configured with a scope
We can update the existing one, or create a new one
In my example, I create a new instance with the following security configuration in a file called xs-security_faas_scope.json

{

  "xsappname" : "xsappforfaaswithscope",

  "tenant-mode" : "dedicated",

  "scopes": [

    {

      "name": "$XSAPPNAME.scopeforfunction",

      "description": "Scope required for accessing function"

    }

  ],

  "role-templates": [ { 

    "name"                : "FunctionRoleTemplate", 

    "description"         : "Role for serverless function", 

    "default-role-name"   : "RoleForFunction",

    "scope-references"    : ["$XSAPPNAME.scopeforfunction"]

  }],

  "authorities":["$XSAPPNAME.scopeforfunction"]

}

Explanation:

scopes
We define a scope.
For us, thie means: when calling the function, a JWT token is not enough. The caller must have the scope. If yes, the scope is contained in the token
However, in the security configuration we only define the scope, such that XSUAA knows about it
If things go well (see below) XSUAA will issue a JWT token that contains the scope
However, XSUAA doesn't enforce the scope.

role-templates
A scope is nothing that can be assigned to a human user. For that, we need to define a “role”, along with “role-template”. That can be found in the Cloud Cockpit and an admin can assign the role to users

authorities
This attribute is meant for non-human users, for client apps, in a client-credentials scenario
With this statement, we accept that scope. A client application bound to XSUAA will get the scope in the JWT token

Create XSUAA

We create an instance of XSUAA and we use above JSON parameters
Can be done in the Cloud Cockpit, or on command line:

cf cs xsuaa application xsuaa_faas_scope -c xs-security_faas_scope.json

Create Service Key

As usual, we need a service key in order to reference it from FaaS and also from REST client (see below)

cf csk xsuaa_faas_scope xsuaa_faasscope_servicekey

See Appendix for all commands

2. Create Function

After creating an instance of XSUAA service, we need to register it in FaaS, and use it in the function definition.
We’ve learned that in a previous tutorial

Register the service in faas

For your convenience, find here the necessary commands

Always need to login first to Cloud Foundry and/or FaaS client

xfsrt-cli login

The convenient command to register a service interactively (the command line client will propose existing services, so we can choose. Precondition: only service instances with service key are proposed)

xfsrt-cli faas service register

After registration, in the console, we get the info which we need to specify in faas.json:
the service key and the GUID of the service instance

Use the service in FaaS project

faas.json

    "services": {

        "xsuaa-with-scope": {

            "type": "xsuaa",

            "instance": "<your GUID of service instance>",

            "key": "xsuaa_faasscope_servicekey"         

        }

    }

See Appendix for full faas.json

Configure Security

As learned in previous blog post, with below setting, we tell the FaaS runtime that we want them to enforce a valid JWT token

"triggers": {

   "prot": {

      "type": "HTTP",

         "function": "prot-func-with-scope",

            "auth": {

               "type": "xsuaa",

               "service": "xsuaa-with-scope"

Enforce scope

As mentioned earlier: the above setting will have the following consequence:

Whenever our function is called with HTTP trigger, the request must contain a valid JWT token
Otherwise the call is rejected by the FaaS runtime (with proper status code and error message) and our function code is not even invoked.

As such, the FaaS runtime enforces the authentication.
But it cannot take care of authorization in a generic way

For example, a function might have the following logic:
If EDIT scope is available, the function may accept POST requests, otherwise only GET
Such logic has to be implemented manually by us

We have to look into the JWT token, read the available scopes and check if the one which we require, is there.
The framework offers a convenience method which decodes the JWT token (if available)
We can then access the JWT payload as JSON object

const jwtToken = event.decodeJsonWebToken()

const jwtScopes = jwtToken.payload.scope

In order to check the scope, we need to know the exact scope name.
Background:

We defined the scope name as
$XSAPPNAME.scopeforfunction
The value of the variable $XSAPPNAME is generated on the cloud platform, as such we have to ask at runtime for the exact value.
The exact value is contained in the service key
And the service key is registered in FaaS
As such, we can ask FaaS for the xsuaa service
Then access the xsappname property

const xsuaaCredentials = await context.getServiceCredentialsJSON('xsuaa-with-scope')

const requiredScope = xsuaaCredentials.xsappname + '.scopeforfunction'

Based on above 2 code snippets we have the needed information:
Which scope do we expect (for whatever business case)
Which scope is contained in the JWT token

In our example, we require a scope for calling the function.
To check if the scope is sent, we just look into the array of available scopes
If not available, we reject the request.
In our case, the correct status code is 403, because use is authenticated, but lacking authorization
In order to set the status, we need to use the HTTP API (see previous blog post)

Below snippet puts the snippets together:

const xsuaaCredentials = await context.getServiceCredentialsJSON('xsuaa-with-scope')

const requiredScope = xsuaaCredentials.xsappname + '.scopeforfunction'



// read the JWT token and check required scope

const jwtToken = event.decodeJsonWebToken()

const jwtScopes = jwtToken.payload.scope

if(! jwtScopes.includes(requiredScope)){

   // fail with 403       

   const response = event.http.response // must be enabled in faas.json

   response.writeHead(403, {

   ...

See Appendix for full sample code

Note:
Before using the HTTP API, it must be enabled, which is done in the faas.json

Note:
SAP provides security libraries and there’s a little helper function, recommended to use for the scope check
The function I’m talking about:
@Sap/xssec: checkScope(scope)
Please refer to Links section
In my examples, I’d like to keep the code free from dependencies (as there might be changes, etc), so I’m not using it. Please forgive
But for your convenience, I've created little sample code based on the library. See Appendix

Deploy function

To deploy the function, you might find this command useful (run from project directory)
xfsrt-cli faas project deploy

3. Call function in user centric scenario

After deploy, we want to test the security of our function

If we call the function in browser –> error
Reason: no JWT token at all

If we call the function in REST client with OAuth flow –> error
Reason: JWT token available, but doesn't contain the required scope

Solution: To call the function we need to assign the required role to our user

The Role

In Cloud Foundry, authorization is controlled by means of Role Based Access Control (RBAC)
In the first step, we created an instance of XSUAA, based on a security configuration which defined a scope and a role-template.
After creating our instance of XSUAA, our role-definition has been added to the list of roles in the cockpit.
We can view it there

But viewing is not enough, we have to add the role to our user.

Assign Role to User

First, we create a new Role Collection, dedicated for your function
In the Cockpit, go to your subaccount->Security-> Role Collections

Second, we have to add the desired role to the new Role Collection
So we “edit” the new role collection and add our new role
Then press “save”

Third, we need to add our Role Collection to the Identity Provider (IDP)
Go to menu entry Trust Configuration
Click on default IDP
Enter the E-Mail Address of your user
Click “show Assignments”
Then “Assign Role Collection”

Test the function with human user

Now that our user has the required role, we can call the function
We don’t have a user interface in our scenario, so we use a REST client
See here for a detailed description about how to call an OAuth protected endpoint with REST client

Short description:
1. fetch a JWT token
2. Use token when calling our function

In my example, I’m using Postman which helps to do both steps in one request
To configure postman request, we need to view the service key of our xsuaa instance which we created above
To view the service key, we can use the following command (alternatively, use cockpit)

cf service-key xsuaa_faas_scope xsuaa_faasscope_servicekey

Back in Postman, we have to configure the request as follows

Method: GET
URL: The endpoint of our function, we get the info during deploy, or with xfsrt-cli faas project get
e.g. https://...-faas.....functions.xfs.cloud.sap/prot/
Don’t forget the slash at the end

Authorization: Oauth 2.0
Access Token:
press "Get new Access Token"
"Get Access Token" Dialog:
Grant Type: Password Credentials
Access Token URL: we copy the “url” property from the service key and append /oauth/token
Example: https://<subaccount>.authentication.....hana.ondemand.com/oauth/token
Username: <your cloud user>
Password: <your cloud user password>
Client ID: copy the value of property clientid from service key
Client Secret: copy the value of property clientsecret from service key
Client Authentication: choose "Send as Basic Auth header"

Then press “Request Token” on the dialog
After getting the token response, press “Use Token”
Then, back in the main Postman window, press “Send” to send the request to the Function endpoint

As a result, we get our success message, which proves that the scope was included in the JWT token

Now we want to do the negative test, to check our function implementation works correctly and if the correct status code is sent
To do so, we have to remove the role from our user.
We can simply unassign the role collection in the "Trust Configuration"
Afterwards, we need to fetch a new JWT token via “Get New Access Token”
Then send the request again to call the function without scope

The result is 403, as coded by us, and the response message shows that the scope is not contained in the JWT token

Note:
In this scenario, we’re using only one instance of XSUAA
The function uses an instance of XSUAA to protect its endpoint
The user who calls the function, uses the same ClientID to call the function
This is OK, because we as developers of the function trust our user
In case that 2 instances of XSUAA are required, please refer to this blog for more information

4. Call function in client credentials scenario

Now we want to call the protected function from an application
Again, we’re using only one instance of XSUAA.
We bind our application to the same instance which is used to protect the function
(Sure, in a future blog, we’ll describe a scenario with different XSUAA instances)

In client credentials scenario, we may wonder: how to assign the required scope to the calling app?
We cannot assign it in the cockpit like we did for our (human) user.
To answer this question, somebody wrote this useful blog post

Our example is a bit different from above blog post, because both the function and the client app are "bound" to the same instance of XSUAA
The solution in our example:
When creating an instance of XSUAA, we defined a parameter called authorities
This is interesting and might be a new learning for us:
The function is attached to the XSUAA instance and the client app is bound to the same instance
As such, we would expect that the xsuaa instance (== OAuth client) trusts itself, because it is the same instance
In fact, trust is there. But the scope is not automatically there
In a client-credentials scenario, the scope must be explicitly granted, just like we assign a role to a user
To assign the scope to the client itself, no “grant” statement is required, but the authorities statement is necessary
This statement declares: our application wants to take the scope

"authorities":["$XSAPPNAME.scopeforfunction"]

Create Client app

The only intention of our app is to call the function – and to send a JWT token which contains the required scope
Well... we’ve just learned how to get the required scope into the JWT token
Nothing special needs to be done in the app code
Just fetch a JWT token and then call the function
So we can skip explanations.
We can go ahead and copy the code from the Appendix

Note:
Don’t forget to replace the FUNC_HOST URL with the URL of your function

Note:
You might need to change the app name in the manifest.yml

Then deploy the clientapp with cf push
Finally, invoke the endpoint of our function caller app and hope to get a success message
http://functioncallerapp.cfapps.sap.hana.ondemand.com/call

To test the negative scenario, we have to remove the authorities statement from our xs-security_faas_scope.json file and then execute an update-service command in Cloud Foundry

cf update-service xsuaa_faas_scope -c xs-security_faas_scope.json

Note:
Instead of deleting the “authorities” statement, we can invalidate it by changing the name of the scope to anything non-existing
e.g.
"authorities":["$XSAPPNAME.scopeforfunctionXX"]

In fact, after running update-service, we can invoke our endpoint again and we get the expected error message:
It says that the function responded with 403, which was expected

Summary

We’ve learned that the FaaS runtime uses XSUAA for token validation, there’s no automatic check of available scopes
To manually check the available scopes, we can access the decoded JW T token
We need to access the scope prefix from xsuaa service key
In client-credentials scenario, we need to use the authorities statement to assign the scope to ourselves

Quick Guide

Few Code snippets

// access registered xsuaa service in order to get the value of variable $XSAPPNAME

const xsuaaCredentials = await context.getServiceCredentialsJSON('xsuaa-with-scope')

const requiredScope = xsuaaCredentials.xsappname + '.scopeforfunction'



// the decoded JWT token

const jwtTokenDecoded = event.decodeJsonWebToken()



// the raw JWT token

const jwtTokenRaw = event.auth.credentials

Appendix 1: Console Commands

cf cs xsuaa application xsuaa_faas_scope -c xs-security_faas_scope.json

cf csk xsuaa_faas_scope xsuaa_faasscope_servicekey
cf service-key xsuaa_client xsuaa_client_servicekey

cf update-service xsuaa_faas_scope -c xs-security_faas_scope.json

xfsrt-cli login

xfsrt-cli faas service register

xfsrt-cli faas project deploy

xfsrt-cli faas project get

xfsrt-cli faas project logs

Appendix 2: All sample project files

For your convenience, I'm pasting the structure of my example project.
Folder names can be changed

Protected Function

These are the files required for the function
They are located in the function project folder, with "lib" subfolder

xs-security_faas_scope.json

{

  "xsappname" : "xsappforfaaswithscope",

  "tenant-mode" : "dedicated",

  "scopes": [

    {

      "name": "$XSAPPNAME.scopeforfunction",

      "description": "Scope required for accessing function"

    }

  ],

  "role-templates": [ { 

    "name"                : "FunctionRoleTemplate", 

    "description"         : "Role for serverless function", 

    "default-role-name"   : "RoleForFunction",

    "scope-references"    : ["$XSAPPNAME.scopeforfunction"]

  }],

  "authorities":["$XSAPPNAME.scopeforfunction"]

}

faas.json

{

	"project": "protectedwithscope",

	"version": "0.0.1",

	"runtime": "nodejs10",

	"library": "./lib",

    "functions": {

        "prot-func-with-scope": {

			"module": "functionImpl.js",

			"httpApi": true,

			"services": ["xsuaa-with-scope"]

        }

    },

    "triggers": {

        "prot": {

            "type": "HTTP",

            "function": "prot-func-with-scope",

			"auth": {

				"type": "xsuaa",

				"service": "xsuaa-with-scope"

			}			

		}

	},

	"services": {

	    "xsuaa-with-scope": {

			"type": "xsuaa",

			"instance": "d8819eda-41e6-40b0-9286-0afa1a59d12c",

			"key": "xsuaa_faasscope_servicekey"			

		}

	}

}

package.json

{}

functionImpl.js

module.exports = async function (event, context) {  	

	// access registered xsuaa service in order to get the value of variable $XSAPPNAME

	const xsuaaCredentials = await context.getServiceCredentialsJSON('xsuaa-with-scope')

	const requiredScope = xsuaaCredentials.xsappname + '.scopeforfunction'



	// read the JWT token and check required scope

	const jwtToken = event.decodeJsonWebToken()

	const jwtScopes = jwtToken.payload.scope

	if(! jwtScopes.includes(requiredScope)){

		// HTTP API required for configuring response

		const response = event.http.response // must be enabled in faas.json

		response.writeHead(403, {

			'Content-Type': 'text/plain'

		});

		response.write(`Unauthorized: required scope '${requiredScope}' not found in JWT. Availbale scopes: '${jwtScopes}' ;-(`);

		response.end();

	} else{

		return `Reached protected function. Scope check successful: required scope '${requiredScope}' found in JWT. Availbale scopes: '${jwtScopes}'`

	}

}

Function Caller Client App

These are the files required for a little node.js app which calls the protected function
Make sure to adapt the URL of the function in the application code

manifest.yml

The application is bound to the same instance of XSUAA which we registered in FaaS

---

applications:

- name: functioncallerapp

  memory: 128M

  buildpacks:

    - nodejs_buildpack

  services:

    - xsuaa_faas_scope

server.js

const express = require('express')

const app = express()

const https = require('https');



const VCAP_SERVICES = JSON.parse(process.env.VCAP_SERVICES)

const CREDENTIALS = VCAP_SERVICES.xsuaa[0].credentials

//oauth

const CLIENTID = CREDENTIALS.clientid; 

const SECRET = CREDENTIALS.clientsecret;

const OAUTH_HOST = CREDENTIALS.url;



const FUNC_HOST = 'https://abcd1234-...-...-faas-...-functions.xfs.cloud.sap' // adapt URL

const FUNC_TRIGGER = 'prot'





app.get('/call', function(req, res){       

   // call function endpoint 

   doCallEndpoint(FUNC_HOST, FUNC_TRIGGER, OAUTH_HOST, CLIENTID, SECRET)

   .then((response)=>{

      res.status(202).send('Successfully called remote endpoint. Function response: ' + response);

   }).catch((error)=>{

      res.status(500).send(`Error while calling remote endpoint: ${error} `);

   })

});





// helper method to call the endpoint

const doCallEndpoint = function(host, endpoint, token_uri, client_id, client_secret){

   return new Promise((resolve, reject) => {

      return fetchJwtToken(token_uri, client_id, client_secret)

         .then((jwtToken) => {

            const options = {

               host: host.replace('https://', ''),

              path:  `/${endpoint}/`,

               method: 'GET',

               headers: {

                  Authorization: 'Bearer ' + jwtToken

               }

            }

            

            const req = https.request(options, (res) => {

               res.setEncoding('utf8')

               const status = res.statusCode 

               const statusMessage = res.statusMessage               

               let response = ''

               res.on('data', chunk => {

                  response += chunk

                })

                

               res.on('end', () => {

                  if (status !== 200 && status !== 201) {

                     return reject(new Error(`Failed to call function. Message: ${status} - ${statusMessage} - ${response}`))

                  }

                  resolve(response)

               })

            

            });

            

            req.on('error', (error) => {

               return reject({error: error})

            });

         

            req.write('done')

            req.end()   

      })

      .catch((error) => {

         reject(error)

      })

   })

}



// jwt token required for calling REST api

const fetchJwtToken = function(token_uri, client_id, client_secret) {

   return new Promise ((resolve, reject) => {

      const options = {

         host:  token_uri.replace('https://', ''),

         path: '/oauth/token?grant_type=client_credentials&response_type=token',

         // path: '?grant_type=client_credentials&response_type=token',

         headers: {

            Authorization: "Basic " + Buffer.from(client_id + ':' + client_secret).toString("base64")

         }

      }



      https.get(options, res => {

         res.setEncoding('utf8')

         let response = ''

         res.on('data', chunk => {

           response += chunk

         })



         res.on('end', () => {

            try {

               const jwtToken = JSON.parse(response).access_token                

               resolve(jwtToken)

            } catch (error) {

               return reject(new Error('Error while fetching JWT token'))               

            }

         })

      })

      .on("error", (error) => {

         return reject({error: error})

      });

   })   

}



// Start server

app.listen(process.env.PORT || 8080, ()=>{})

package.json

{

  "dependencies": {

    "express": "^4.16.3"

  }

}

Appendix 3: Sample code using @Sap/xssec

package.json

{

    "dependencies": {

        "@sap/xssec": "latest"

    }

}

functionImpl.js

const xssec = require('@sap/xssec')

const util = require('util');

const createSecurityContext = util.promisify(xssec.createSecurityContext);



module.exports = async function (event, context) {  	

	// access registered xsuaa service in order to get the value of variable $XSAPPNAME

	const xsuaaCredentials = await context.getServiceCredentialsJSON('xsuaa-with-scope')

	const requiredScope = xsuaaCredentials.xsappname + '.scopeforfunction'



	const jwtTokenRaw = event.auth.credentials

	const securityContext = await createSecurityContext(jwtTokenRaw, xsuaaCredentials)

	const jwtScopes = securityContext.getTokenInfo().getPayload().scope



	if(! securityContext.checkScope(requiredScope)){

		// HTTP API required for configuring response

		const response = event.http.response // must be enabled in faas.json

		response.writeHead(403, {

			'Content-Type': 'text/plain'

		});

		response.write(`Unauthorized: required scope '${requiredScope}' not found in JWT. Availbale scopes: '${jwtScopes}'`);

		response.end();

	} else{

		return `Reached protected function. Scope check successful: required scope found in JWT. All availbale scopes: '${jwtScopes}'`

	}

}

Making your SAP Integration Serverless

2021-03-05T20:29:57+01:00

Growing demands of rapid digital interactions and expanding the ecosystem means IT departments will need to spend more time eliminating silos, bridging between services. While handling the ever complex, immense amount of data in real-time. Also trying to bring the new service to the market at an expedited speed. But also with cost, and good resource management in mind.

This drives a drastic change to how systems are interconnected. From JUST API calls to more scalable event-driven architecture. Development style has gone from heavy service oriented to small quick turn around snippets of code. With a Serverless platform, it can help lowering the operation cost and reduce packaging and deployment complexity.

SAP being a world's leading enterprise business processing solution. There is always going to be a need to connect an organization's core to other SaaS offering, partners or even another SAP solution. Red Hat Integration offers flexibility, adaptability, and ability to move quickly with framework and software to build the event-driven integration architecture. Not just connect, but also maintain data consistency across platforms.

An Architectural Overview

This is how Red Hat Integration can help to achieve modernized integration with SAP.

SAP exposes business functionality through the Netweaver Gateway. Camel K or Camel in RHI can be used by developers to integrate(bi-directional) these functionalities. Camel K/Camel not only connects the dot, but also provides a set of built-in patterns and data transformations components making customized integration easy. They can be deployed in the form of a serverless function, serverless source/sink, or a long running microservice.

At the time of writing, I don’t see a complete support from SAP event enhancements, developers do still require to retrieve real data via other methods such as through OData and APIs. To implement a true event driven architecture, AMQ Streams (Kafka) can be used as the event stream store to handle streaming of events, for reducing decoupling and achieving near real-time latency.

Since the system is based on events, we can also capture changes of data state in Databases using Debezium. Keeping all data consistent by passing the updated state back to SAP.

When there is a need to expose any functions or services as API endpoints, we can easily implement it with Camel using the OpenAPI Standard Specification. And have the API managed and secured by the 3scale API management platform.

Openshift as the platform that can run on major cloud vendors and on-prem, so it’s truly cloud agnostic. It provides a serverless platform to deploy and manage all functions. And with Interconnect we will be able to broadcast events, to the closest data center to optimize traffic control.

As a result, it is now ready to connect to endless 3rd party and partner services, streaming large amounts of edge signals and providing real-time processing from edge devices. Legacy, mainframe systems can also be part of the ecosystem. Lastly, this is a good tool for SAP to SAP integration too.

Technical Dive

Connect with Camel

SAP offers interfaces such as OData v4, OData v2, RESTful API and SOAP as the HTTP based one, or you can also use the classic RFC(remote procedure call) and iDoc Messages. And there is a recent event enablement add-on that offers AMQP and MQTT protocol.

The Camel feature in RHI allows you to seamlessly connect to any of your preferred protocols. Developers can simply configure to connect to the endpoints with it’s address, credential and/or SSL settings.

Example:

Camel code connecting to OData v4 (Olingo4 components)

.to("olingo4://read/SalesOrder")

[NOTE]: https://camel.apache.org/components/latest/olingo4-component.html

Camel code connecting to Restful API

.to("http://demo.sap.io/SalesOrder")

[NOTE]: https://camel.apache.org/components/latest/http-component.html

OData v4, RESTful API and Events protocols are better suited for Serverless. As OData v4 has significant performance over the older version, and support for analytical application. Whereas OData v2, RFC and iDoc are better used in traditional Camel Project.

What Components to use for SAP endpoints.

	Serverless Camel K/Camel Quarkus	Camel
OData V4	✓	✓
OData V2	✕	✓
Restful API	✓	✓
SOAP	O	✓
RFC/IDoc	✕	✓
Events	✓	✓

After receiving the payload, Camel can then use the built-in data format components to transform it. In the serverless case, data is mostly in the form of JSON. By marshal and unmarshalling incoming payload, we can easily access the value and retrieve the content we need from the payload.

Example:

.marshal().json().

.to("kafka:mytopic")

[NOTE: https://camel.apache.org/manual/latest/json.html]

For syntax mapping between incoming and outgoing payload, there is visual tooling for you to design the mapping, and run that data mapping via Camel Engine.

[NOTE: https://www.atlasmap.io/]

Utilize the useful pattern in Camel, they are a straight implementation from Enterprise Integration Pattern, which organize and define the most used pattern and behaviour of integration applications.

Example:

Split streams by and split with token “,”.

.split(body().tokenize(",")).streaming()

.to("knative:mychannel")

[NOTE] (https://camel.apache.org/components/latest/eips/split-eip.html)

Flexible workload with Red Hat Serverless

There aren’t many things Camel K developers need to worry about when converting the long running application “Serverless”. First thing you have to do is make sure Red Hat Serverless is installed on the OpenShift platform (Should be done by the platform admin). And you are ready to go.

Camel K will detect if Serverless is available, and create the services needed for serverless. But there are two aspects of Serverless that you might want to take a closer look at.

AutoScaling setup

You can scale the replicas for an application/function to closely match incoming demand. When the administrator sets up the cluster for Serverless, they would already have configured the autoscaler to apply globally to the cluster. It watches the traffic flow and scale accordingly. You can however override the setting, by using the “knative-service” trait in Camel K.

Example:

kamel run --trait knative-service.autoscaling-class=hpa.autoscaling.knative.dev --trait knative-service.autoscaling-metric=concurrency integration.java

Eventing setup

Eventing enables late-binding event sources and event consumers. The cluster admin should have already set up the underlying layer to store the events. Some options may not be persistent and may perish when nodes restarts.

This is quick demo showing how to Integrate SAP with 3rd party services Telegram. Using Camel K with Knative Eventing.

Summary

This is a quick overview of how we can use Camel K to build an true event-driven serverless integration for SAP to 3rd party services or other SAP modules. With Red Hat Integration Camel’s OData 4 connector to interact with the exposed SAP functions. And also by deploying on OpenShift serverless platform will automatically turn the integration application serverless.

Make SAP Cloud Native and Event Driven in 4 days

2021-06-23T14:51:04+02:00

Recently I had an opportunity to work with Sanket Taur (IBM UK) and his team on a demo, showcasing how Red Hat products can help speed up innovation with SAP Landscapes. To be honest I was shocked at how little time we were given to create the entire demo from scratch. It’s less than a week. While still doing our day job, having a couple of hours per day to work on it. If this doesn't convince you.. I don’t know any other stronger proof than this, to show how agile and fast a cloud solution can be from development to production.

I STRONGLY encourage you to attend Sanket’s session for more details, this post is JUST my view on the demo, and things I did to make it running. The demo was a simple approval process of Sales Orders. The SOs are created in the Core SAP platform (In this case ES5), therefore we need to create an application that speaks to the Core SAP platform and retrieve all the data needed.

First thing first, we need a Kubernetes(k8s) platform. And then I used Camel K -- an enhanced framework based on Camel (part of Red Hat Integration product) to create the application. There was some mixup during the setup, instead of the OData v4 endpoint from ES5 for SO, line items and customer details. I was given an OData v2 endpoint. (Needless to say, how more efficient the OData v4 is, compared to v2. Please do update it when you have a chance). Note that Camel K only supports OData v4. HOWEVER, we can still get the results using normal REST API calls (So you are still covered).

This is how Camel helps you retrieve all the information needed. As you can see I have made several requests to get all the data needed as well as doing some transformation to extract results to return.

from("direct:getSO")



   .setHeader("Authorization").constant("Basic XXXX")

   .setHeader("Accept").constant("application/json")

   .toD("https://sapes5.sapdevcenter.com/sap/opu/odata/iwbep/GWSAMPLE_BASIC/SalesOrderSet('${header.SalesOrderID}')?bridgeEndpoint=true")

   .unmarshal().json()

   .setHeader("CustomerID").simple("${body[d][CustomerID]}")

   .marshal().json()

   .bean(this, "setSO(\"${body}\",\"${headers.CustomerID}\")")



;



 from("direct:getItems")

     .setHeader("Authorization").constant("Basic XXXX")

     .setHeader("Accept").constant("application/json")

     .toD("https://sapes5.sapdevcenter.com/sap/opu/odata/iwbep/GWSAMPLE_BASIC/SalesOrderSet('${header.SalesOrderID}')/ToLineItems?bridgeEndpoint=true")

     .unmarshal().json()

     .marshal().json()

     .bean(this, "setPO(\"${body}\")")

 ;



 from("direct:getCustomer")

     .setHeader("Authorization").constant("Basic XXXX")

     .setHeader("Accept").constant("application/json")

     .toD("https://sapes5.sapdevcenter.com/sap/opu/odata/iwbep/GWSAMPLE_BASIC/BusinessPartnerSet('${header.CustomerID}')?bridgeEndpoint=true")

     .unmarshal().json()

     .marshal().json()     

     .bean(this, "setCust(\"${body}\")")



 ;

The endpoints to trigger the call to SAP, is exposed as an API. Here I use Apicurio Studio to define the API contract. With two endpoints, fetch and fetchall. One returns SO, PO and Customer data, where the other one returns a collection of them.

We can now export the definition as a OpenAPI Specification contract in the form of YAML (Link to see the yaml). Save the file into the folder of where your Camel application is. Add the API yaml file name to your Camel K application mode line, and Camel K will automatically map your code to this contract.

   // camel-k: language=java dependency=camel-openapi-java open-api=ibm-sap.yaml dependency=camel-jackson

By using the Camel K CLI tool. Run the command to deploy the code to the OpenShift platform.

   kamel run SapOdata.java

And you should now see a microservice running. Did you notice how Camel K helps you, not only it detects and loads the libraries needed for you, but also containerised it as a running instance.

Go to my git repo to see the full code and running instructions.

Kafka was used in the middle to set the event driven architecture. So the SO approval application can notify the shopping cart client when it’s been approved.

Since everything was put together in a week, with everyone in different timezones, miss communication will happen. What I did not realize was that all the client applications, SO approval and shopping carts were all written in JavaScript, and must communicate via HTTP. But Kafka only does Kafka protocols!!! Therefore, I set up an Http Bridge in front of the Kafka clusters, so it will now translate the Kafka protocols.

And now clients can access the topic via HTTP endpoints. For more information on how to set, go to my Github repo for more detailed instructions.

Last but not least, we need to migrate all UI5 SAP web applications to OpenShift. The UI5 is basically an NODEJS app. We first create the docker file to containerize it. And push it to a container registry.

  docker push quay.io/<YOUR_REPO>/socreate

And deploy the application to OpenShift.

  oc new-app quay.io/<YOUR_REPO>/socreate:latest --as-deployment-config

BUT WAIT!! Since UI5 only does binds to *localhost* (weird..), we need to add a proxy that can tunnel traffic to it. Therefore, I added a sidecar proxy running right next to the NodeJS application. By adding the following configuration.

spec:

      containers:

        - name: nginx

          image: quay.io/weimei79/nginx-sidecar

          ports:

            - containerPort: 8081

              protocol: TCP

          resources:

            limits:

              cpu: 500m

              memory: 1Gi

          terminationMessagePath: /dev/termination-log

          terminationMessagePolicy: File

          imagePullPolicy: Always

This will start the proxy, and since this NGINX proxy starts on port 8081, make sure you update all related settings on OpenShift.

  oc expose dc socreate --port=8181

  oc expose svc socreate

And this is how you would migrate the UI5 application from a local SAP instance onto OpenShift. More detailed migration instructions, check out my Github repo.

Once it’s done, you can see all the applications are running as a container on the cloud. And ready to approve the SOs.

This is actual developer view on top of our demo OpenShift platform

Thank you Sanket for this fun ride, all the nail biting moments, but this is all the fun in IT right? We work through problems, tackle issues and ultimately get everything done! 🙂 If you are a SAPer, and want to explore the world of clouds and containers, what are you still waiting for? Join the ride! This is the story on how we made SAP Cloud Native and Event Driven in 4 days.

To see the full version, be sure to attend Sanket’s session (Virtual free events):

SAP & OpenShift: From classic ABAP development to cloud native applications: Use cases and reference architecture to implement with SAP Landscapes to unlock innovation enabled by Hybrid Cloud and Red Hat OpenShift.

Register here:

https://events.redhat.com/profile/form/index.cfm?PKformID=0x373237abcd&sc_cid=7013a000002w6W7AAI

Refer to Sanket's awesome post for more details on the concept and why we created this demo.

https://blogs.sap.com/2021/06/28/safeguard-your-investments-with-red-hat-openshift/

Safeguard your Investments with Red Hat OpenShift

2021-06-28T12:59:02+02:00

Traditional development with SAP has evolved from Classical ABAP to ABAP RAP, SAP CAP (Cloud Application Programming Model). Its analogous to moving on from doing Stop Motion animation to immersive CGI to virtual reality that we experience today. The need to evolve and innovate has never stalled for SAP rather has accelerated and multiplied in last decade. With an imperative to keep the core clean and lean in the new SAP world, the side-by-side concept has pushed the extensions towards the cloud to orchestrate the data and processes with cloud native capabilities in Hybrid cloud environments.

Evolving Hyperscalers

Hyperscalers tend to have higher churn rates on innovative platform services and are sharing the side-by-side extensibility space with SAP BTP. Whether you go with SAP BTP as your primary extension platform and create plethora of cloud native applications on the periphery utilising the native platform services on hyperscaler’s, or you go pure Hyperscaler based extension is based on the hyperscaler startegy your organisations are adopting for now or in future. It can influence the choice of application services, development services or data services that will have direct influence on how quickly you can turn around an innovative idea to a product or service. That is dependent on the vision the organisation or business has about its products and services in the near and long term.

The extension and innovation platform choice is further influenced by SAP footprint on the landscape, where you are in the S/4 HANA adoption journey, how open is your organisation for open source innovation, the development culture, cloud native skillsets are a few other facets to consider. Its an architectural choice, again influenced by platform services that will help drive your innovation agenda.

What if you want to abstract yourself from all these choices and changes that may overturn, the decisions your organisations take today in the future as hyperscalers evolve i.e. continue accelerating your digital transformation agenda. Red Hat OpenShift creates that abstraction layer and provides the scalability, interoperability and control that the organisation desires. Its like a hovercraft which glides across the changing turf. Its about getting from point A to B with the least number of changes in direction. The good part is all SAP BTP extensions work in harmony and unison along sides the Red Hat® OpenShift® cloud native applications / extensions i.e. you can opt to choose best of both worlds.

The open innovation built behind Red Hat® Openshift® and its products is critical to achieving digital transformation objectives. This open innovation and embracing open source has driven tooling that enables us to do the following:

Innovate anywhere, at pace and agility on any cloud

Consumption based models with wider ecosystem platform services

Reduce the turn around times with streamlined deployment cycles.

Improve team productivity Dev + Sec + Ops

Optimise costs and efficiencies, share resources, accelerate with repositories of reusable assets and components.

Moving away from VM’s with operating system footprint to application footprints, which enables hosting and running multiple applications and functions consuming the same amount of compute.

The docker image or the golden image of the application can reproduce the same results with same behaviour and consistency in any environment. The immutability results in interoperability.

As organisation comes to realise that "Cloud Adoption" is not just modernisation of applications with lift and shift to the cloud but the true value is realised by change in the organisation culture, the development and delivery practices, with Continuous Integration and Deployment practice, the Architectural and Integration Patterns.

Modular Architectures

Modern Architectures and Agile Integrations (source : IBM + Red Hat)

From enterprise architecture point of view, it’s how do we move away from traditional integration like enterprise service buses towards more of an agile integration which is decentralised. For e.g. we don’t want applications hogging system resources 24*7 to serve couple of requests. When we talk about event driven architectures, we can have a serverless function, being invoked by event or a web-hook call, spins up for the moment serves the request Just-In-Time and then spins down.

With headless architectures, we are more microservices driven for any front end framework as far as it adheres to the API Contracts for the capabilities being delivered by underlying platform. When we look at Edge devices, we are using machine learning on edge , sifting out the most criticak data points for further insights from what is being sensed. Pub-Sub mechanisms allow application to listen for events / messages, to react only if they are relevant for any action. Istio Mesh based distributed Microservices deployment leads to failsafe, resilient, secure and observable mesh network.

So we can almost end up distributed architectural components with a RACI matrix of all things, applications and digital entities that are part of that ecosystems which drive the enterprise systems and processes. This is where we start seeing the way we design applications become more modular, agile, scalable across different clouds to be iterated more quickly and more efficiently.

Delivering Outcomes at Speed, Scale and Control

Shift in the way we deliver outcomes (source : IBM + Red Hat)

Adopting dev-sec-ops takes a lot of different steps moving away from traditional methods and practices to hybrid cloud platform approach. Moving from siloed teams using waterfall delivery methods, to Agile practices with CI/CD adoption. Deploying in hybrid, public / private cloud with enterprise grade container platforms, is preferred over VMs with co-located workloads in data centers. From an application perspective we’re still building these monolithic applications and we need to start to move towards more modular , decentralised architectures and agile integrations, delivering microservices or serverless functions as explained above.

When we talk about speed we're really talking about time to market. Agility, how quickly we can make new updates, new commits to specific processes or applications further how they can be simplified as far as the process more streamlined so that we have more freedom to experiment. The personas within these different roles especially when you're a developer you're usually, much more bleeding edge, want a quick turn around. Build once and run everywhere is emerging trend amongst the developers to cater the business demands.

Though the questions like, how do we scale with resilience, without sacrificing the stability and control of enterprise landscape needs to be addressed. When you’re on the operations side or administration side you want a little more tried and trusted solutions, how do we enable both the personas and then control how do we mitigate any kind of security, risks or any kind of issues with bugs, how do we approach them more quickly when they do come up.

Red Hat Openshift - Smarter Kubernetes

This is where the containers are becoming a defacto standard in the cloud native application development. It is underpinning the adoption of Devops culture. Containers promise things like application portability across any cloud. They allow developers to really just focus on building their apps instead of having to worry about the underlying infrastructure technologies. This is where you would require a policy based automated container orchestration mechanism and features to manage containers across your dev, test /staging and production environments.

Kubernetes as open source, has really emerged as the standard for container orchestration, management and scalability. Though just installing Kubernetes to have a production grade platform is not enough: you’ll need to add authentication, networking, security, monitoring, logs management. That means you will also have to pick your tools among everything available (see CNCF landscape to get an idea of the complexity of the ecosystem), and maintain the cohesion of all of them as a whole; but also do updates and regression tests whenever there is a new version of one of these components.

With OpenShift, Red Hat has decided to shield this complexity and deliver a comprehensive platform, including not only Kubernetes at its core, but also all the essential open source tools that make it an enterprise-ready solution to confidently run your production. Of course, in case you already have your own stacks, then you can opt-out and plug into your existing solutions.

Red Hat Openshift run on "Anycloud" (source : IBM + Red Hat)

OpenShift allows you to deploy traditional stateful applications, alongside cutting-edge cloud-native applications, by supporting modern architectures such as microservices or serverless.

AT IBM we believe that containers, Kubernetes and Devops are the key ingredients that a modern application platform should be based on that allows you to transform your traditional apps, build cloud-native applications and also experiment with analytics, machine learning and serverless applications.

This application platform needs to provide a consistent way for both developers and operations teams to collaborate across all deployment footprints, from Edge and air gapped environments to infrastructure you have in your own datacenter and all the way to the hybrid cloud.

OpenShift allows you now to even migrate your legacy virtual machines to OpenShift itself by using Container Native Virtualisation

I have been advocating the container based extensibility with modern architectures at several of IBM’s SAP Clients using Red Hat Openshift Platform and portfolio of products. I believe that the developers have the power and energy to create and architects help channelise that energy in right direction for business outcomes, while operational teams provide a level playing field for all participants of the Innovation Games. Liberating these personas of the traditional shackles is the need of the hour and this is what I am talking about in my upcoming talk on SAP and Openshift : From classic ABAP development to cloud-native applications. Please join us to know more , where we also cover a demo to show you how we deploy cloud native extensions with OpenShift.

The demo is based on modularising and separating the UI, Business Logic and the System functions using several Red Hat Openshift Products and Platform services to create a modern decentralised architectures. Its a Sales Order Approval Scenario which covers three Fiori apps : the Shopping Cart for Customer persona, the SO Approval App for the Approver persona and the Back-office persona using the approved Sales Order app to complete order fulfilment.

Demo Scenario : Sales Order Approval (source : IBM + Red Hat)

All Fiori apps / SAP Ui5 apps deployed on Openshift Containers , invoking microservices and serverless functions, streaming events and reacting to them using Red Hat Openshift streams for Apache Kafka broker. More details on technical deployment with sample code on GitHUb refer to the blog post here : https://blogs.sap.com/2021/06/23/make-sap-cloud-native-and-event-driven-in-4-days/

Hope you find this article useful. Feel free to comment and get in touch.

How to Extend SAP S/4HANA Business Address Services (or any other SAP S/4HANA application) with Serverless Functions on Kyma Part-II

2021-09-23T09:07:03+02:00

In this blog post you will learn…

Overview:

We will learn about how we will create serverless function in Kyma Runtime and how they are deployed (i.e. how URLs are created to get which can be used to run serverless functions) .

We will also learn about how to use Google APIs to get Geocodes of any inputted address .

To Know what is serverless function and need of serverless function refer to previous blog post of this blog series

Prerequisites/Skills:

Access to SAP BTP Cockpit
You need access to a productive account of SAP BTP Cockpit
Note:
This service is available in Trial version of SAP BTP Cockpit

Node.js/JavaScript
Functions are written in JavaScript for Node.js runtime.
As such, some knowledge is helpful, however, most of the tutorials can be followed without any knowledge.

ABAP.

Kyma Environment Setup explained in Part-I of this Blog Series

Implementation Steps:

After successfully setting up the Kyma Runtime Environment as described in the steps above, we now must define the Kyma Namespace. This is where all our functions will be defined. The steps below are to set up your Kyma Namespace and get started with the Kyma environment.

1. Open Your Subaccount in SAP BTP Cockpit.

2. Click on Instances and Subscription.

3. Click on Environments.

4. Click on the Actions button in your Kyma environment and navigate to ‘Go to Dashboard’.

5. On the Dashboard click on ‘Select Namespace’ and choose your namespace.

Creating Serverless Function

Click on ‘Functions’ on left hand pane and then click on ‘Create Function’ to create a new function.

Enter name of your choice and press Enter. You will see the screen shown below.

There are two sections under code tab:
- First section will contain our source code to call the Google API.
- Second section will contain dependencies (if any).

We are now going to add code in Source section

const https = require('https');



const key = {Enter Your Key Here}



const generateGeoCode = (address) => {



let data = '';



return new Promise((resolve,reject) => {



https.get(`https://maps.googleapis.com/maps/api/geocode/json?address=${address}&key=${key}`,



(response)=>{



response.on('data',(chunks)=>{



data+=chunks;



})



response.on('end',()=>



{



// console.log('check123',data);



// response = data;



// return data;



resolve(data);



})



response.on('error',(error)=>{



console.log(error)



reject(error);})



});



//  console.log("google",response);



})



}









module.exports = {



main: async function (event, context) {



console.log('event',event.extensions.request.query.address);



address = event.extensions.request.query.address;



const output = await generateGeoCode(address);



let {results} = JSON.parse(output);



console.log('add',results[0].geometry.location.lat);



let final = '';



final +=`${results[0].geometry.location.lat}, ${results[0].geometry.location.lng}`



return final;



//console.log('f',f);



}}

In the above Picture you can see that there is a variable key that has been purposely left blank. Here you need to get your credentials from Google Cloud Platform before entering them. you can get them from Here

Here we can see that our code is dependent on HTTP module to run so we are going to put that in our dependency:

{



"name": "geocode-api",



"version": "1.0.0",



"description": "geocode api to get latitude and longitude",



"dependencies": {



"https": "^1.0.0"



},



"license": "ISC"



}

This Completes first part of our function. Now it’s time to create the URL to send request to API.

Creation of URL for Function to place request to API:

Click on Configuration tab next to Code tab and click on ‘Expose Function’.

Enter API Rule Name and Host Name and press Enter. This will generate the URL.

You can run the URL above in your browser and see the output.

Summary:

In this blog post we saw about

How to create serverless function in Kyma.

How to use Google APIs to find Geocodes using address send by user.

And How to deploy the serverless function and generate API URL which can be used to send get request to server.

Next Steps:

We will be seeing how to Integrate the Kyma serverless function in any SAP S/4HANA applications

For any queries and doubts please comment in comment section I will be more then happy to help you, also you can follow my profile to get updated of upcoming blog posts.

How to Extend SAP S/4HANA Business Address Services (or any other SAP S/4HANA application) with Serverless Functions on Kyma Part-III

2021-09-27T10:31:38+02:00

Introduction

This blog post explains how a Serverless Function developed in Kyma Runtime can be consumed in the SAP S/4HANA system for the extensibility of SAP S/4HANA applications. Specifically, this blog post covers the extensibility of Business Address Services and is in continuation of Blog Series of the same title(mentioned under Prerequisites).

Prerequisites/Skills

ABAP

Kyma Environment Setup explained in Part-I of this Blog Series

Kyma Serverless Function Implementation explained in Part-II of this Blog Series

In our example, we will be implementing the geocode functionality with the Business Partner (BP) transaction. Once our serverless function returns the geocodes, we will be updating a Custom Z table.

Since it is a customer modification, we can make use of the BADIs available. ADDRESS_UPDATE is the BADI that is used to trigger updates on Address Changes. We have implemented this BADI in SE18 as ZADDRESS_UPD_SRV_POC. The implementing class name is given as ZCL_IM_ADDRESS_UPD_SRV_POC

Based on the type of address created i.e. Organization, Person, or Workplace, add the logic in methods ADDRESS1_SAVED, ADDRESS2_SAVED, and ADDRESS3_SAVED respectively. Next, we must compile the complete URL which will be a combination of:
- URL generated by Kyma runtime
- Search parameters from BP transaction which will be components of address based on which Geocode will be found. For our PoC, we have considered House Number, Street, City, Region, Postal Code, and Country

 DATA(url) = 'https://get-geocodes.fdc4fe9.kyma.shoot.live.k8s-hana.ondemand.com/?address='.

    LOOP AT im_t_xadrc ASSIGNING FIELD-SYMBOL(<fs_xadrc>).



      IF <fs_xadrc>-house_num1 IS NOT INITIAL.

        full_address = <fs_xadrc>-house_num1.

      ENDIF.

      IF <fs_xadrc>-street IS NOT INITIAL.

        CONCATENATE full_address <fs_xadrc>-street INTO full_address SEPARATED BY space.

      ENDIF.

      IF <fs_xadrc>-city1 IS NOT INITIAL.

        CONCATENATE full_address <fs_xadrc>-city1 INTO full_address SEPARATED BY space.

      ENDIF.

      IF <fs_xadrc>-region IS NOT INITIAL.

        CONCATENATE full_address <fs_xadrc>-region INTO full_address SEPARATED BY space.

      ENDIF.

      IF <fs_xadrc>-post_code1 IS NOT INITIAL.

        CONCATENATE full_address <fs_xadrc>-post_code1 INTO full_address SEPARATED BY space.

      ENDIF.

      IF <fs_xadrc>-country IS NOT INITIAL.

        CONCATENATE full_address <fs_xadrc>-country INTO full_address SEPARATED BY space.

      ENDIF.

      REPLACE '#' WITH space INTO full_address.

      SHIFT full_address LEFT DELETING LEADING space.

      CONDENSE full_address.

      CONCATENATE url full_address INTO DATA(final_url).

    ENDLOOP.

Next, an HTTP client for the generated URL must be created. This is done by calling the method CREATE_FROM_URL of class CL_HTTP_CLIENT. This HTTP client is used to send the request to Kyma Serverless Runtime and receive in response the Geocodes of the provided search parameters.

"create HTTP client by url

    CALL METHOD cl_http_client=>create_by_url

      EXPORTING

        url                = final_url

      IMPORTING

        client             = lo_http_client

      EXCEPTIONS

        argument_not_found = 1

        plugin_not_active  = 2

        internal_error     = 3

        OTHERS             = 4.



    IF sy-subrc <> 0.

      "error handling

    ENDIF.



*** Send the request

    lo_http_client->send(

      EXCEPTIONS

        http_communication_failure = 1

        http_invalid_state         = 2 ).



*** Receive the respose

    lo_http_client->receive(

       EXCEPTIONS

         http_communication_failure = 1

         http_invalid_state         = 2

         http_processing_failed     = 3 ).

Finally, we read the result from the HTTP response and update our custom table with the Geocode.

*** Read the result

      lv_result = lo_http_client->response->get_cdata( ).

      IF lv_result NP 'Internal Server Error'.

        ls_geocode-mandt = sy-mandt.

        ls_geocode-addrnumber = im_address_number.

        SPLIT lv_result AT ',' INTO ls_geocode-latitude ls_geocode-longitude.



        MODIFY zaddress_geocode FROM ls_geocode.

      ENDIF.

The Custom table structure is as below:

Next, in BP transaction we must create an Organization BP with the values below for address fields which in turn will be considered for the final URL generation:

The address number of the BP above is:

On Save of the Business Partner, the custom table ZADDRESS_GEOCODE is updated:

Note: We did not enhance the BP transaction to display these coordinates, but such enhancements can be taken up if required for the project.

Summary

In this blog post, we have seen how a Serverless Function developed in Kyma Runtime can be consumed in the SAP S/4HANA system for the extensibility of Business Address Services or any other SAP S/4HANA applications.

Deploying an SAP Customer Data Cloud Extension to SAP BTP, Kyma Runtime

2021-11-10T19:51:00+01:00

The objective of this example is to demonstrate how to setup a Kyma serverless function to be used as an SAP Customer Data Cloud Extension endpoint.

SAP Customer Data Cloud Extensions allow us to synchronously intercept specific SAP Customer Data Cloud REST API calls on the server-side and to execute custom business logic before the specific API call invokes SAP Customer Data Cloud. They also act like filters as they can be used to prevent an API call from invoking SAP Customer Data Cloud by returning a status with the value of "FAIL" and a custom error message to the user if specific business rules aren't met.

Currently, the following SAP Customer Data Cloud REST API calls can be intercepted using an SAP Customer Data Cloud Extension:

accounts.register - Registration (OnBeforeAccountsRegister extension)

accounts.login - Login (OnBeforeAccountsLogin extension)

socialize.login - Social Login (OnBeforeSocialLogin extension)

accounts.setAccountInfo - Profile Updates (OnBeforeSetAccountInfo extension)

accounts.resetPassword - Reset Password (OnBeforeResetPassword extension)

Send SMS - Communication (OnBeforeSendSMS extension)

In this example, the accounts.setAccountInfo REST API endpoint has been intercepted to cleanse the user's address via an external SAP Data Quality Management microservice.

If the address can be cleansed, the request is enriched with the cleansed address and the user's account is updated.

On the other hand, if the address can't be cleansed, an error message is returned to the user and the user's account isn't updated.

The code of this example can be easily re-used to build any other SAP Customer Data Cloud Extension and deploy it to SAP BTP, Kyma Runtime or to Kyma Open Source.

Notes:

All the functionality presented here are subject to change and may be changed by SAP at any time for any reason without notice.

For demonstration, this example uses an API Key to authenticate requests to SAP Data Quality Management. In a real-world scenario, either OAuth 2.0 or Client Certificate Authentication are to be used.

Scenario

This example includes a Kyma serverless function, cdc-extension, that is exposed as an SAP Customer Data Cloud extension endpoint, and demonstrates how to:

Create an SAP Customer Data Cloud extension endpoint using a Kyma serverless function

Deploy a Kyma serverless function and an API Rule using the Kubernetes command-line tool

Alternately, deploy a Kyma serverless function and an API Rule using the Kyma Console User Interface

Explore api.sap.com and try out REST API calls using a sandbox environment

Use the SAP Data Quality Management microservice for location data to cleanse addresses

Solution Architecture

Sequence Diagram

Pre-requisites

Provision SAP Customer Data Cloud from Gigya and setup an SAP Customer Data Cloud site.

Get a Free Account on SAP BTP Trial.

Enable SAP BTP, Kyma Runtime.

Download and install the Kubernetes Command Line Tool.

Test the kubectl installation.

Download the Kyma Runtime kubeconfig.

Create your api.sap.com account.

Deployment steps

Go to the kyma-runtime-extension-samples repository and clone it. This repository contains a collection of Kyma sample applications including this example (in the cdc-extension subfolder). Download the code by choosing the green Code button, and then choosing one of the options to download the code locally. Alternately, you can also run the following command using your command-line interface within your desired folder location:
- git clone https://github.com/SAP-samples/kyma-runtime-extension-samples
  
  Note: The source code of this example is in the cdc-extension subfolder of this repository.

Update the values of the following environment variables in the ./kyma-runtime-extension-samples/cdc-extension/k8s/function.yaml file:
CDC_API_KEY, SAP_API_HUB_API_KEY, PUBLIC_KEY_KID, PUBLIC_KEY_N and PUBLIC_KEY_E
- CDC_API_KEY - This is the API Key of the SAP Customer Data Cloud site and can be got from the SAP Customer Data Cloud console.
- SAP_API_HUB_API_KEY - This is the API Key of SAP API Business Hub. Login to api.sap.com. Then, go to your profile settings and click on Show API Key to get the value for this variable.
Go to https://accounts.SAP_Customer_Data_Cloud_Data_Center/accounts.getJWTPublicKey?apiKey=Your_SAP_Customer_Data_Cloud_Site_API_Key.

Find your SAP Customer Data Cloud Data Center. Replace SAP_Customer_Data_Cloud_Data_Center with your Data Center (For example, the US Data Center is us1.gigya.com). Replace Your_SAP_Customer_Data_Cloud_Site_API_Key with your SAP Customer Data Cloud site's API Key.

The response JSON body of the above request will also include the following fields: kid, n and e
- PUBLIC_KEY_KID - This is the value of the kid field in the response above.
- PUBLIC_KEY_N - This is the value of the n field in the response above.
- PUBLIC_KEY_E - This is the value of the e field in the response above.

Create a Kubernetes namespace with the name cdc.
- kubectl create namespace cdc
Note: As a prerequisite, please follow the steps listed in the following tutorial: Download the Kyma Runtime kubeconfig

Alternately, use the Kyma Console User Interface to create a new namespace
- Open the Kyma console and click on Add new namespace. Enter its name as cdc and click the Create button.

Create/update Kubernetes resources of the cdc-extension serverless function.
- kubectl apply -f ./kyma-runtime-extension-samples/cdc-extension/k8s/function.yaml
- kubectl apply -f ./kyma-runtime-extension-samples/cdc-extension/k8s/api-rule.yaml
Note: As a prerequisite, please follow the steps listed in the following tutorial: Download the Kyma Runtime kubeconfig
The resources are represented as declarative YAML objects. Applying the resources will perform the following steps:
- Deploy the Kyma serverless function
- Expose the serverless function using a Kyma API Rule that will serve as the SAP Customer Data Cloud Extension endpoint
Alternately, deploy the Kyma serverless function and API Rule using the Kyma Console User Interface:
- Open the Kyma console and select the cdc namespace.
- Click on Workloads. Then, click on Deploy new workload and select Upload YAML.
- Then, click on Browse to select the following YAML file, and click on Deploy: ./kyma-runtime-extension-samples/cdc-extension/k8s/function.yaml
- Repeat the above steps and select the following YAML file. Then, click on Deploy: ./kyma-runtime-extension-samples/cdc-extension/k8s/api-rule.yaml

Go to the Kyma Console -> cdc namespace -> Discovery & Network -> API Rules. Copy the host URL of the cdc-extension API Rule.

Then, go to the SAP Customer Data Cloud Console. Select your site and click on Extensions -> Add.

Enter any Name, select the API as accounts.setAccountInfo (OnBeforeSetAccountInfo), enter any Description, paste the host URL from step 5 above and click on Advanced. Then, enter the Timeout as 10000 ms, select the Fallback Policy as FailOnAnyError and click Save.

In the SAP Customer Data Cloud Console, select your site and click on Schema in the left menu under Registration-as-a-Service.

Set the following schema fields to be Required and select Write Access as clientModify for all of them. Then, click Save Changes.
- profile.address
- profile.city
- profile.state
- profile.zip
- profile.country

In the SAP Customer Data Cloud Console, select your site and click on Screen-Sets in the left menu under Registration-as-a-Service.

Click on the Default-RegistrationLogin screen-set.

Select the Registration Completion screen from the dropdown.

Add four Textbox components and one Dropdown component to the SAP Customer Data Cloud Registration Completion screen and map them to the following fields.
- profile.address
- profile.city
- profile.state
- profile.zip
- profile.country

Steps to test the solution

Register an account in your SAP Customer Data Cloud site.

Note: This can also be done by previewing the registration screen of the Default-RegistrationLogin screen-set in the SAP Customer Data Cloud console.

The Registration Completion screen will be displayed. Enter an invalid address and click the Submit button. An error message will be returned.

Fix the address and click the Submit button. The form should be processed successfully.

View the details of the account that was registered in the Identity Access screen of the SAP Customer Data Cloud console. It can be observed that the address of the user has been cleansed.

Troubleshooting steps

Check the logs of your Kubernetes pods

To see the logs of a specific function, open the function in the Kyma console (Go to Workloads -> Functions -> cdc-extension) and you will see the logs in an expandable window at the bottom of the page.

Alternately, go to Workloads -> Pods in the Kyma Console (within the cdc namespace) to see the list of all running pods. Then, click on the three dots to the right of the running pod of the cdc-extension function, and click on Show Logs to see the logs of the pod.

Or use the following kubectl command to get the list of pods running in the cdc namespace.

kubectl get pods -n cdc

Then, to see the logs of any of the pods, use the following syntax:

kubectl logs <pod-name> -n <namespace-name>

Example:

kubectl logs cdc-extension-65khj-58b6d69cd9-l7dgs -n cdc

Conclusion

This example demonstrates how to easily extend SAP Customer Data Cloud. Care should be taken, however, to ensure that the custom business logic executes as quickly as possible so as to provide a good user experience. In general, synchronous microservices should execute within about 50 ms to about 300 ms depending on the use case. It is to be noted that SAP Customer Data Cloud Extensions currently support a maximum latency of 10,000 ms. Here are a few things you could do that could help decrease the latency of your Kyma serverless function:

Minimize external API calls as much as possible.

Parallelize external API calls that aren't dependent on each other.

Use OData or GraphQL APIs if possible, to get only the required data when making external API calls. For example, use the $select parameter when using OData calls to select the fields to be returned.

Simplify the logic of the Kyma serverless function and reduce the amount of custom code as much as possible.

Cache the responses of repetitive external API calls having identical request payloads using fully managed caching solutions if possible. In this example, the SAP Customer Data Cloud Public Key, that hardly changes, has been saved using environment variables, and the API call to get the Public Key is only made if it has changed.

Increase the replicas (horizontal scaling) or the memory and CPU resource usage of your Kyma serverless function (vertical scaling) for more resource intensive workloads or higher load, which can be easily done in the Resources tab of the Kyma serverless function (Workloads -> Functions -> cdc-extension -> Resources -> Runtime Profile). You can also utilize the auto-scaling feature of the Kyma Runtime by setting minimum and maximum replicas.

As a next step, you could try to extend this example to implement your own custom logic or use case.

I'd like to request you to kindly provide your feedback or ask clarifying questions related to this post in the comment section below. Additionally, I'd like to invite you to submit any broader Kyma related questions in the Q&A area of the SAP BTP, Kyma runtime topic.

If the SAP BTP, Kyma runtime topic interests you, here are some other links that you may like:

Kyma at SAP

Kyma related SAP Tutorials for Developers

Lastly, if you liked this post, I'd like to request you to kindly hit the like icon, leave a comment below or share this post.

Enrich contact data on SAP Customer Data Platform with master data from SAP S/4HANA Cloud using a Kyma Serverless Function

2021-11-24T11:30:42+01:00

This example demonstrates how to set up a Kyma Serverless Function as an SAP Customer Data Platform pre-mapping Extension endpoint and to use it to enrich contact data extracted from an Amazon S3 Cloud Object Storage bucket with master data from SAP S/4HANA Cloud Business Partner (A2X) microservice, before ingesting it to SAP Customer Data Platform (CDP).

An SAP Customer Data Platform pre-mapping Extension can be used to synchronously intercept the data ingestion flow of SAP Customer Data Platform events that ingest data from supported sources such as Commerce applications, Cloud Storage Solutions, CRM Solutions, Custom Web Applications and SAP Customer Data Cloud.

In this example, email addresses and unique identifiers of contacts are ingested from an Amazon S3 Cloud Object Storage bucket into SAP Customer Data Platform. During the data ingestion process, the flow is intercepted by an Extension (the Kyma Serverless Function) that enriches the request with additional data from SAP S/4HANA Cloud such as the name, phone number and organizations of each of the contacts.

The Kyma Serverless Function used in this example will work with other supported sources as well such as Google Cloud Storage or Microsoft Azure Blob. The only change required is to connect a different source to SAP Customer Data Platform instead of an Amazon S3 Cloud Object Storage bucket that is demonstrated here.

Note: All the functionality presented here are subject to change and may be changed by SAP at any time for any reason without notice.

Scenario

This example includes a Kyma Serverless Function, cdp-extension, that is exposed as an SAP Customer Data Platform Extension endpoint, and demonstrates how to:

Create an SAP Customer Data Platform Extension endpoint using a Kyma Serverless Function

Deploy a Kyma Serverless Function and an API Rule with JWT Access strategy using the Kubernetes command-line tool

Alternately, deploy a Kyma Serverless Function and an API Rule with JWT Access strategy using the Kyma Console User Interface

Explore api.sap.com and try out REST API calls using a sandbox environment

Use the SAP S/4HANA Cloud Business Partner (A2X) microservice for Business Partner, Supplier, and Customer master data in SAP S/4HANA Cloud system

Solution Architecture

Sequence Diagram

Pre-requisites

Provision SAP Customer Data Platform.

Get a Free Account on SAP BTP Trial.

Enable SAP BTP, Kyma Runtime.

Download and install the Kubernetes Command Line Tool.

Test the kubectl installation.

Download the Kyma Runtime kubeconfig.

Create your api.sap.com account.

Get an AWS Free Tier account or use your existing AWS account to create an Amazon S3 bucket.

Deployment steps

Deploy the Kyma Serverless Function

Go to the kyma-runtime-extension-samples repository and clone it. This repository contains a collection of Kyma sample applications including this example (in the cdp-extension subfolder). Download the code by choosing the green Code button, and then choosing one of the options to download the code locally. Alternately, you can also run the following command using your command-line interface within your desired folder location:
- - git clone https://github.com/SAP-samples/kyma-runtime-extension-samples
Note: The source code of this example is in the cdp-extension subfolder of this repository.

Update the values of the following environment variable in the ./kyma-runtime-extension-samples/cdp-extension/k8s/function.yaml file: SAP_API_HUB_API_KEY
- SAP_API_HUB_API_KEY - This is the API Key of SAP API Business Hub. Login to api.sap.com. Then, go to your profile settings and click on Show API Key to get the value for this variable.

Make the following changes in the ./kyma-runtime-extension-samples/cdp-extension/k8s/api-rule.yaml file:
- Replace DATA_CENTER with the Data Center that is closest to you. As an example, the US Data Center is us1.gigya.com. For other locations, check Finding your Data Center.
- Replace BUSINESS_UNIT_ID with your Business Unit ID, which can be located in your SAP Customer Data Platform console URL after /business-unit/.

Create a Kubernetes namespace with the name cdp.
- kubectl create namespace cdp
Note: As a prerequisite, please follow the steps listed in the following tutorial: Download the Kyma Runtime kubeconfig

Alternately, use the Kyma Console User Interface to create a new namespace
- Open the Kyma console and click on Add new namespace. Enter its name as cdp and click the Create button.

Create/update Kubernetes resources of the cdp-extension serverless function.
- kubectl apply -f ./kyma-runtime-extension-samples/cdp-extension/k8s/function.yaml
- kubectl apply -f ./kyma-runtime-extension-samples/cdp-extension/k8s/api-rule.yaml
Note: As a prerequisite, please follow the steps listed in the following tutorial: Download the Kyma Runtime kubeconfig

The resources are represented as declarative YAML objects. Applying the resources will perform the following steps:
- Deploy the Kyma serverless function
- Expose the serverless function using a Kyma API Rule with JWT Access strategy that will serve as the SAP Customer Data Platform Extension endpoint
Alternately, deploy the Kyma serverless function and API Rule using the Kyma Console User Interface:
- Open the Kyma console and select the cdp namespace.
- Click on Workloads. Then, click on Deploy new workload and select Upload YAML.
- Then, click on Browse to select the following YAML file, and click on Deploy: ./kyma-runtime-extension-samples/cdp-extension/k8s/function.yaml
- Repeat the above steps and select the following YAML file. Then, click on Deploy: ./kyma-runtime-extension-samples/cdp-extension/k8s/api-rule.yaml

Go to the Kyma Console --> cdp namespace --> Discovery & Network --> API Rules. Copy the host URL of the cdp-extension API Rule and use it in the last step below.

Update the Schema in the SAP Customer Data Platform console

Go to Dashboard --> Connect --> Customer Schema

Select Profile Entity. Then, click on JSON and enter the following JSON:

Note: If you already have some custom fields, then only add the phoneNumberDetails and contactPersonBPID fields listed in the JSON below.

{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "primaryEmail": { "type": "string" }, "primaryPhone": { "type": "string" }, "masterDataId": { "type": "array", "items": { "type": "string" } }, "crmId": { "type": "array", "items": { "type": "string" } }, "ciamId": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "phones": { "scopes": [], "type": "array", "items": { "type": "string" } }, "cookieId": { "type": "array", "additionalItems": true, "items": { "type": "string" } }, "searchHistory": { "type": "array", "additionalItems": true, "items": { "type": "string" } }, "phoneNumberDetails": { "type": "object", "additionalProperties": false, "properties": { "phoneNumber": { "type": "string" }, "phoneNumberExtension": { "type": "string" }, "phoneNumberType": { "type": "string" } } }, "contactPersonBPID": { "type": "string" } } }

Select Activities --> Click on the icon with three lines --> Create New Activity. Enter its name as "groups" and click Save. Then, click on JSON and enter the following JSON:

{ "type": "array", "items": { "type": "object", "properties": { "customerBPID": { "type": "string" }, "relationshipNumber": { "type": "string" }, "relationshipCategory": { "type": "string" } } } }

Add a source and create a new event

Go to Dashboard --> Connect --> Sources --> Connect Application --> Select connect within AWS S3 (under Cloud Storage).

Enter the connection details and your AWS credentials as depicted in the screenshots below.

Once the aws-cdp-integration source has been created, click to select it.

Then, click on Create New Event.

In the Settings screen, enter the settings as per the screenshots below and click Next.

In the Model screen, click on JSON and enter the following JSON:

{ "type": "object", "additionalProperties": true, "properties": { "profile": { "type": "object", "additionalProperties": true, "properties": { "UID": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } }, "data": { "type": "object", "additionalProperties": true, "properties": { "phoneNumber": { "type": "string" }, "phoneNumberExtension": { "type": "string" }, "internationalPhoneNumber": { "type": "string" }, "phoneNumberType": { "type": "string" }, "contactPersonBPID": { "type": "string" }, "groups": { "type": "array", "additionalItems": true, "items": { "type": "object", "additionalProperties": true, "properties": { "customerBPID": { "type": "string" }, "relationshipNumber": { "type": "string" }, "relationshipCategory": { "type": "string" } } } } } } } }

Perform the following mappings in the Mapping screen:

EVENT SCHEMA	CUSTOMER SCHEMA
profile.UID	PROFILE.ciamId
profile.email	PROFILE.primaryEmail
profile.firstName	PROFILE.firstName
profile.lastName	PROFILE.lastName
data.phoneNumber	PROFILE.phoneNumberDetails.phoneNumber
data.phoneNumberExtension	PROFILE.phoneNumberDetails.phoneNumberExtension
data.internationalPhoneNumber	PROFILE.primaryPhone
data.phoneNumberType	PROFILE.phoneNumberDetails.phoneNumberType
data.contactPersonBPID	PROFILE.contactPersonBPID
data.groups	GROUPS

Click Next. Finally, in the Scheduled Polling screen, click on Extensions.

Under Pre-mapping, enter the name and URL of the extension, which is the host URL of the cdp-extension API Rule. Set the Timeout to 10 seconds, select Stop as the Failure Policy.

Click Save and Done.

Test the solution

Upload the sample input file to your AWS S3 bucket: Upload the input_20211119_001.json file (located in the ./kyma-runtime-extension-samples/cdp-extension/input folder of the cdp-extension repo) to the input folder of your AWS S3 bucket.

Note: The input_20211119_001.json file contains mock email addresses that are currently used by the SAP S/4HANA Cloud Business Partner (A2X) microservice for Business Partner, Supplier, and Customer master data in SAP S/4HANA Cloud system.

Go to Dashboard --> Connect --> Sources --> aws-cdp-integration --> Load users from AWS S3 --> Ingest Now.

If SAP API Hub is up and running and your Extension has been setup correctly, then the data is enriched during ingestion with additional data from SAP S/4HANA Cloud. To verify this, go to Customers --> Search. Then, check to confirm that the contact data has been enriched and ingested as expected.

Troubleshooting steps

Check the logs of your Kubernetes pods

To see the logs of a specific function, open the function in the Kyma console (Go to Workloads > Functions > cdp-extension) and you will see the logs in an expandable window at the bottom of the page.

Alternately, go to Workloads > Pods in the Kyma Console (within the cdp namespace) to see the list of all running pods. Then, click on the three dots to the right of the running pod of the cdp-extension function, and click on Show Logs to see the logs of the pod.

Or use the following kubectl command to get the list of pods running in the cdp namespace.

kubectl get pods -n cdp

Then, to see the logs of any of the pods, use the following syntax:

kubectl logs <pod-name> -n <namespace-name>

Example:

kubectl logs cdp-extension-jqckp-57787d8cd4-d54nw -n cdp

Conclusion

As you’ve seen, this example demonstrates how to enrich data being ingested to SAP Customer Data Platform using a Kyma Serverless Function that makes external API calls to SAP S/4HANA Cloud Business Partner (A2X) microservice.

The external API calls get specific additional information about the contacts, which is also ingested. You can also extend this example to validate specific information about the contacts from the SAP S/4HANA Cloud Business Partner (A2X) microservice. For example, you could verify the postal code and city of contacts.

As a next step, you could extend this example to support your use case and you could also try using another source instead such as Google Cloud Storage.

Since this is a synchronous flow, it is important to ensure that the extension executes as fast as possible. In this example, parallel API calls have been made to the SAP S/4HANA Cloud Business Partner (A2X) microservice to save processing time and to reduce the latency.

I’d like to request you to kindly provide your feedback or ask clarifying questions related to this post in the comment section below. Additionally, I’d like to invite you to submit any broader Kyma related questions in the Q&A area of the SAP BTP, Kyma runtime topic.

If the SAP BTP, Kyma runtime topic interests you, here are some other links that you may like:

Kyma at SAP

Kyma related SAP Tutorials for Developers

Lastly, if you liked this post, I’d like to request you to kindly hit the like icon, leave a comment below or share this post.

Going Jamstack with Kyma Runtime & building a high-performance web app

2022-02-24T03:28:46+01:00

Some common goals of web development projects are to build fast, secure, scalable and high-performance websites and apps. At the same time, there's also a need for delivering value faster.

Thankfully, these days, there are many tools and technologies readily available to help us.

This post demonstrates an example that uses the following state-of-the-art technologies to help achieve these goals and is inspired by the Jamstack architecture — “the modern way to build Websites and Apps that delivers better performance”^[1].

Next.js — "gives you the best developer experience with all the features you need for production"^[2]

Chakra UI — "gives you the building blocks you need to build your React applications"^[3]with "less code"^[3]and "more speed"^[3]

Go Programming Language — language of choice for backend microservices

Gin - an HTTP web framework written in Go that "features a Martini-like API with much better performance -- up to 40 times faster"^[4]

SAP HANA Cloud — a "high-performance in-memory database"^[5]

SAP Event Mesh — "a fully managed cloud service that allows applications to communicate through asynchronous events"^[6]

Kyma — "a cloud-native application runtime that combines the power of Kubernetes with a set of best-in-class tools and open-source components"^[7]

Kubernetes — "an open source container orchestration engine for automating deployment, scaling, and management of containerized applications"^[8]

Cloudflare CDN — "stops malicious traffic"^[9], "optimizes the delivery of website resources"^[9], "routes visitor requests to the nearest Cloudflare data center"^[9] and "provides security"^[9]

Next.js app with Kyma Eventing & Go backend connected to SAP HANA Cloud database

This example illustrates the following major components of SAP BTP, Kyma Runtime and its goal is to help you to get familiarized with some of the key features of SAP BTP, Kyma Runtime and to help you use your learnings in your own experiments using a free SAP BTP Trial account.

Containerized Microservice exposed via an API Rule — a Next.js app used as a client-side web app

Go Containerized Microservice — a Go app used as a backing service

Node.js Serverless Function

Kyma Eventing using either NATS (available with a free SAP BTP Trial account) or SAP Event Mesh (requires a paid account)

It is modelled as a simple conference registration system that stores user information in an SAP HANA Cloud database and sends a confirmation email to the user.

Its front-end is powered by a Next.js app that is deployed as a microservice on Kyma Runtime with a client-side user interface and an API endpoint.

Form submissions are sent via the API endpoint to Kyma Eventing, which can be either NATS by default, or optionally SAP Event Mesh.

A Serverless Function consumes events from the queue and sends a confirmation email to the user after saving the user's details to an SAP HANA Cloud database via a Go Microservice — a REST API Server microservice that is implemented in Go using Gin Web Framework.

The Go Microservice is exposed as a Kubernetes service with ClusterIP ServiceType (by default) and can be accessed via a hostname that is only accessible within the Kubernetes cluster, with the following format: <service-name>.<namespace>.svc.cluster.local

Note: Mutual TLS (mTLS) is enabled mesh-wide by default in Kyma Runtime. To be more specific, the mTLS mode is set to STRICT in a PeerAuthentication policy within the root istio-system namespace. As a result, all internal service to service communication within the Kubernetes cluster is encrypted by default using Transport Layer Security (TLS).

Solution Architecture

Sequence Diagram

Build and deployment steps

This web app can be deployed using a free SAP BTP Trial account via the following steps that will also help you learn how the major components of Kyma Runtime work together.

Note: Click the links below for more details.

Pre-requisites

Step 1 - Pre-requisite SendGrid setup steps

Step 2 - Build & deploy the Conference Registration app (Next.js app) — this step includes the link to the source-code repository

Step 3 - Deploy the Event Consumer function

Step 4 - Apply the Event Registration Subscription

Step 5 - Create an instance of SAP HANA Cloud

Step 6 - Deploy the Registrations REST API Server

Step 7 - Connect your web app running on Kyma Runtime to a domain via Cloudflare — optional step

Verification steps

Step 1 - Verify that all the resources of the app are running

Step 2 - View the environment variables in the config map

Step 3 - View the environment variables in the secret

Step 4 - View the API Rule

🎈 🎉 Step 5 - Launch the app and Register to attend the Tech Conference via the app

Troubleshooting steps

Using Cloudflare CDN

The DNS provider of the namespace needs be set as Cloudflare to use Cloudflare CDN.

For more Information, refer to: Step 7 - Connect your web app running on Kyma Runtime to a domain via Cloudflare.

Superb performance of the user facing app

Without Cloudflare CDN

Even without Cloudflare CDN, Google's PageSpeed Insights tool gave a Performance score of 100 to the Next.js web app for Desktop.

With Cloudflare CDN

With Cloudflare CDN, the time to interactive and total blocking time were reduced even further.

Blazing fast performance of the backing service

Although this web app only uses the HTTP POST API call of the Go Microservice to save customer records to the SAP HANA Cloud database, the Go Microservice has all the CRUD operations (Create, read, update and delete) implemented in it for the sake of demonstration.

The HTTP POST and PUT API calls of the Go Microservice had an almost similar response time. In order to not create too many records in the database during load testing, the HTTP PUT API calls were load tested, which make update requests and they had an average response time of 27.33 ms with 143.4 Hits per second when tested with BlazeMeter.

That is, on average each request was executed within about 1/36th of a second, which is blazing fast for a backing service — and that too with using a free SAP BTP Trial account!

Conclusion

Implementing the Jamstack architecture using the Kyma Runtime and an SAP HANA Cloud database results in extremely fast performance, which can be fine-tuned even further by either using caching services such as Redis or by horizontal as well as vertical scaling — key features of Kubernetes that can be easily configured. The added benefit of using the Kyma Runtime is the seamless connectivity provided by it to various SAP solutions as well as to services of other hyperscalers such as Google Cloud Platform, AWS & Azure using service operators — a great topic that is covered in the following blog post: Using Kubernetes operators with SAP BTP Kyma runtime.

As a next step, you could try to customize this example or put together the different components of Kyma Runtime that were covered in this example and build a web app for another use case using the Jamstack architecture.

If you'd like to dive deeper into some of the key topics that were covered in this blog post, you may find the resources listed in the Further Readings section below interesting.

Also, if you'd like to access the Go Microservice via a public URL from outside the Kubernetes cluster for testing it using an API client such as Postman, then you'll need to create an API Rule and expose the registrations-rest-api service. To do that, select the conference-registration namespace in the Kyma console. Next, under Discovery and Network, select API Rules. Then, click on Create API Rule. When creating the API Rule, you could also select to set its access strategy to OAuth2 to secure it. If you do that, you'll also need to create an OAuth client to be used to access it. You can do that by selecting Configuration and then OAuth Clients from the left menu in the Kyma console.

Kindly provide your feedback or feel free to ask clarifying questions related to this post in the comment section below. Additionally, I’d like to invite you to submit any broader Kyma related questions in the Q&A area of the SAP BTP, Kyma runtime topic.

If the SAP BTP, Kyma runtime topic interests you, here are some other links that you may like:

Kyma at SAP

Kyma related SAP Tutorials for Developers

Lastly, if you liked this post, kindly hit the like icon, leave a comment below or share this post. Thank you!

References

Jamstack: For fast and secure sites

Next.js by Vercel

Chakra UI

Gin Web Framework - GitHub

SAP HANA

What Is SAP Event Mesh?

Kyma - An easy way to extend enterprise applications on Kubernetes

Kubernetes Documentation

How Cloudflare works

Send personalized emails with SAP Customer Data Cloud webhooks and Kyma serverless functions

2022-06-28T20:41:33+02:00

SAP Customer Data Cloud webhooks send out asynchronous event notifications to custom notification URLs when specific events occur in SAP Customer Data Cloud flows such as login, registration, and account update.

This post demonstrates an example in which event notifications for the subscription updated event are sent to a Kyma serverless function, which has a code snippet that implements some business logic to eventually send a personalized welcome email to users.

Two Kyma serverless functions are used in this example and they work together as explained below.

The first serverless function receives notification messages and has a code snippet to extract all the events from each message and post them to an SAP Event Mesh Queue.

The second serverless function has a code snippet to consume the events from the SAP Event Mesh Queue and process them as follows:

First, it makes an accounts.getLiteToken REST API call to get a regToken that is required for the next step

Next, it makes an accounts.getAccountInfo REST API call to get the user's preferences

Finally, it sends a personalized email to the user based on the user's preferences using SendGrid Email Delivery Service

Note: All the functionality presented here are subject to change and may be changed by SAP at any time for any reason without notice.

Solution Architecture

Sequence Diagram

Source code repository

Here's a link to the source code of this example.

Build and deployment steps

This example can be setup using SAP Customer Data Cloud and a free SAP BTP Trial account via the following steps:

Note: Click the links below for more details.

Pre-requisites

Step 1 - Pre-requisite SendGrid setup steps

Step 2 - Create a lite registration screen in SAP Customer Data Cloud

Step 3 - Deploy a Memcached memory-caching service

Step 4 - Deploy the Webhook endpoint

Step 5 - Deploy the Event Consumer Serverless Function

Step 6 - Apply the Webhook Event Subscription

Verification steps

Step 1 - Verify that all the resources of the app are running

Step 2 - Subscribe for a newsletter and receive a customized confirmation email

Conclusion

This example shows how easy it is to extend SAP Customer Data Cloud using webhooks and SAP BTP, Kyma runtime. It also shows how to effortlessly and quickly create Kyma serverless functions using the Kyma console to add some simple code snippets without having to worry about the infrastructure details, which results in faster time to market as well as lower infrastructure total cost of ownership (TCO).

As a next step, you could explore the built-in observability tools of Kyma runtime for monitoring the serverless functions. With reference to this example, you could also try to create other Kyma serverless functions for your own use cases and implement SAP Customer Data Cloud webhook endpoints for some other events such as the account logged in or account updated events.

Kindly provide your feedback or feel free to ask clarifying questions related to this post in the comment section below. Additionally, I’d like to invite you to submit any broader Kyma related questions in the Q&A area of the SAP BTP, Kyma runtime topic.

If the SAP BTP, Kyma runtime topic interests you, here are some other links that you may like:

Kyma at SAP

Kyma related SAP Tutorials for Developers

Lastly, if you liked this post, kindly hit the like icon, leave a comment below or share this post. Thank you!

SAP Business Technology Platform - Serverless Functions | Hands-On Tutorial Videos

2023-02-10T14:22:24+01:00

A new playlist about SAP Business Technology Platform (BTP) serverless functions has been made available on our YouTube channel. Video tutorials by philip.mugglestone for the SAP HANA Academy and Partner Ecosystem Success.

In this article you will find the videos embedded with references and additional information.

A prerequisite, as covered in the first video of this series, is some familiarity with BTP. For the SAP BTP Onboarding article, visit

SAP BTP Developer Onboarding | Hands-on Video Tutorials

Anything to add? Leave a comment below.

Useful? Give us a like and share on social media.

Questions? Please use the community Q&A.

Thanks!

Hands-On Video Tutorials

Serverless Functions

In this series of hands-on tutorial videos we cover serverless functions in SAP Business Technology Platform (SAP BTP). Serverless functions allow you to build API- and event-based extensions which can be triggered on demand whilst reducing the implementation and operation effort of an application to the absolute minimum. SAP BTP, Kyma runtime provides a platform to run lightweight functions in a cost-efficient and scalable way using Node.js or Python.

Following along in the patented zero-to-hero format, you will be ready to start developing business applications on the SAP Business Technology Platform with minimal effort and no time wasted.

Video tutorials by philip.mugglestone for the SAP HANA Academy and Partner Ecosystem Success.

What You Will Learn

Watching the complete series of eight videos takes about an hour. What you will learn is

The concepts and what you need to know to get started with serverless functions

How to install and use the jump-start generator for serverless functions

How to use the generator to create serverless function projects
- using Python to interact with SAP HANA Cloud
- using Node.js and the SAP Cloud SDK to interact with different APIs
- providing enterprise security for the endpoints (authentication and authorization)
- subscribing to events
- managing source code using Git and GitHub
- incorporating an Application Router to facilitate interactive browser-based authentication

How access a serverless function created using the jump-start generator from SAP Build Apps including authentication and authorization.

YouTube Playlist

To bookmark the playlist on YouTube, go to

SAP Business Technology Platform - Serverless Functions

Documentation

For the references, visit

Serverless - Docs | Kyma

For the SAP BTP Onboarding series, go to

SAP BTP Developer Onboarding | Hands-on Video Tutorials

For the tutorials about the SAP BTP Kyma environment, see

Kyma Environment | Tutorial Video

Getting Started

Video Tutorial

In this hands-on video tutorial, Philip Mugglestone gets started with serverless functions in SAP BTP. After providing an introduction Philip covers prerequisites before showing how to install and use the jump-start generator for serverless functions.

https://youtu.be/GOznweBGewU?list=PLkzo92owKnVyyemLABuRYmyc29crnvxn3

Markers

0:13 Introduction

4:55 Prerequisites

6:34 Application Wizard

7:00 Jump-start Generator

9:57 Recap

References

For the prerequisites, visit

Kyma Environment | Tutorial Video

SAP HANA Cloud | Tutorial Video

SAP Build Apps | Tutorial Video

For the downloads, see

Application Wizard - Visual Studio Marketplace

Illustration

Run the SAP HANA Academy Function-as-a-service generator in Visual Studio Code with the Template Wizard.

Python and SAP HANA Cloud

Video Tutorial

In this hands-on video tutorial, Philip Mugglestone shows how to use the jump-start generator to create a serverless function project that uses Python to interact with SAP HANA Cloud.

https://youtu.be/j_rBuwarYqo?list=PLkzo92owKnVyyemLABuRYmyc29crnvxn3

Markers

0:22 Jump-start Generator

1:08 Code Review

5:54 Test

8:08 Tear Down

8:59 Recap

References

For the prerequisites, visit

SAP HANA Cloud | Tutorial Video

Illustration

View the function source code using the Kyma Dashboard.

Node.js and APIs

Video Tutorial

In this hands-on video tutorial, Philip Mugglestone shows how to use the jump-start generator to create a serverless function project that uses Node.js and the SAP Cloud SDK to interact with different APIs.

https://youtu.be/SERjGBG55kQ?list=PLkzo92owKnVyyemLABuRYmyc29crnvxn3

Markers

0:17 Jump-start Generator

1:05 Code Review

1:40 API Key

2:13 SAP Cloud SDK

3:00 Deploy

3:55 Test

5:45 Review Services

6:57 Recap

Authentication and Authorization

Video Tutorial

In this hands-on video tutorial, Philip Mugglestone shows how to use the jump-start generator to create a serverless function project that provides enterprise security for the endpoints incorporating both authentication and authorization.

https://youtu.be/2Qnkqs821Xc?list=PLkzo92owKnVyyemLABuRYmyc29crnvxn3

Markers

0:32 Jump-start Generator

0:55 Code Review

4:11 Deploy

5:13 Test

7:13 Assign Role Collections

8:03 Recap

Illustration

Get an authentication token using Postman.

Events

Video Tutorial

In this hands-on video tutorial, Philip Mugglestone shows how to use the jump-start generator to create a serverless function project that subscribes to events.

https://youtu.be/kVPgFiRn_tU?list=PLkzo92owKnVyyemLABuRYmyc29crnvxn3

Markers

0:27 Jump-start Generator

1:03 Code Review

3:04 Deploy

3:36 Test

6:34 Recap

References

For the documentation, see

Trigger a workload with an event

Illustrations

Triggering an event on the command line using curl.

View the result in the pod log file using the Kyma dashboard.

Git

Video Tutorial

In this hands-on video tutorial, Philip Mugglestone shows how to use the jump-start generator to create a serverless function project where the source code is managed via Git instead of being inline.

https://youtu.be/HBXazXXKnuY?list=PLkzo92owKnVyyemLABuRYmyc29crnvxn3

Markers

0:46 Jump-start Generator

1:09 Create Git Repository

4:32 Code Review

5:44 Clone Git Repository

6:05 Commit and Push Source Files

6:24 Deploy

7:21 Test

9:41 Recap

Illustrations

Commit source code update using git and GitHub.

SAP Build Apps

Video Tutorial

In this hands-on video tutorial, Philip Mugglestone shows how to access a serverless function created using the jump-start generator from SAP Build Apps including authentication and authorization.

https://youtu.be/1lnXZT4whXM?list=PLkzo92owKnVyyemLABuRYmyc29crnvxn3

Markers

0:29 Jump-start Generator

1:20 Launch SAP Build Apps

1:36 Assign Role Collections

2:15 Create Destination

4:25 Create Application in SAP Build Apps

7:41 Preview App

8:11 Recap

References

For the prerequisites, visit

SAP Build Apps | Tutorial Video

Illustrations

Configure SAP BTP destination REST API integration in SAP Build Apps.

Application Router

Video Tutorial

In this hands-on video tutorial, Philip Mugglestone shows how to use the jump-start generator to create a serverless function project that also incorporates an Application Router in order to facilitate interactive browser-based authentication.

https://youtu.be/bXnR9fUliVA?list=PLkzo92owKnVyyemLABuRYmyc29crnvxn3

Markers

0:30 Jump-start Generator

1:02 Code Review

2:36 Deploy

3:34 Assign Role Collections

4:00 Test

5:38 Tear Down

6:08 Recap

Share and Connect

Anything to add? Leave a comment below.

Useful? Give us a like and share on social media.

Questions? Please use the community Q&A.

Thanks!

If you would like to receive updates, connect with me on

LinkedIn > linkedin.com/in/dvankempen

Twitter > @dvankempen

For the author page of SAP PRESS, visit

Denys van Kempen

Over the years, for the SAP HANA Academy, SAP’s Partner Innovation Lab, and à titre personnel, I have written a little over 300 posts here for the SAP Community. Some articles only reached a few readers. Others attracted quite a few more. For your reading pleasure and convenience, here is a curated list of posts which somehow managed to pass the 10k-view milestone and, as sign of current interest, still tickle the counters each month.

Good Reads (my two cents)