Why CA Certs?
The purpose of this blog series is to give a deeper look on the use of Certificate Authority (CA) Certificates, especially on how this method of authentication works and how to use them for your different integrations.
A Quick Recap On Anaplan APIs Authentication
We recommend our readers to have some basic knowledge on Anaplan APIs.
In order to be able to trigger Anaplan actions remotely, one will need to get authenticated to the API server. If the authentication process is successful, the user will be granted a token that can be used for a limited period of time to activate Anaplan actions. The biggest challenge is to be able to get that token from the certificate you have.
Why would you use CA Certs instead of the well-known "basic authentication", involving the user email and password?
There are 2 main drawbacks of using basic authentication.
1. Critical information easily accessible
When using basic authentication, one will have to use username and password in the development of the integration process. Very often, this information is in clear text for any person who will have access to the scripts.
2. Regular update of credentials
Anaplan's password policy requires that any credentials must be updated at least every 3 months. The team in charge of integration will then be required to amend the scripts frequently, which increases the maintenance workload.
By using CA certs, we want to address those 2 concerns that are frequently raised by teams in charge of integration.
How does CA Cert based authentication work under the hood?
Sometimes, a schema is a great tool for understanding. So here is one:
Anaplan's cert-based method follows PKI basic principles, especially the rules of asymmetric cryptography.
Out of CA certificate, one will extract a private key and the public certificate. To have a thorough description of the steps needed to achieve this extraction, please use this link with a very instructive and interactive guide.
The private key will be used to "sign" a random string, generated externally for that purpose. Anaplan API server will receive this random string and its signed version. Via a specific calculation, it will validate if those two strings are related to each other using a private key's signature linked to the public certificate. Once the check is validated, the authentication process can be sure that the person who has sent the information is in possession of a valid private key.
So why is that method more secure than using Basic Authentication?
Based on what has been described above, we can state that:
- As you could see in the previous part, certificate information decoding requires a minimum of technicality to be handled correctly.
- No private or confidential information is sent on the web.
- There is also another advantage, quite consequential: The integration based on CA Certs will remain valid until the end of the certificate validity. Hence, there is no need to have a regular maintenance of integration scripts.
Anaplan also adds another level of security: to authorize API actions triggering via certificates, public certificate needs to be registered in the tenant admin.
In the case that we want to deactivate a certificate, you can simply do it via this screen. This will be without any consequence on the actual user linked to the certificate.
What about the private information?
One concern can be made on the use of the private key. Indeed, that piece of information is critical and private. Then, it cannot be handled lightly and should not be easily accessed.
Nevertheless, when analyzing the diagram flow, we can see that no private information is passed through the web. Only the 2 strings and the public certificate are sent through the web.
In your integration, nothing prevents you from reusing this pair of strings and store the private key in a secure location. By doing so, you will be compliant with the necessity to secure sensitive information.
Now, let's compare 2 situations, both involving a person with bad intents.
- Situation 1: Credentials have been retrieved
In this situation, an authorized person, in possession of Anaplan credentials, can log in into Anaplan and have access to sensitive information stored in Anaplan Platform.
- Situation 2: Cert-based information (2 strings + public cert) have been retrieved
In this case, an authorized person can trigger APIs; However, the unauthorized person will have no access to other parts of Anaplan interface and functionality. The access is more limited than with the actual credentials.
Now, you'd also want to ensure that those strings aren't also too easily readable. Please visit to learn how to create the strings securely.
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 this helpful article and see the Authentication Service API documentation.
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).
https://us.v-cdn.net/6037036/uploads/LDTJOQ62N2NS/image.png
https://us.v-cdn.net/6037036/uploads/GBB3JLNBSJW6/rsa-signer.zip
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.
https://community.anaplan.com/discussion/156606/using-the-anaplan-certificate-with-the-anaplan-rest-api-a-comprehensive-guide
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, @traineradam - Operational Excellence Group (OEG)
