SAP BTP, SAP ABAP Development, SAP ABAP Extensibility, SAP BTP Security, SAP S/4HANA

Consuming a Business Technology Platform service from an S/4 HANA system using SM59 destination with OAuth

Scenario Description

In this blog, I present an introduction to OAuth and explain how to implement and configure the consumption of an OAuth-enabled service provided by the SAP Business Technology Platform from an SAP S/4HANA system on release 2021 or above (here workflow service on cloud foundry is used as an example) using the CL_HTTP_CLIENT class and SM59 destination. The blog only focuses on the client credentials and SAML Bearer Assertion grant types.

We create a simple runnable ABAP class consuming an SM59 destination pointing to the REST API offered by the workflow service for cloud foundry. This is used to get details of the workflow definitions in the subaccount on SAP Business Technology Platform. The SM59 destination shall be configured for using OAuth with client credentials or SAML Bearer flow, as desired.

Note: Here, the workflow service’s REST API is used only for demonstration. In a real use case where you need to connect to the workflow service, there is a dedicated API for this.

Introduction to OAuth

In the traditional client-server authentication model, the client requests an access-restricted resource (protected resource) on the server by authenticating with the server using the resource owner’s credentials (basic authentication). To provide third-party applications with access to restricted resources, the resource owner shares its credentials with the third party.

Third-party application access in client-server model

This creates several problems and limitations such as:

  • Third-party applications may store the resource owner’s credentials for future use, potentially as clear text or with poor encryption.
  • Servers are required to support password authentication, despite the security weaknesses inherent in passwords.
  • Third-party applications gain overly broad access to the resource owner’s protected resources, leaving resource owners without any ability to restrict duration or access to a limited subset of resources
  • Resource owners cannot revoke access to an individual third party without revoking access to all third parties, and must do so by changing the password
  • Compromise of any third-party application results in compromise of the end-user’s password and all the data protected by that password

OAuth addresses these issues by introducing an authorization layer and separating the role of the client from that of the resource owner. In OAuth, the client requests access to resources controlled by the resource owner and hosted by the resource server. The client is issued a different set of credentials than those of the resource owner.

Instead of using the resource owner’s credentials to access protected resources, the client obtains an access token — a string denoting a specific scope, lifetime, and other access attributes. Access tokens are issued to third-party clients by an authorization server with the approval of the resource owner. The client uses the access token to access the protected resources hosted by the resource server.

Third-party application access with OAuth

OAuth Client Credentials v/s SAML Bearer Assertion

In this blog, I cover the client credentials and SAML Bearer assertion grant types. It is therefore important to know when to use each of these.

The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user. This works with the client ID and client secret.

The OAuth SAML bearer assertion grant on the other hand can be used to propagate the principal (the logged on user) from S/4HANA to the Business Technology Platform.

How to use OAuth to connect from SAP S/4 HANA to an SAP Business Technology Platform service

The following image shows the activities performed by different personas

Activities performed by different personas

The steps broadly involve the following:

  • Create OAuth 2.0 client profile in SE80
  • Establish Trust between the S/4HANA system and the subaccount on SAP Business Technology Platform
  • Create OAuth configuration with the appropriate type (SAML Bearer/Client Credentials/…) using the profile created above
  • Create destination to connect to the BTP service in SM59
  • Consume the destination in code

The subsequent sections of this blog detail the steps listed above.

1. Gather the necessary information needed for configuration

1.1. As security administrator of the subaccount on SAP Business Technology Platform

Download SAML metadata from the subaccount on SAP Business Technology Platform, where the service instance to be consumed (workflow in our example) is created.

  • As security administrator of the subaccount where the service resides, go to the “Trust Configuration” section in the menu and use the “Download SAML Metadata” button
  • Open the SAML metadata file and note the following details. These details would be used in future steps
    • EntityID – This is the entity ID of the SAML service provider and will be used as SAML Audience for our OAuth SAML Bearer assertion configuration later
  • Location of the SAML binding URI (which contains /oauth/token) – This would be our token service URL in the configuration

1.2. As space developer of the subaccount on SAP Business Technology Platform

Go to the Business Technology Platform service instance (workflow service in this example) and read the service key details. If a service key does not exist, you could create one as per the documentation. Following information is required from the service key:

1.2.1. Client ID, Client Secret and URL

  • The Client ID and Client Secret would be used against the corresponding fields in the configuration.
  • The authorization endpoint in the configuration would be the URL from the service key followed by “/oauth/authorize” without spaces.

1.2.2. Endpoints – WORKFLOW REST URL

The host for our SM59 destination used to connect to the workflow service shall be this URL without the https://

The part of this URL after “.com” shall form the path prefix of our SM59 destination for a basic connection to the workflow service. To make this more meaningful, we will enhance this path prefix with the specific REST endpoint for the workflow definitions.

1.3. Using web browser to access the API Business Hub

To identify the specific path to the workflow-definitions endpoint, go to the API Business Hub (api.sap.com)

  • Search for the “Workflow service for cloud foundry”
  • Navigate to the API Reference section and pick a suitable path prefix (example: workflow-definitions)

The summary of required details and where to find them is presented by the following image

2. Establish trust between the S/4HANA System and the Business Technology Platform

2.1. As administrator of the S/4HANA system

Note: This step can be skipped if client credentials grant type is used. See section OAuth configuration with client credentials.

For the S/4HANA system to issue a SAML assertion and for the Business Technology Platform to validate this, we need to establish trust. To achieve this –

  • Login to the SAP S/4HANA system and start the oa2c_config transaction
  • Enable SAML0by clicking the “SAML 2.0 Enabled” button
  • Download SAML 2.0 metadata using the “Download SAML 2.0 Metadata” button

2.2. As security administrator of the subaccount on SAP Business Technology Platform

Note: This step can be skipped if client credentials grant type is used. See section OAuth configuration with client credentials.

To set the ABAP system as the SAML Assertion issuer for getting the credentials (Email) whenever a token is requested, upload the SAML 2.0 Metadata downloaded in step 3, to the subaccount on SAP Business Technology Platform.

  • As security administrator, go to the trust configuration section of the subaccount which contains the service instance you wish to use (in our example, workflow)
  • Click the “New Trust Configuration” button
  • Upload the SAML 2.0 metadata downloaded from the OA2C_CONFIG transaction.

After the upload, a new identity provider (IDP) would be listed with the name specified in the form

Note: We do not need this identity provider (IDP) for user logon. Therefore, make sure to disable the “Available for user logon” checkbox.

2.3. Add SSL/TLS digital signature certificate to the certificate list of the SSL Client Anonymous PSE (Personal Security Environment)

To establish a trusted relationship using the OAuth 2.0 client with SAP Business Technology Platform, you must use an SSL/TLS communication channel between your service provider (SAP BTP) and the SAP S/4HANA System. For this purpose, the service provider (SAP BTP) and the SAP S/4HANA System must trust each other. This is achieved by placing the SSL/TLS digital signature certificate of the service provider (SAP BTP) in the certificate list of the SSL Client Anonymous PSE (Personal Security Environment) of the SAP S/4HANA system.

2.3.1. Using web browser in the SAP Business Technology Platform,

  • To achieve this, open the subaccount and from the address bar of the browser, click the lock icon
  • Go to “Connection is secure”->” Certificate is valid”
  • Go to the details tab and export the certificate for the root CA of the certificate hierarchy

2.3.2. As administrator in the S/4HANA system

  • In the S/4HANA system, go to transaction STRUST and open the edit mode
  • Under the SSL Client (Anonymous), double click the subject. Scroll down to the certificate section and click the import certificate button
  • Import the certificate exported above and save

3. Configure connection to the BTP service via OAuth

To make sure that users access only the resources that are exposed to them, you can restrict access through scopes in an OAuth client profile. An OAuth 2.0 scope represents a list of resources that can be accessed by remote applications.

3.1. As developer on the S/4HANA system

  • In the SAP S/4HANA system, use transaction SE80.
  • Under your development package, create an OAUTH 2.0 Client Profile. This is used to define the scopes. For simplicity, I do not specify any scopes in our example

Note: Specifying the wildcard * under scopes is NOT the same as not specifying any scopes. Specifying such a wildcard could cause errors.

3.2. As Administrator on the S/4HANA system

  • Next, we need a client for our communication. The communication between OAuth 2.0 client and server is secured by an HTTPS connection. The end users can then use services and resources offered by the service provider
    • Use T-code OA2C_CONFIG to create an OAUTH 2.0 client.
    • When requested for OAUTH profile name, use the profile name created SE80. Use Client ID copied from the information gathering stage.
  • We now can choose the OAuth method we wish to use. In the current blog, we restrict the explanation to only the Client Credentials and SAML Bearer Assertion approaches.

3.2.1. OAuth Configuration with Client Credentials

Provide the following details based on the results of the information gathering section

  • Client Secret
  • Authorization Endpoint
  • Token Endpoint
  • Remaining Details:
    • Client Authentication: Form Fields
    • Resource Access Authentication: Header Field
    • Selected Grant Type: Client Credentials

3.2.2. OAuth Configuration with SAML Bearer Assertion

Provide the following details based on the results of the information gathering section

  • Client secret
  • Authorization Endpoint
  • Token Endpoint
  • SAML 2.0 audience
  • SAML 2.0 recipient:
  • Remaining Details:
    • Client Authentication: Form Fields/Basic
    • Resource Access Authentication: Header Field
    • Selected Grant Type: Current User Related
    • Grant Type (Current User Related): SAML 2.0 Bearer Assertion
    • User Email for SAML 2.0 Name ID: 000
  • Once configuration is done and saved, a test could be done using T-Code OA2C_GRANT. Select the profile and click on the button “Request OAUTH 2.0 Token”. If everything is configured correctly, the “Access Status” column will be green and “Receive Date”, “Receive Time” would be filled

Note: The OA2C_GRANT transaction, shown under administrator activities on SAP S/4HANA can only be used to request access tokens for user-related grant types, i.e. SAML Bearer Assertion grant type (see section OAuth configuration with SAML Bearer Assertion) and Authorization Code grant type (not covered in this blog). The OA2C_GRANT app cannot be used to request an access token for OAuth configurations where the Client Credentials grant type is selected

  • Since we are propagating the email ID for single sign-on, users in the S/4HANA system should have email id maintained. Use transaction SU01 to verify this

3.3. As Security Administrator on the Business Technology Platform

Assign Roles/Role Collections to S/4HANA On Premise specific users (by using the new IDP we set up).
This step is only needed if you chose the OAuth SAML Bearer Assertion in the previous step

3.4. As Administrator in the S/4HANA system, create SM59 destination with OAuth settings

  • On the S/4HANA System, go to transaction SM59 and create a destination of type G (HTTP connections to external server). We use Type G since we wish to connect to BTP which is external.
  • Under the technical settings tab, provide the following details:
    • Host: api.workflow-sap.cfapps.sap.hana.ondemand.com (Obtained in the information gathering section)
    • Path Prefix: /workflow-service/rest/v1/workflow-definitions (Here, and /v1/workflow-definitions is the additional path we use to get the workflow-definitions)
    • Port: 443 (Default HTTPS port)
  • Under the Logon and Security tab,
    • Use the OAuth Settings button to link the OAuth configuration we did earlier with the SM59 destination
    • Click the button and provide the OAuth profile name and OAuth configuration names as defined in corresponding steps
  • Scroll down to the security options and under “Status of Secure Protocol”, ensure the following:
    • SSL: Active
    • SSL Certificate: ANONYM SSL Client (Anonymous)
  • Perform a connection test to ensure everything is set up correctly. If all configuration is correct, you should get a status code 200

4. Use the destination in ABAP Code

The SM59 destination, now linked to the OAuth configuration can be used in ABAP code as demonstrated in the following runnable class (created as developer in the S/4HANA system)

class ZCL_OAUTH_BTP_WF definition

public

final

create public .

public section.

INTERFACES IF_OO_ADT_CLASSRUN.

protected section.

private section.

ENDCLASS.

CLASS ZCL_OAUTH_BTP_WF IMPLEMENTATION.

METHOD IF_OO_ADT_CLASSRUN~MAIN.

TRY.

* Create HTTP client using the SM59 Destination with log-on configured using OAuth

CALL METHOD cl_http_client=>create_by_destination

EXPORTING

destination = 'S4H_2021_BTP_WF' "Name of SM59 Destination

IMPORTING

client = DATA(http_client).

IF sy-subrc <> 0.

out->write( 'Could not create http client' ).

ENDIF.

* In productive code, handle potentially raised exceptions better. Not handled here for brevity

http_client->send( ).

http_client->receive( ).

http_client->response->get_status( IMPORTING

code = DATA(status_code)

reason = DATA(http_status_description) ).

out->write( 'HTTP Status: ' && status_code ).

* Read the parsed character data from the HTTP response

DATA(workflow_definition_data) = http_client->response->get_cdata( ).

out->write( workflow_definition_data ).

* Generic exception handling done for brevity

IF http_client->oauth_last_err_txt IS NOT INITIAL.

out->write( http_client->oauth_last_err_txt ).

ENDIF.

CATCH cx_root INTO DATA(exception).

out->write( exception->get_longtext( ) ).

ENDTRY.

ENDMETHOD.

ENDCLASS.

Executing this class, provides the details of workflow definitions in the subaccount