Blueprinting LOB extensions with SAP BTP services and API Management

[quovadis]

SAP BTP is a platform with several technical built-in-in services like connectivity, identity, application router etc and application runtimes like Cloud Foundry, Kyma, ABAP or Other.

The native platform services can be consumed from any runtime. For instance, the Other runtime options allows for consuming native services from anywhere (from other bespoke runtime or environment).

Disclaimer:

• Please note all the code snippets below are provided “as is”.


• All the x509 certificates, bearer access and refresh tokens and the likes have been redacted.


• This is not a replacement of SAP official documentation.


• I included pointers to relevant parts of the official documentation for your convenience.

The best practices for SAP BTP explain in more details the approach towards Extending Existing SAP Solutions Using namely: Extensions with Automated Configurations for the likes of  SAP S/4HANA Cloud, SAP SuccessFactors, SAP Cloud for Customer, SAP Commerce Cloud, SAP Field Service Management... Extensions with Manual Configurations with  SAP S/4HANA Cloud, SAP SuccessFactors and SAP Cloud for Customer Use Cases and Resources

Let's take a step back and try to understand how you could proceed to design and blueprint a bespoke extension of yours.

Blueprinting LOB extensions with SAP BTP services and API Management. Qu'est ce que c'est ?

 

Recently I got pulled into a project extending an existing SuccessFactors ECP on-premise integration with a digital twin on SAP BTP.

Overall, a design with a very classic architecture on SAP BTP with SAP BTP sub-account acting as a service provider for the SuccessFactors tenant, as depicted below:

SFSF Identity Provider is the single point of trust for business users coming to the platform.

It is like a border control agent granting access to the business territory regardless of the entry point.

The granted access is not permanent though. It is valid for the duration of the SAML WebSSO login session (this may vary from one IDP to another; it can be minutes, hours or even weeks or months, pretty much like with a visas entry system).

For instance, a business user TITI who has first logged into SFSF EC (right hand side of the diagram above) will not need to login again into the DigitalTwin application on BTP platform (left-hand side of the diagram) [ within the limits of its visa duration].

And vice versa, a user TOTO who first got access to the DigitalTwin portal will not need to authenticate again against the SFSF Employee Central tenant.

The SAML WebSSO authentication flow just described is commonly referred to as SP-initiated authentication flow.

Furthermore, on BTP platform side, the XSUAA service instance to which the digital twin is bound, is the OIDC provider and will implicitly "convert" SFSF users SAML WebSSO identities into users JWT tokens.

It is worth noticing that both destination and xsuaa services are technical services and available on a BTP sub-account level (=without any tie-in to a specific runtime).

This means that a DigitalTwin application could have been deployed not only on runtimes natively supported on SAP BTP but also on Other bespoke runtimes.

 

There is one more identity provider and one more service provider in this diagram...

Guess what, the destination service itself is this other identity provider as it will produce a saml bearer assertion that will be consumed by the ECP OAuth client. And the ABAP NW server hosting the ECP engine is this other service provider.

The destination service is like a travel agent acting on behalf of the business user to get the user to the destination.

The authentication flow just described is commonly referred to as IDP-initiated authentication dedicated to unattended, unmanned integration scenarii.

The project was at stalemate. I said to myself..hmm. that's actually pretty well documented here: SuccessFactors Employee Central with S/4HANA ECP (Employee Central Payroll).

So why the stalemate ?

Me again back to reading the manual. OK. SuccessFactors is a very "clever" piece of software. Well thought through and well designed.

And in this type of outbound integration towards an ECP payroll system a SFSF tenant can do it all.

• It provides the ECP's OAuth provider's x509 certificate.


• It handles the generation of a saml bearer assertion signed with the private key [of the public x509 certificate] and calls into the OAuth client token endpoint to retrieve the bearer access token.


• And then it calls into ECP ODATA APIs.

Thus, eventually, it does it all.

Putting it all together.

Me back to solving the problem. OK. The digital twin should be capable of offering the same "all-in" outbound destination features as the SFSF tenant can do.

Thus I split the problem into three separate tasks, namely:

• Task 1 covering the Step1,


• Task 2 covering the Steps 2,3,4


• Task 3 covering the Step5.

 

Task 1 (prepare destination).

Prepare destination with SAP BTP destination service.

That's relatively simple to achieve. The BTP's destination service is acting as the IDP provider in the IDP-initiated OAuth2 SAML Bearer assertion flow. (IDP-initiated means it is an unattended, unmanned authentication flow).

You can either be using your own x509 key pair [as trust] or be using the default destination service trust.

Good to know:

• if you are relying on the default (or fallback) destination service trust all you need to do is download (manually) either the x509 certificate or the destination service IDP metadata (which contains the x509 certificate) from its SAP BTP cockpit GUI.


• If this is your own key pair then you are managing the certificate yourself but you are still delegating the business user SSO propagation to the destination service.

I personally prefer the latter approach as this can be fully automated with destination service APIs and does not require any manual operation.

Here follows a sample destination definition with the x_user_token.jwks_uri property pointing to the token_keys url of the BTP sub-account the SFSF tenant IDP trust has been established with (as shown in the simplified architecture diagram above).

This will in turn enable a seamless business user propagation with the XSUAA service on the BTP side acting as an OIDC provider.

{

  "Name" : "QUOVADIS",

  "Type" : "HTTP",

  "URL" : "https://<FQDN>/sap/opu/odata/sap/PYC_CONF_SRV/?sap-client=<***>",

  "Authentication" : "OAuth2SAMLBearerAssertion",

  "ProxyType" : "Internet",

  "KeyStorePassword" : <Password>,

  "tokenServiceURLType" : "Dedicated",

  "audience" : <audience>,

  "authnContextClassRef" : "urn:oasis:names:tc:SAML:2.0:ac:classes:x509",

  "Description" : "QUOVADIS",

  "x_user_token.jwks_uri" : "https://<indentityzone>.authentication.<region>.hana.ondemand.com/token_keys",

  "tokenServiceUser" : <OAuth client user>,

  "tokenServiceURL" : "https://<FQDN>/sap/bc/sec/oauth2/token?sap-client=<***>",

  "tokenServicePassword" : <password>,

  "KeyStoreLocation" : <location>,

  "clientKey" : <OAuth client user>,

  "nameIdFormat" : "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",

  "scope" : "PYC_CONF_SRV_0001",

  "userIdSource" : "user_name"

}

 

Task 2 (prepare the OAuth communication channel).

 

 

Prepare the OAuth communication channel with ABAP server.

That's the hardest part of the configuration. You may not have done it before but the ABAP skills are a "must have".

I have never done it before, However, with ABAP is like with riding a bike, once you've learnt it you never forget it. Indeed my ABAP skills helped me overcome all the hurdles on the way.

On a side note, the whole process is also very nicely documented on public SCN wiki pages here.

For step by step instructions please refer to my sibling blog post: ABAP acting as a Resource Server. App2App integration with OAuth2SAML2BearerAssertion flow. | SAP Bl...

Good to know:

• The ABAP transactions required to set up the OAuth2 communication may require a set of enhanced user authorisations.


• You may need to secure access to your security ABAP team to get help with the process.

 

Task 3 (Find destination).

Find destination with SAP BTP destination service.

Please note that an ABAP server OAuth Provider does not expose an "idp" endpoint to generate a signed saml bearer assertion.

This where SAP BTP destination service comes to the rescue.

The destination service find destination API call is all you need.

Albeit under one condition - that the ABAP system is exposed to the public internet via its SAP Gateway. As described in SAP help pages - Prerequisites

Here follows the json output from the find destination call to SAP BTP destination service with the above destination definition. Based on that definition the destination service will internally build a saml assertion and will call into the OAuth client token endpoint to get the bearer access token.

Please note the [business] user identity used by the destination service to build the saml assertion is either implicitly provided by the XSUAA's user JWT or it has to be provided in the X-user-token header of the find destination call.

And in either case the mandatory  x_user_token.jwks_uri property is a pointer to the jwks uri of the OIDC provider (in this very case the XSUAA service is the OIDC provider).

{

  "owner": {

    "SubaccountId": "<SubaccountId>",

    "InstanceId": null

  },

  "destinationConfiguration": {

  "Name" : "QUOVADIS",

  "Type" : "HTTP",

  "URL" : "https://<FQDN>/sap/opu/odata/sap/PYC_CONF_SRV/?sap-client=<***>",

  "Authentication" : "OAuth2SAMLBearerAssertion",

  "ProxyType" : "Internet",

  "KeyStorePassword" : <Password>,

  "tokenServiceURLType" : "Dedicated",

  "audience" : <audience>,

  "authnContextClassRef" : "urn:oasis:names:tc:SAML:2.0:ac:classes:x509",

  "Description" : "QUOVADIS",

  "x_user_token.jwks_uri" : "https://<indentityzone>.authentication.<region>.hana.ondemand.com/token_keys",

  "tokenServiceUser" : <OAuth client user>,

  "tokenServiceURL" : "https://<FQDN>/sap/bc/sec/oauth2/token?sap-client=<***>",

  "tokenServicePassword" : <password>,

  "KeyStoreLocation" : <location>,

  "clientKey" : <OAuth client user>,

  "nameIdFormat" : "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",

  "scope" : "PYC_CONF_SRV_0001",

  "userIdSource" : "user_name"

  },

  "certificates": [

    {

      "Name": <location>,

      "Content": "MIIQeAIBAzCCEDIGCSqGSIb3DQEHAaCCECMEghAfMIIQGzCCCggGCSqGSIb3DQEHAaCCCfkEggn1MIIJ8TCCCe0GCyqGSIb3PG/HcO5xW0ai3ZkwPTAhMAkGBSsOAwIaBQAEFMyS26dKft/dWRSIVg/SQvDnQmaSBBQTST14Lse+rKA3igKg4Q7gzIB0mAICBAA=",

      "Type": "CERTIFICATE"

    }

  ],

  "authTokens": [

    {

      "type": "Bearer",

      "value": "AFBWi3u9Htuzw77bWyiBXc7kUQjy51gIBlvMSGqJN07****",

      "http_header": {

        "key": "Authorization",

        "value": "Bearer AFBWi3u9Htuzw77bWyiBXc7kUQjy51gIBlvMSGqJN07f****"

      },

      "expires_in": "3598",

      "scope": "PYC_CONF_SRV_0001"

    }

  ]

}

 

Task1+Task2+Task3 === Bon voyage:)

 

As a result the digital twin can talk to the ECP payroll instance on premise extension on behalf of  SFSF tenant business users whose identities are propagated securely by the destination service towards the ECP payroll system. Task1 + Task3 = SAP BTP Destination Service Task 2 = ECP (ABAP with SAML2/SU01/PFCG/SOAUTH2) Bon voyage:)

 

Conclusion.

As a rule of thumb, it is so much worth decomposing your solution into smaller building blocks and try to assemble them - pretty much as you would be doing it with your kids lego sets.

My own experience is that often you come up with a way simpler solution than the initial design!

This is how I ended up with using API Management, part of SAP Integration Suite, for both calling the destination service APIs and/or implementing the saml bearer authentication with the security policies SAP ships on API Business Hub.

 

---

Appendix

 

 

Configuring OAuth 2.0

SAP currently supports the following OAuth 2.0 flow for unattended integrations:

• Grant type extension with OAuth 2.0 SAML bearer assertion.


• To configure an OAuth 2.0 SAML bearer assertion flow, proceed as follows:
  
  
  
  1. Establish SAML 2.0 trust relationship with the issuer of the SAML 2.0 assertion (see Configuring a Trusted Identity Provider for OAuth 2.0).
  
  
  2. Configure OAuth 2.0 clients (see Configuring an OAuth 2.0 Client).
  
  
  3. Configure resource owner authentication with a SAML 2.0 bearer assertion (see Configuring a Grant Type Extension with an OAuth 2.0 SAML Bearer).
  
  
  4. Grant access to the resource owner by assigning the S_SCOPE authorization object (see Resource Owner in OAuth 2.0).
  
  
  
  

SAML 2.0 Bearer Assertion Flow for OAuth 2.0

Prerequisites

• There is a trust relationship between the authorization server and the issuer of the SAML 2.0 bearer assertion, which is the identity provider.


• The resource owner must be known by the SAML 2.0 identity provider.


• The resource owner is a user who has the roles that grant him or her the authorizations to access the resources that are to be accessed by the cloud or web-based application.


• In the configuration of the OAuth 2.0 client, you have assigned OAuth 2.0 scopes in Scope Assignment.


• You have assigned a cloud or Web-based service application to an OAuth 2.0 client.


• The resource owner must also be authorized to delegate access to an OAuth 2.0 client.


• The OAuth 2.0 client (user with user type System) must have the right to access the resources.


• The OAuth 2.0 client must have an entry with the trusted identity provider for OAuth 2.0.


• You have activated the grant type SAML 2.0 Bearer Active in the OAuth 2.0 client.


• You have installed an application that supports OData on AS ABAP, such as SAP NetWeaver Gateway. For more information, see SAP Note 1688545 .

For more information, see Configuring OAuth 2.0.

 

__________

Additional resources.

You may refer to Best Practices for SAP BTP - SAP Help Portal for more information.

Also available as PDF here: Best Practices for SAP BTP

Quovadis or how to find your destination?

How to generate SAML bearer assertion token with SAP BTP Destination Service?

ABAP acting as a Resource Server. App2App integration with OAuth2SAML2BearerAssertion flow. | SAP Bl....

Demystifying XSUAA in SAP Cloud Foundry