Consuming DPI NextGen Services using Client Certificate Authentication

[shifa_tarannum]

This blog provides a step-by-step walk-through of using client-certificate authentication to connect to DPI Next Gen (Data Privacy Integration - NextGen) services via destination certificates. You’ll also find practical guidance for testing your setup ensuring secure communication between services via MTLS. Even if you're new to certificate authentication, or just looking for a quick reference, this guide offers an approach to getting it right.

Introduction

Client Certificate Authentication is a secure method to verify the identity of an application making a request to a service. Instead of relying on passwords or OAuth2 tokens, the calling client presents a certificate during the TLS handshake. The service then validates this certificate against trusted authorities before allowing access.

In the SAP BTP landscape, this authentication mechanism is used when applications communicate with either a platform service (such as Destination Service), or custom apps deployed on Cloud Foundry. By configuring a certificate as a service key, SAP BTP ensures that only verified clients can call endpoints.

This method offers stronger security for communication because certificates are harder to compromise, can be automatically rotated, and can be scoped strictly to the required service.

Accessing Data Privacy Integration (DPI Next Gen) Service

DPI Services provides unified data privacy capabilities for applications on SAP BTP. You can explore more about it in the help guide. It also provide API endpoints that you need to implement in your application.

To consume the services, create a service instance of data-privacy-integration-service with the data-privacy-internal plan. Depending on the use-case (for example, archiving, retention, etc.) a set of configurations parameters are expected during service instance creation, which are documented here.

Generating Client Certificates

The Destination Certificates UI on the BTP Cockpit provides a way to create and maintain X.509 Certificates, either self-signed or generated via external services.

1. Create a new certificate. Make sure to choose the file-extension as P12 extension, which allows retrieve both the certificate and the corresponding private key. Choose the validity based on your requirement. Password can be left empty.
   (Note: whatever you input in the "name" field will end up being the Common Name in the certificate, once generated.)Certificate Creation on BTP
   
   
2. Once submitted, the UI shows the certificate subject and the issuer details. They are needed during the creation of a service-key. 
   
   Destination Certificate Details

Creating a Service Key for DPI NextGen Service

Creating a service key without additional parameters typically indicates that the service uses the Client-Credentials flow, where authentication is handled through the client ID and client secret.

To consume the DPI NextGen service via client-certificates, we'll need to specify our intent via a few parameters when creating a service-key:

{
  "credentials": {
    "certSubject": ".....",
    "certIssuer": "....."
  }
}

The values for certSubject and certIssuer fields are strings, and can be obtained from the certificate details page as shown previously. For example:

Service Key Configuration Parameters

Click on Create to start the service-key creation. Once the service key is successfully created, you can fetch the callback URL. We will create a destination by providing this URL.

Creating a Destination to access DPI NextGen Services

Now, we create a destination to the DPI NextGen service.

1. Create a new destination via the BTP Cockpit. For authentication, choose the option ClientCertificateAuthentication from the drop-down. In the Key Store Location select the certificate that you created in the previous step. The URL can be obtained from the service-key itself.
   
   Creation of a new Destination
   
   
2. Click on Save to create the destination. Verify the authentication parameters and the URL.
   
   Destination Details

Once this is done, the connectivity setup is complete for any application to consume the DPI NextGen services. In the next few sections, we'll show how to test the connectivity via a REST Client, and also via a deployed application.

Getting Client Certificate and Key via Destination Service API

To test connectivity via a REST client, we'll need access to both the certificate and the private key. Currently, the "Export" button on the Destination Certificates UI provides only the public certificate. Private keys are only accessible via the Destination Service API.

All destination certificates and private keys can be obtained by sending a GET request to the following endpoint:

https://<domain>/destination-configuration/v1/subaccountCertificates

The response body will have the following format:

{
    "Name": "trial.p12",
    "Type": "CERTIFICATE",
    "Content": "<base64-encoded content>"
}

The certificate and private-key are packed together into a binary, and then encoded via base64, which is what the API response carries. In the next set of steps, we'll be decoding this base64-encoded content and extract the certificate and private-key as two separate files.

Copy the value for the "Content" attribute and save it in a file, for example Trial.txt. Since the content is base64-encoded, use the following command to decode it and save it in a proper format:

cat Trial.txt | base64 -d > Trial.p12​

For the subsequent operations, the openssl binary is needed. For macOS, you can install it via homebrew. 

Next, we'll use this command to display the certificate chain and the private key. This is to verify if the response was properly decoded or not.

openssl pkcs12 -in Trial.p12 -nodes​

There will be prompt to enter a password. It would be the same as the one chosen while creating the certificate. In case you didn't enter a password, just press the enter key to continue.

Next, we need to save certificate and key into two separate files.

To save the certificate to a file TrialCert.crt:

openssl pkcs12 -in Trial.p12 -nodes -out TrialCert.crt -nokeys ​

To save the private key as TrialKey.key 

openssl pkcs12 -in Trial.p12 -nodes -out TrialKey.key -nocerts

There may be some sections with “Bag Attributes”. We can manually correct both the certificate and key files by removing these sections.

Example: Use DRM Service via REST Client

In this section, we'll test by sending calls to the Data Retention Manager (DRM) API which is a part of the DPI NextGen service, by using client-certificate we obtained in the previous step. Any REST client can be used, Bruno is used in these examples.

In Bruno, create a new collection. On the collection settings page, choose the certificate and key that was created, For domain, specify the root URL for the DPI service.Add Certificate in Bruno
Now, within the collection, any request that is created to an endpoint which matches the domain selected above, Bruno will perform authentication via the chosen client-certificate:

Send Request to DRM Endpoint

 

Example: Use DRM Service via SAP Cloud SDK

For a backend application to consume any external service, SAP recommends using the SAP Cloud SDK for both Java and JavaScript applications. This blog post assumes you're using a CAP application. Follow these steps here to setup Cloud SDK integration: https://cap.cloud.sap/docs/java/cqn-services/remote-services#cloud-sdk-integration

Also, this blog post uses code-snippets written in Java, but Cloud SDK for JavaScript has equivalent methods and interfaces for everything used here.

Setup a Destination Instance

SAP Cloud SDK provides the DestinationService and DestinationOptions interfaces. This is an example to connect to a destination via name:

var service = new DestinationService();
DestinationOptions options;
Try<Destination> destination = service.tryGetDestination("destination-name", options);

By default, in case of a multi-tenant setup, the Cloud SDK will look-up the destination in a consumer subaccount first. Since, the “TRIAL_AUTH” destination is maintained in the provider subaccount, the destination lookup (a.k.a "retrieval") strategy needs to be changed.

Here, we explicitly specify the retrieval strategy ALWAYS_PROVIDER to make sure the destination is fetched directly from the provider subaccount:

DestinationService service = new DestinationService();

DestinationOptions options = DestinationOptions.builder()
      .augmentBuilder(DestinationServiceOptionsAugmenter
      .augmenter()     
      .retrievalStrategy(DestinationServiceRetrievalStrategy.ALWAYS_PROVIDER))
      .build();

Try<Destination> destinationTry = service.tryGetDestination(“TRIAL_AUTH”, options);
Destination destination = destinationTry.get();

Setup an HTTP Client using the resolved Destination

Once the destination has been resolved, the next step is to create an instance of HTTPClient. This instance already has the authentication credentials, headers, etc. defined as set in the destination, which it will be apply for every request:

// Convert the destination to an HTTP destination
 HttpDestination httpDestination = destination.asHttp();
 
 // Obtain an HTTP client instance
 HttpClient client = HttpClientAccessor.getHttpClient(destination);
 
 // Create a generic HTTP request (e.g., HttpPut / HttpPost / HttpGet / tec)
 HttpRequestBase request = new HttpPut(httpDestination.getUri().toString());
 // Example: Replace with new HttpPost(...) or new HttpGet(...)or others as needed
 
 // --- Set headers (example) ---
 request.setHeader("Content-Type", "application/json");
 request.setHeader("Accept", "application/json");
 // Add any additional headers here...
 
 // --- Set payload (only applies to entity-enclosing requests like PUT/POST/others) ---
 StringEntity requestBody = new StringEntity(payload, "UTF-8");
 if (request instanceof HttpEntityEnclosingRequestBase) {
     ((HttpEntityEnclosingRequestBase) request).setEntity(requestBody);
 }
 
 // Execute the HTTP request
 HttpResponse response = client.execute(request);

To verify this, we setup a dummy backend application with this code, along with an endpoint to trigger it. Again, we setup Bruno to send a request to this custom endpoint and validate the destination-based connectivity. This time, the client-certificates need not be added, since the destination service will provide those:

Send Request to DRM via Bruno

Conclusion

This post walked through configuring client-certificate (mTLS) authentication for DPI Next Gen: from creating destination certificates and service keys to wiring a destination for testing both using a REST client and the SAP Cloud SDK. The following is the summary of what we've covered:

• Generate a P12 certificate in the Destination Certificates UI.
• Create the DPI-NextGen service-instance and configure a service-key for client-certificate authentication.
• Create a destination using ClientCertificateAuthentication.
• Retrieve and decode the certificate-key pair via the Destination Service API endpoint.
• Test with a REST client to call DRM/DPI endpoints.
• Integrate and test from an application using the SAP Cloud SDK.