Putting it all together

quovadis · ‎2021 May 10

This instalment belongs to a mini series of blogs on OAuth2SAMLBearerAssertion Flow leveraging SAP BTP Destination Service with S/4HANA Cloud inbound ODATA services. Bon voyage:)

Set Up Authentication for SAP S/4HANA Cloud Extensions

There is ample and relatively accurate official documentation on how to configure S/4HANA Cloud for Side by Side or In-App integration with the APIs.

And when it comes to inbound communication (e.g. you are calling into S4HC APIs) the end to end user SSO is not only essential but paramount.

And precisely, OAuth2SAMLBearerAssertion authorisation flow allows for propagation of a user's identity from any client application deployed anywhere all the way through to an ODATA-based asset management service (like SAP S/4HANA Cloud in this instance).

A truly end to end Single Sign On!

Putting it all together

As a baseline we will use the following User Propagation Scenario: User Propagation from the Cloud Foundry Environment to SAP S/4HANA Cloud.

This scenario is applicable to any brief including with the client application deployed as Other runtime (== other than SAP BTP CF or Kyma runtimes).

Good to know:

The SAP BTP destination service can be used with Other custom runtimes. This translated into plain English means your application does not have to be deployed on BTP but you can still leverage the SAP BTP Destination service.

The following authentication scenarios are supported with SAP S/4HANA Cloud:
- Basic Authentication (inbound and outbound connections)
- OAuth 2.0 SAML Bearer Assertion (inbound connections). This is scenario being described in this blog.
- OAuth 2.0 Client Credentials (outbound Connections)
- No Authentication (outbound connections)

Configure OAuth communication with S/4HANA Cloud.

We will follow the sequence of the configuration tasks as described in the official documentation, namely:

Configuration Tasks

Perform these steps to set up user propagation between S/4HANA Cloud and the SAP BTP Cloud Foundry environment.

Tasks

Configure Single Sign-On between S/4HANA Cloud and the Cloud Foundry Organization on SAP BTP

Configure OAuth Communication

Configure Communication Settings in S/4HANA Cloud

Configure Communication Settings in SAP BTP

Consume the Destination and Execute the Scenario

Also Set Up Authentication for SAP S/4HANA Cloud Extensions is very relevant piece of documentation.

Quovadis-S4HC.

Assuming you have the right level of access to your target S4HC system and that you have created a communication user you may now create there your own OAuth2.0 client application (=communication system+communication arrangement).

Let's call it Quovadis-S4HC.

Configure the OAuth2.0 Identity Provider in the Communication System.

One piece of information you will need from the Destination service created on SAP BTP sub-account level is the trust's public x509 certificate that you will need to insert into the Quovadis-S4HC OAuth2.0 Communication System as depicted below:

A fairly common question. What is the Provider Name?

The provider name designated the issuer of the saml bearer assertion. The provider name defaults to the Issuer's x.509 certificate CN (Common Name).

When uploading the destination service signing certificate, the CN will be populated automatically to both the Signing Certificate Subject and Issuer sections to the left .

Make sure you copy the CN field and assign it as a Provider Name (as it will not be populated).

Good to know:

Under the bonnet this will result in the creation of a custom OAuth2.0 Identity Provider that will be used in the IDP-initiated flow when your 3rd party client app has called into the oauth token validation endpoint...

You might also use a custom Provider Name; however this requires setting additional property called assertionIssuer (which designates the issuer of the saml assertion) in the destination definition. This is documented here at the section Set Up SAP BTP Side point 3b.

Last but not least you can create a communication arrangement for a given communication scenario.

Create a communication arrangement for a given communication scenario.

Creating a communication arrangement (that uses this communication system) will result in creating of an OAuth2.0 client with the client_id and client_secret equal the communication user name and password respectively.

The SAML2 Audience is the service provider and is the value

of your S4HC tenant URL.



The Token service URL is the OAuth2.0 IdP endpoint. 

The Destination service will call this endpoint with the saml 

assertion it has generated internally.



You can add the required scope as a Token service URL 

endpoint's query parameter (?scope=<scope>)

or you can pass it in the scope property in the destination 

definition.

You will need the above OAuth2.0 client details when creating a destination definition below.

Creating a destination.

Create a Destination service instance on a BTP sub-account level (that can be done with a trial BTP account as well)

Before you can configure the API hub sandbox environment you will need to have created an instance of the destination service.

Choose Other as the runtime environment and give the service instance a name, for instance Quovadis

Next configure your API Business Hub sandbox with the above destination service credentials.

Please refer to the following article on the details for the sandbox environment configuration with SAP API Business Hub.

You can create a destination definition using either GUI of the SAP BTP sub-account or programmatically calling the destination service APIs.

Assuming you will be rehearsing the access to the destination 

service APIs with the SAP Business API Hub sandbox environment

or alternatively using the API Management,

you do not need to write a single line of code.



All you need to do is create a definition of your destination

as demonstrated below.



Then you may call that destination with the destination 

service find api any time you need to procure a bearer access token

to authorize access to remote S4HC resource.

Most of the values in the below destination definition will need to come from the OAUTH2.0 service - the so called Communication Arrangement - from S4HC tenant.

Create destination definition programmatically with API.

You could grab the below json structure, enter your values and use it with the destination service POST/PUT destinations APIs

Post (=create) a new destination:

Put (=update) an existing destination:



https://destination-configuration.cfapps.xx99.hana.ondemand.com/destination-configuration/v1/subacco...



{

  "Name": "Quovadis-S4HC",

  "Type": "HTTP",

  "URL": "https://my999999.s4hana.ondemand.com/sap/opu/odata/sap/API_PURCHASEORDER_PROCESS_SRV",

  "Authentication": "OAuth2SAMLBearerAssertion",

  "ProxyType": "Internet",

  "tokenServiceURLType": "Dedicated",

  "audience": "https://my999999.s4hana.ondemand.com",

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

  "Description": "https://api.sap.com/api/API_PURCHASEORDER_PROCESS_SRV/overview",

  "clientKey": "<client_id>", //==communication user name

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

  "scope": "API_PURCHASEORDER_PROCESS_SRV_0001",

  "x_user_token.jwks_uri": "https://<identityzone>.authentication.xx99.hana.ondemand.com/token_keys",

  "tokenServiceUser": "<client_id>", //==communication user name

  "tokenServiceURL": "https://my999999-api.s4hana.ondemand.com/sap/bc/sec/oauth2/token",

  "userIdSource": "email",

  "tokenServicePassword": "<client_secret>" //==communication user password

}

Asserting user's identity

A user's identity.That's the most important part of the setup.

You have a choice between a static technical user, or a dynamic user.



The destination service supports dynamic user indentities via 

a user JWT token. 

You may need to provide an access url to OpenID Connect provider metadata.

Please add in the destination service's x_user_token.jwks_uri property 

the value of the jwks_uri url from the OIDC provider metadata.



As aforementionned, the value of this property must come 

from the OIDC user identity provider metadata.

In case you are using the XSUAA service as the OIDC provider you could call

the .well-known/openid-configuration endpoint of the XSUAA service url,

in order to retrieve the OIDC metadata, for instance:



https://<identityzone>.authentication.xx99.hana.ondemand.com/.well-known/openid-configuration



then you will look for jwks_uri and copy the value of jwks_uri 

(it is yet another url) to the x_user_token.jwks_uri property 

in the destination defintion.



Disclaimer:

In a productive scenario you must be using a user JWT token!

However a technical user may be used in the initial sandboxing 

and concept proving of the entire configuration.



In either case, the user must exist in both the client application 

and the target S4HC system.

Finding destination.Obtaining the bearer access token to call into S4HC business API.

Find destination API call:



https://destination-configuration.cfapps.xx99.hana.ondemand.com/

destination-configuration/v1/destinations/Quovadis-S4HC



Please substitute xx99 by the BTP subaccount region where you

have provisionned the destination service on a subaccount level,

for instance 'eu10' etc.

As a result of this call you will get the bearer access token that you can use to call into S4HC OData API, and retrieve the assets like Purchaser Orders or Sales Orders, your user has been granted access to, for instance:

 "authTokens": [

    {

      "type": "Bearer",

      "value": "-hY-nuoXHtusskpbJBHeC4EX8jPi0jYZ7RAZP9Q7_WadI111",

      "http_header": {

        "key": "Authorization",

        "value": "Bearer -hY-nuoXHtusskpbJBHeC4EX8jPi0jYZ7RAZP9Q7_WadI111"

      },

      "expires_in": "3600",

      "scope": "API_PURCHASEORDER_PROCESS_SRV_0001"

    }

  ]