Set Up Inbound OAuth Client Credentials Grant Authentication for API Clients with SAP-Generated Certificate

In this tutorial, the application Postman (version v9.16.0) is used as API client. 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)

In the example scenario, the API client calls the Cloud Integration OData API to access message processing logs. To get more information on this API resource and the supported operations, see SAP API Business Hub.

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. Create a new service instance and specify the following settings when creating the service instance. When you are done, choose Next.
   • Service: Process Integration Runtime
   • Plan: api
   • Runtime Environment: Cloud Foundry
   • Space: Select the space that hosts your Cloud Integration application (for example, this is the dev space).
   • Instance Name: Specify any name for the instance.
   

4. In the parameters section, select Form and add the following information:

   • Role: Select MonitoringDataRead and keep the other default settings as is. You need this role to authorize the API client to access monitoring data through the OData API (see Message Processing Logs). For a complete list of all operations and roles to access the available Cloud Integration resources, see Tasks and Permissions.
   • Grant-Type: Select Client Credentials.
   

5. 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. Select the newly created service instance.

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. Next, to display the details of the service key, select View:

   

   A service key with an SAP-generated client certificate contains the following parts which you need for the configuration of your API client (Postman) in a later step. Each service key contains certain properties. You need the following parts for the configuration of your API client (Postman):

   • clientid: The user associated with the certificate. You need clientid when configuring the call from Postman.
   • URL: The URL of the resource you like 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 also the private key to configure the Postman client later-on.
   • 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: Make sure to replace all \n in the SAP-generated certificate by line breaks.

   You can use Word to do the formatting the content by specifying the Find and Replace dialog in the following way (after doing that, copy the content into the text file):

   

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

   

3. Save the text file as file with 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.

You now need to configure Postman as API client.

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.

As described above, in general, you need to configure and run two separate requests for the API client: one request addressed at the token server to get the access token, and another request addressed at the Cloud Integration API to access the API resource. 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. Create a new GET request with the following URL (to get the message processing logs): https://<Cloud Integration host>/api/v1/MessageProcessingLogs

   The Cloud Integration host is the same address as when you have opened the Cloud Integration Web UI without the /itspaces. Note that this is the address of the API resource targeted with the second request where the API client accesses the Cloud Integration API resource.

2. 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.

3. 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 executed.

4. 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.

   

5. Click Send. The API resource is called, and the response sent back to Postman. The response contains the message processing logs of the tenant as an XML document.