Set Up Inbound OAuth Client Credentials Grant Authentication for Senders Calling Integration Flows with SAP-Generated Certificate

In this tutorial, the application Postman (version v9.16.0) is used as the sender. This Postman version provides a simplified user experience that allows you to configure the 2 requests described above in a single tab.

There are two options to create a client certificate for the first request (addressed at the token server):
- Using any tool, for example, KeyStore Explorer
- Getting a client certificate and key pair generated by SAP (when creating the associated service key on SAP BTP)

For more information, see Creating Service Instance and Service Key for Inbound Authentication.

In the example scenario, the sender calls the Cloud Integration runtime to process an integration flow.

Define a service instance. With a service instance, you define how to access a certain SAP BTP service. In the context of SAP Cloud Integration, a service instance is the definition of an OAuth client.

1. In SAP BTP cockpit, select your subaccount.
2. Go to Instances and Subscriptions.
3. Click Create to create a new service instance and specify the following settings when creating the service instance.
   • Service: Process Integration Runtime
   • Plan: integration-flow
   • Runtime Environment: Cloud Foundry
   • Space: Select the space that hosts your Cloud Integration application (for example, the dev space).
   • Instance Name: Specify any name for the instance.
   

4. Select Next.

5. On the screen “Parameters”, leave the settings as they are. With Roles “ESBMessaging.send” and Grant-types as “Client Credentials”.
   

   The default role ESBMessaging.send provides permission for the sender system to process integration flows.

   Make sure that under Grant-types the Client Credentials entry is displayed.

   Tip: You can also use self-defined roles to authenticate sender systems to call integration flows. See: Managing User Roles.

6. Choose Create.

For further information on creating service instances and service keys, see: Creating Service Instance and Service Key for Inbound Authentication.

You now define a service to go along to your service instance.

1. On the Instances and Subscriptions screen for your subaccount, select the newly created service instance and choose ….

2. Click on Create Service Key.

   

3. Specify a service key Name. To use an SAP-generated certificate for the step to retrieve the access token, select Certificate as Key Type. You can keep the default settings for Validity and Key Size.

4. Click Create.

5. Next, to display the details of the service key, choose … > View:

   

Each service key with an SAP generated client certificate contains certain properties. You need the following parts for the configuration of your sender (Postman):

• clientid: The user associated with the certificate. You need clientid when configuring the call from Postman.

• URL: The URL of the resource you want to call.

• certificate: The client certificate including the certificate chain. Note that the content contains multiple certificates in sequence (the beginning and end of each certificate identified with the strings BEGIN CERTIFICATE and END CERTIFICATE).

• key: The private key associated with the certificate. The certificate is generated (together with the private key) by SAP. You need the private key to configure the Postman client later.

• token URL: The URL of the component (referred to as token server) that issues the access token.

Example: This is how the JSON representation of the service key looks like when you open it in SAP BTP cockpit:

Upload the public certificate (including chain, content of property certificate from service key) and the private key (content of property key from service key) to Postman.

1. Copy the value of the certificate property into a text file (for example, Notepad). Make sure that for the certificate you include the whole certificate chain, that means, copy the complete content starting with -----BEGIN CERTIFICATE-----\n... and ending in -----END CERTIFICATE-----\n.

2. Make sure you have the content transformed into the right format: Replace all \n in the SAP-generated certificate with line breaks.

   You can use Word to format the content by using the Find and Replace dialog with the following values (once done, copy the content into the text file):

   

   The figure shows the Find and Replace dialog in Word with the following entries:

   • In field Find what enter \n.

   • In field Replace with enter ^p.

   The correctly formatted content looks like this (beginning of the certificate content):

   

3. Save the text file as file with the extension .cer, for example, certificate.cer.

4. Repeat the same steps for the key content. Start copying from -----BEGIN RSA PRIVATE KEY-----\n until -----END RSA PRIVATE KEY-----\n and store this as file with extension .key, for example key.key.

On your desktop, configure Postman as sender.

1. To specify the certificates and keys to be used to call the token server (first request), go to the Postman Settings.

2. Select the Certificates tab and choose Add certificates.

   

3. Specify the following parameters:

   • Host: Add the URL of the tokenurl property (without the https:// at the beginning and the /oauth/token at the end).
   • CRT file: Upload the .cer file.
   • KEY file: Upload the .key file.

Design a simple integration flow that does nothing else apart from generating a timestamp and sending the timestamp back to the sender.

If you have configured everything correctly, you receive a response in Postman that contains the actual time in Coordinated Universal Time (UTC) time zone.

1. Open SAP Integration Suite.

   You can open SAP Integration Suite from the Instances and Subscriptions page of your subaccount. Your applications are listed on the page. Next to the Integration Suite application, select the … icon and then choose Go to Application.

2. Go to Design > Integrations.

   If this is the first time you are using your account, you need to create an integration package. If there’s already an integration package, you can open that integration package and skip the steps 3 to 5.

3. To create an integration package, navigate to the Integrations tab on the left side and select Integrations.

4. Select Create.
5. Enter the name and description of the integration package (you can choose any name you want) and Save.
   

6. In your Integration package, choose the Artifacts tab.

7. Choose Add > Integration Flow. You are now adding an integration flow to your integration package.
   

8. Specify a name for the integration flow and choose OK. You can use any name. Make sure that the Product Profile is set to Cloud Integration.

   

9. Select the newly created integration flow by clicking.

   The integration flow model is opened.

10. Select Edit.

    You will notice that on top of the model, the integration flow component palette is activated that allows you to add shapes to the model.

    

11. Click the Receiver shape and remove it by selecting the recycle bin icon.

    You don’t need a receiver component in this integration flow that is why you should delete it.

    

12. Select the Sender shape so that the icons appear next to it - instead can we add the graphic here and remove the bit from ”like” to “before” as shown for the Receiver shape before. Delete the sender shape.

13. Again, select the Sender shape so that icons appear next to it. Select the arrow icon (as shown in the figure above) and drag and drop it to the integration flow Start shape.
    

    A screen where you can select an adapter type opens. Select HTTPS.

    In this scenario, the sender system (Postman) calls the integration flow through a basic HTTPS request.

    

    As long as the connection line is selected, you can access the properties sheet of the HTTPS adapter.

14. Within the configurations for the HTTPS adapter, choose the Connection tab.

15. For Address enter /GetTimestamp. Keep the other settings (for the parameters Authorization, User Roles, and CSRF Protected) as they are. The role ESBMessaging.send is assigned to the service key.
    

16. In the palette on top of the model, select the Message Transformers icon and choose Content Modifier.

    

    Place the cursor on the connection line between the Start and the End shapes to add the Content Modifier element to the integration flow.

    In Content Modifier properties sheet below the model, choose the Message Body tab, and in the Body field enter the following expression:

    Current time (UTC):

    ${date:now:yyyy-MM-dd HH:mm:ss}

    

    The so-configured Content Modifier element creates a message body with the actual timestamp.

    The expression ${date:now:yyyy-MM-dd HH:mm:ss} is an Apache Camel Simple language expression. Apache Camel is the open-source component behind Cloud Integration.

    See: Using Camel Simple Expression Language.

    That’s it, our integration is finished. When everything works well, the integration flow generates the actual timestamp and sends it back to the sender as a response.

Perform the following steps to deploy the integration scenario.

1. Save the integration flow.
2. Choose Deploy and confirm on the following screen.
3. Choose OK.
4. Go to Monitor > Integrations.
   

5. Select the left tile under Manage Integration Content.

   Your deployed integration flow is displayed. You can check if deployment has been performed successfully (which is the expected behavior).

   If a deployment error is shown, go back to Design > Integrations and check if the integration flow model can be saved without any errors.

6. Select the newly deployed integration flow.

7. In tab Endpoints, you find the endpoint address.
   

8. Copy the endpoint address to the clipboard. You need it to configure the Postman client.

As described above, in general, you need to configure and run two separate requests for the sender: one request addressed at the token server to get the access token, and another request addressed at the Cloud Integration runtime to call the integration flow. Using Postman, you can specify the settings for the first request as part of the second request in one screen. For more information, see OAuth with Client Credentials Grant for API Clients.

1. Open Postman.

2. Create a new GET request.
   As URL, enter the endpoint address of the deployed integration flow from the previous step.

3. Go to Authorization and specify the following parameters:

   • Type: OAuth 2.0
   • Header Prefix: Bearer.
   • Add authorization data to: Request headers
   • Token Name: Enter any name.
   • Grant Type: Client Credentials
   • Access Token URL: Enter the value of the tokenurl property from the service key (ending with /oauth/token). Note that this is the address of the token server called by the first requests.
   • Client ID: Enter the value of the clientid property from the service key.
   • Client Authentication: Send client credentials in body.
   With these Authorization settings, you’ve configured the first request addressed at the token server explained above.

4. Click Get New Access Token. The access token is fetched from the token server and displayed on the next screen. In other words, the first request is performed.

5. To use the retrieved access token for the second request (to call the API resource), click Proceed. The request is shown with the access token.
   

6. Click Send. The Cloud Integration runtime is called, and the integration flow is processed. The response is sent back to Postman. The response contains the actual timestamp (in UTC time zone).

So, the next time your watch doesn’t work, you can use this scenario to get the actual time.