In this blog post, I would like to share how to create destinations in SAP Cloud Platform and examples of different types that we support in SAP Leonardo IoT actions in detail.
Actions of type Service Integration and In-App Notification in SAP Leonardo IoT uses destinations defined in the SAP Cloud Platform cockpit.
Destinations can be created in two different ways:
or via
Destinations have to be of type HTTP and following Authentication types are supported:
Destinations can describe Cloud systems (reached via public internet) or On-Premise systems (reached via cloud connector). Depending on the location of the destination the proxy type has to defined accordingly:
Destinations of type HTTP need to have a URL. The URL can have tokens which are being replaced with actual values during the execution of an action. Those tokens are optional. Since destinations are defined outside of the Action Modeler UI, there is no value help available for those tokens. The token format is still the same however as what you would see in Action UI: ${token.name}. An example with the thing id, name and type tokens in an URL may look like this:
https://www.sap.com/do/${thing.type}/something?thingid=${thing.id}&thingname=${thing.name}
The destination name shall not contain any whitespace of special characters except underscores "_" and dashes "-". This restrictions is enforced in the destination service UI but not in the API. However, refrain from using those unsupported characters (e.g. spaces " " via API).
HTTP Headers can be defined using (additional) destination properties. In the destination service UI a property can be added by clicking the New Property button. The left field being the property name, the right being the property value.
Properties can also be defined via the destination service API.
To be used as a HTTP Header, the property has to have the prefix sap.iot.header. (including the last dot) followed by the name of the actual header variable. Examples would be sap.iot.header.X-Client-Version or sap.iot.header.X-Client-ID
SAP backend systems are often requiring a CRSF token, that's true for ERP systems but also for CPI. This protection can (often) be disabled but in case this is not appropriate or possible, the destination definition can be enhanced to indicate to the Action execution framework that CRSF need retrieved and added.
Following property is needed to enable CRSF Token:
In addition to CRSF token, Action execution framework also supports ETAG.
Following property is needed to enable ETAG Token:
Although not considered secure, there might be a need to use the action framework to connect to systems which are using self-signed certificates (e.g. demo or development systems).
The property sap.iot.certificationEnabled with the value false can used in a destination to indicate that the certificate check should not apply for this destination.
Although of type HTTP destination, the destinations will not appear and cannot be used for Actions of type HTTP but are rather be used for Actions of type In-App Notifications and represent another choice of notification server. Those destinations will probably rarely be used.
An (additional) destination property with the name sap.notification_server with the value true indicates that the destination is used for a notification server instead of being an endpoint of a (backend) system.
Destination with OAuth 2.0 Password grant + two HTTP Header variables:
Destination with Basic Authentication (e.g. for use with CPI):
Destination for on-premise 3rd party Notification Server:
Destination with OAuth 2.0 Client Credentials grant (e.g. used for calling SAP Leonardo IoT APIs):
Destination with OAuth 2.0 Client Credentials grant and URL tokens:
Destination with No Authentication (or payload based authentication):
Destination with CRSF token support:
As you can see from examples of destinations outlined in this blog post, SAP Leonardo IoT support multiple types of authentication method as well as tokens for robust service integration.
Actions of type Service Integration and In-App Notification in SAP Leonardo IoT uses destinations defined in the SAP Cloud Platform cockpit.
- For actions of type Service Integration, destinations contain the URL and credentials of (backend) systems which are the targets of these actions.
- For actions of type In-App Notification, destinations contain URL and credentials of 3rd party notification servers (e.g. the notification server of a SAP S/4 HANA on-premise system). Having destinations for this kind of action are optional since the built-in notification server is the default notification server and can be used without having any destination.
How to create destinations
Destinations can be created in two different ways:
- In the SAP cloud platform cockpit, within the menu on the left, Connectivity→ Destinations → New Destination (certain roles / permissions are needed to create a destination from the UI)
or via
- SAP cloud platform Destination Service API via HTTP POST request to https://destination-configuration.cfapps.sap.hana.ondemand.com/destination-configuration/v1/subaccou... (a bearer token is required as authentication)
Supported Destination Type and Authentication mechanisms
Destinations have to be of type HTTP and following Authentication types are supported:
- NoAuthentication
- BasicAuthentication
- OAuth2ClientCredentials (Client Credentialsand Password grant types are supported)
- OAuth2UserTokenExchange (Client Credentialsgrant is used, token is not exchanged as of 4/1/2019)
Supported Destination Proxy Types
Destinations can describe Cloud systems (reached via public internet) or On-Premise systems (reached via cloud connector). Depending on the location of the destination the proxy type has to defined accordingly:
- Internet
- OnPremise
Supported Destination URLs
Destinations of type HTTP need to have a URL. The URL can have tokens which are being replaced with actual values during the execution of an action. Those tokens are optional. Since destinations are defined outside of the Action Modeler UI, there is no value help available for those tokens. The token format is still the same however as what you would see in Action UI: ${token.name}. An example with the thing id, name and type tokens in an URL may look like this:
https://www.sap.com/do/${thing.type}/something?thingid=${thing.id}&thingname=${thing.name}
Supported Destination Names
The destination name shall not contain any whitespace of special characters except underscores "_" and dashes "-". This restrictions is enforced in the destination service UI but not in the API. However, refrain from using those unsupported characters (e.g. spaces " " via API).
Destinations with HTTP headers
HTTP Headers can be defined using (additional) destination properties. In the destination service UI a property can be added by clicking the New Property button. The left field being the property name, the right being the property value.
Properties can also be defined via the destination service API.
To be used as a HTTP Header, the property has to have the prefix sap.iot.header. (including the last dot) followed by the name of the actual header variable. Examples would be sap.iot.header.X-Client-Version or sap.iot.header.X-Client-ID
Destinations for endpoints which require a CRSF token
SAP backend systems are often requiring a CRSF token, that's true for ERP systems but also for CPI. This protection can (often) be disabled but in case this is not appropriate or possible, the destination definition can be enhanced to indicate to the Action execution framework that CRSF need retrieved and added.
Following property is needed to enable CRSF Token:
- sap.iot.XcsrfURL with the value of the URL which returns the CRSF token. This is often the same URL as the actual URL of the endpoint
Destinations for endpoints which require a ETAG token
In addition to CRSF token, Action execution framework also supports ETAG.
Following property is needed to enable ETAG Token:
- sap.iot.etagURL with the value of the URL which returns the ETAG token. This is often the same URL as the actual URL of the endpoint
Destinations for endpoints with a self-signed certificate
Although not considered secure, there might be a need to use the action framework to connect to systems which are using self-signed certificates (e.g. demo or development systems).
The property sap.iot.certificationEnabled with the value false can used in a destination to indicate that the certificate check should not apply for this destination.
Destinations defining a 3rd party notification server
Although of type HTTP destination, the destinations will not appear and cannot be used for Actions of type HTTP but are rather be used for Actions of type In-App Notifications and represent another choice of notification server. Those destinations will probably rarely be used.
An (additional) destination property with the name sap.notification_server with the value true indicates that the destination is used for a notification server instead of being an endpoint of a (backend) system.
Examples for destinations
Destination with OAuth 2.0 Password grant + two HTTP Header variables:
Destination with Basic Authentication (e.g. for use with CPI):
Destination for on-premise 3rd party Notification Server:
Destination with OAuth 2.0 Client Credentials grant (e.g. used for calling SAP Leonardo IoT APIs):
Destination with OAuth 2.0 Client Credentials grant and URL tokens:
Destination with No Authentication (or payload based authentication):
Destination with CRSF token support:
Summary
As you can see from examples of destinations outlined in this blog post, SAP Leonardo IoT support multiple types of authentication method as well as tokens for robust service integration.
- SAP Managed Tags:
3 Comments
