Integrating Securely: Using the Anaplan REST API with Certificate-Based Authentication

AnaplanOEG
edited December 2023 in Best Practices

In the ever-evolving landscape of technology, secure communication between platforms is paramount. The Anaplan REST API offers a robust way to connect and interact with the Anaplan platform, and one of the most secure methods of authentication is through certificate-based authentication. In this article, we'll delve into the process of using the Anaplan REST API with certificate-based authentication, exploring the concepts and techniques involved.

1. Understanding Certificate-Based Authentication

Certificate-based authentication involves the use of a digital certificate and private key to establish trust between parties. In the context of Anaplan's REST API, this method ensures a secure connection while exchanging data. Learn more about how Authentication with CA Certs work as well as view the Authentication Service API documentation. If you need a certificate, then please check out the CA Certificate Quick Start Guide using Sectigo.

2. PEM Format: The Key to Success

Before we delve into the authentication process, it's essential to ensure that your public certificate and private key are in the PEM (Privacy Enhanced Mail) format. This widely used format ensures compatibility and security during data exchange.

3. Authentication API Request Structure

To generate the authentication token, your API request should have the appropriate header and body components:

Header: Include your public certificate (.pem), encoded in base64.
Body: Comprises a JSON structure containing two strings.

  • encoded_string: A randomly generated string of at least 100 bytes, encoded in base64.
  • Encoded_signed_string: This string is the "encoded_string" signed by your private key and then base64 encoded.

Here's an example of the JSON structure for the request body:

{
    "encodedData": "2wiKPoVqz0ZheVU8T+CqoR82WsVfDIb3bc...",
    "encodedSignedData": "hnbAWqqOob5RrAlqMyLbuUvkpK0Bfe9hm3Ml..."
}

4. The Role of Base64

Base64 encoding is crucial in this process, as it converts binary data into a printable text format. This transformation enables the secure transport of data over protocols or mediums that might not handle binary data formats.

5. Ensuring Secure Communication

The combination of base64-encoded data and the certificate-based authentication method guarantees secure communication with the Anaplan platform. This is especially important when dealing with sensitive information.

6. Approach 1: Simple Browser-Based Solution

For an effortless way to generate the required strings, you can use our downloadable RSA Signer in a handy downloadable ZIP file. Once the files have been downloaded and unzipped, open the index.html file. You are then presented with an interface that allows you to paste your public certificate and private key. It then generates the necessary encoded strings, which you can directly use in your API request (i.e. Postman).

Note: The RSA Signer currently does not support a passphrase on the Private Key.

7. Approach 2: Python Implementation

If you prefer a programmatic approach, here's a link to a comprehensive guide to using the Anaplan Certificate with Python to generate the required strings for your Anaplan API request. This solution is compatible with Python 3.11.1 and later versions.

8. Incorporating Certificates with Anaplan: A Productive Endeavor

As organizations strive for tighter security and efficient integration, certificate-based authentication emerges as a dependable solution. By implementing the methods discussed in this article, you'll be better equipped to seamlessly and securely connect your systems with the Anaplan platform.

Incorporating certificates into your Anaplan integration can appear complex, but armed with the knowledge of these two approaches, you're well on your way to a more secure and streamlined integration process. Stay ahead in the world of secure communication and data exchange with Anaplan's REST API and certificate-based authentication.

Authors: Quin Eddy, @QuinE & Adam Trainer, @AdamT - Operational Excellence Group (OEG)

Comments

  • Could you please help me with understanding how should I obtain the PEM file?
    As I understand public key and private keys are stored in .pem file and I can see that in Py code you provide the path to it.

    What is the best approach to obtaining this authentication certificate?

  • @kpasko You will take the certificate files that you receive from the vendor of your choice and need to convert them to PEM format. You can follow steps on converting to PEM format through the Interactive CA Certificate Guide pasted below. This will allow you to "choose your adventure" based on the certificate format that you are starting with. Feel free to reach out if you have any troubles!

    https://anaplanenablement.s3.amazonaws.com/Community/Interactive+CA+Cert+Guide/story.html

  • Thank you @kpasko - that is correct.