Putting it all together.

quovadis · ‎2021 Oct 07

S/4HANA Cloud Product Master APIs with OAuth2SAMLBearerAssertion.

SAP Extensibility Explorer for SAP S/4HANA Cloud

I previously shared how to implement either ODATA v2 or ODATA v4 APIs from SAP_COM_0009 scenario with SAP API Management, part of SAP Integration Suite bundle.

Let me describe how to do it with SAP BTP destinations.

Pre-requisites:

SAP BTP sub-account with destination service (SAP BTP trial sub-account will do)

S/4HANA Cloud public tenant with admin access.

Disclaimer:

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

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

Images/data in this blog post is from SAP internal sandbox, sample data, or demo systems. Any resemblance to real data is purely coincidental.

Access to online resources referenced in this blog may be subject to a contractual relationship with SAP and a S-user login may be required.

S/4HANA Cloud: Product Integration (SAP_COM_0009)

S/4HANA Cloud APIs for Product Master are implemented within the Product Integration scenario SAP_COM_0009.

As a reminder you must have set up a communication arrangement in your S/4HANA Cloud system with the Product Integration scenario SAP_COM_0009.

Please refer to the SAP Best Practices Explorer Customer Guide: Scope Item 1RO , Configuring Communication Scenario SAP_COM_0009 page 39 onwards for more details.

Putting it all together.

Quoting after Scope Item 1RO Setting Up OAuth 2.0 page 49 onwards:

OAuth 2.0 is a widely-adopted security protocol for protection of resources over the Internet. It allows an application to request authentication on behalf of users with third-party user accounts, without the user having to grant its credentials to the application. You can set up inbound OData interface API_PRODUCT_SRV, API_PROD_HIER_NODES_SRV, API_PROD_HIER_PRODS_SRV, API_PRODUCTTYPE, API_PRODUCTGROUP_2 with OAuth 2.0 authentication.

Let's dissect the following three ProductMaster inbound ODATA APIs as follows:

COMM_0009 inbound API	ODATA version	ODATA interface (Service Group Name)	supported user identity with OAuth2SAMLBearerAssertion flow
1. Product Master (A2X)	v2	API_PRODUCT_SRV	business user or communication user
2. Product Type	v4	API_PRODUCTTYPE	communication user only
3. Product Group Data	v4	API_PRODUCTGROUP_2	communication user only

ad1. Product Master (A2X).

Product Master (A2X) is an ODATAv2 API.

Moreover it supports user propagation with OAuth2SAMLBearerAssertion flow with either type of a user: a business user or a technical (communication) user.

Here goes S4HC-ProductMaster destination definition where the business user identity is used.

{

  "owner": {

    "SubaccountId": "<SubaccountId>",

    "InstanceId": null

  },

  "destinationConfiguration": {

    "Name": "S4HC-ProductMaster",

    "Type": "HTTP",

    "URL": "https://my30xxxx-api.s4hana.ondemand.com/sap/opu/odata/sap/API_PRODUCT_SRV",

    "Authentication": "OAuth2SAMLBearerAssertion",

    "ProxyType": "Internet",

    "tokenServiceURLType": "Dedicated",

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

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

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

    "tokenServiceUser": "<CommunicationUser>",

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

    "tokenServicePassword": "<CommunicationUserPassword>",

    "clientKey": "<CommunicationUser>",

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

    "scope": "API_PRODUCT_SRV_0001",

    "SystemUser": "<business user email address>"

  },

  "authTokens": [

    {

      "type": "Bearer",

      "value": "-hY-fl00HuyJ7h9my7nb2ySsRcuwuWJ4YdcjDK24gAxxxxxx",

      "http_header": {

        "key": "Authorization",

        "value": "Bearer -hY-fl00HuyJ7h9my7nb2ySsRcuwuWJ4YdcjDK24gAxxxxxx"

      },

      "expires_in": "3600",

      "scope": "API_PRODUCT_SRV_0001"

    }

  ]

}

Consuming the ODATA endpoint from a 3rd party application (Postman)

ad2. ProductType

ProductType is an ODATAv4 API.

It does support the user identity propagation with OAuth2SAMLBearerAssertion flow but only with the communication (technical) user.

The reason behind it is that currently there is no way to assign the relevant scope to the business user.

{

  "owner": {

    "SubaccountId": "afbac4de-9d13-4ef5-b480-f1d80ccb9ad4",

    "InstanceId": null

  },

  "destinationConfiguration": {

    "Name": "S4HC-ProductType",

    "Type": "HTTP",

    "URL": "https://my30xxxx-api.s4hana.ondemand.com/sap/opu/odata4/sap/api_producttype/srvd_a2x/sap/producttype/0001/",

    "Authentication": "OAuth2SAMLBearerAssertion",

    "ProxyType": "Internet",

    "tokenServiceURLType": "Dedicated",

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

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

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

    "tokenServiceUser": "<CommunicationUser>",

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

    "tokenServicePassword": "<CommunicationUserPassword>",

    "clientKey": "<CommunicationUser>",

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

    "scope": "API_PRODUCT_SRV_0001 OV4:API_PRODUCTGROUP_2 OV4:API_PRODUCTTYPE",

    "SystemUser": "<CommunicationUser>"

  },

  "authTokens": [

    {

      "type": "Bearer",

      "value": "-hY-fl00HtyJ8Mf06r0Bc7n14UhL3vLHwO-Vx1IJvQxxxxxx",

      "http_header": {

        "key": "Authorization",

        "value": "Bearer -hY-fl00HtyJ8Mf06r0Bc7n14UhL3vLHwO-Vx1IJvQxxxxxx"

      },

      "expires_in": "3600",

      "scope": "API_PRODUCT_SRV_0001 OV4:API_PRODUCTGROUP_2 OV4:API_PRODUCTTYPE"

    }

  ]

}

Consuming the ProductType endpoint from a 3rd party application (Postman)

ad3. Product Group Data - Read

Product Group Data - Read is an ODATAv4 API.

It does support the user identity propagation with OAuth2SAMLBearerAssertion flow but only with the communication (technical) user.

The reason behind it is that currently there is no way to assign the relevant scope to the business user.

{

  "owner": {

    "SubaccountId": "<SubaccountId>",

    "InstanceId": null

  },

  "destinationConfiguration": {

    "Name": "S4HC-ProductGroupData",

    "Type": "HTTP",

    "URL": "https://my30xxxx-api.s4hana.ondemand.com/sap/opu/odata4/sap/api_productgroup_2/srvd_a2x/sap/productgroup/0001",

    "Authentication": "OAuth2SAMLBearerAssertion",

    "ProxyType": "Internet",

    "tokenServiceURLType": "Dedicated",

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

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

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

    "tokenServiceUser": "<CommunicationUser>",

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

    "tokenServicePassword": "<CommunicationUserPassword>",

    "clientKey": "<CommunicationUser>",

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

    "scope": "API_PRODUCT_SRV_0001 OV4:API_PRODUCTGROUP_2 OV4:API_PRODUCTTYPE",

    "SystemUser": "<CommunicationUser>"

  },

  "authTokens": [

    {

      "type": "Bearer",

      "value": "-hY-fl00HtyJ8ImbinzA5ggEtf7TwlLH-fGlKFUCeAxxxxxx",

      "http_header": {

        "key": "Authorization",

        "value": "Bearer -hY-fl00HtyJ8ImbinzA5ggEtf7TwlLH-fGlKFUCeAxxxxxx"

      },

      "expires_in": "3600",

      "scope": "API_PRODUCT_SRV_0001 OV4:API_PRODUCTGROUP_2 OV4:API_PRODUCTTYPE"

    }

  ]

}

Consuming the ProductGroup endpoint from a 3rd party application (Postman)

Conclusion

Let's summarise our findings.

With the help of SAP BTP destination service one can easily generate bearer access tokens for each of the ODATA API.

These APIs can be subsequently consumed from anywhere.

However only the ProductMaster ODATAv2 API can be consumed with a business user identity. The remaining four ODATAv4 API only accept the communication user identity:

The ProductMaster ODATAv2 API_PRODUCT_SRV supports a business user identity propagation as the OAuth scope can be granted to the business user via the SAP_CMD_BC_PR_MAINT_PC business catalog.

On the other hand, as aforementioned, currently there is no way to assign the OAuth scope to a business user for either of the ODATAv4 inbound APIs.

Which translates these APIs only support communication user identity propagation with the OAuth2SAMLBearerAssertion flow.

If this user identity propagation asymmetry were an issue at all, please note all these APIs support the x509 client certificate authentication method as well, which overall is a good alternative when the communication user is to be used (by design the x509 client certificate uniquely designates a given communication user).

As always, please refer to the SAP Best Practices Explorer Scope Item 1RO for Data Master Integration scenario test and setup instructions.

__________

Appendix

Maintain Business User

The business user must have the business role BR_PRODMASTER_SPECIALIST (which is based on a role template SAP_BR_PRODMASTER_SPECIALIST) assigned as explained in the setup instructions on page 50

Destination definitions templates

// destinationConfiguration template with SystemUser as username

//

{

    "Name": "<Name>",

    "Type": "HTTP",

    "URL": "https://my30xxxx-api.s4hana.ondemand.com/sap/opu/<ODATA API suffix>",

    "Authentication": "OAuth2SAMLBearerAssertion",

    "ProxyType": "Internet",

    "tokenServiceURLType": "Dedicated",

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

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

    "Description": "Description",

    "tokenServiceUser": "<CommunicationUser>",

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

    "tokenServicePassword": "<CommunicationUserPassword>",

    "clientKey": "<CommunicationUser>",

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

    "scope": "<scope list>",

    "SystemUser": "<CommunicationUser>"

}

// destinationConfiguration template with SystemUser as email address

//

{

    "Name": "<Name>",

    "Type": "HTTP",

    "URL": "https://my30xxxx-api.s4hana.ondemand.com/sap/opu/<ODATA API suffix>",

    "Authentication": "OAuth2SAMLBearerAssertion",

    "ProxyType": "Internet",

    "tokenServiceURLType": "Dedicated",

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

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

    "Description": "Description",

    "tokenServiceUser": "<CommunicationUser>",

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

    "tokenServicePassword": "<CommunicationUserPassword>",

    "clientKey": "<CommunicationUser>",

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

    "scope": "<scope list>",

    "SystemUser": "<business user email address>"

}

API Business Hub try-out

Destination service REST APIs package on API Business Hub: https://api.sap.com/api/SAP_CP_CF_Connectivity_Destination/resource

First you will need to configure your custom sandbox environment pointing to your own destination service as follows:

a. Assuming both the destination configuration and the S4HC communication arrangement have been set up accordingly you can try to call out this destination name using your custom sandbox environment as depicted below:

b. In the case of S4HC-ProductMaster destination definition used in this blog no additional headers are required. They were all got removed before proceeding.

Good to know:

Make sure to remove all the optional headers that are not being used; otherwise errors will be thrown.

c. Subsequently, code snippets will be generated accordingly as follows:

d. last but not least the Run button allows to trigger the destination call-out:

Good to know:

you can use the auto-generated code snippet as a template for embedding the destination call-out logic into your own code in the programming language of your choice.

__________