How to leverage sample codes to generate authentication strings from CA Certs?

[#1]

In Part 1 of this blog series, we presented “under the hood” details on how CA Certs are used to authenticate to Anaplan. Let’s recap what we learned inPart 1.

Anaplan Integration APIs requests require an authentication token (AnaplanAuthToken)in its headers. Anaplan authentication service API is used to generate this token.

Authentication API request requires following header and body to generate the token:

• Header: Public certificate (.pem) that’s base64 encoded
• Body: A JSON structure with two strings.
  • encoded_string:base64 encoded randomly generated string of at least 100 bytes.
  • Encoded_signed_string: “encoded_string”that’s signed by your private key and base64 encoded.
  • 例子:示例JSON请求主体的结构。

{

"encodedData" : "2wiKPoVqz0ZheVU8T+CqoR82WsVfDIb3bc1I/MIxXD9OQ76js+Qjlh8y5lfzb0lpx8jyZiM+lKMA8Ku5oKyOh0nJN2nk6tloTkL8TKJ6nUm9pVT1+dbCsJZhAi",

"encodedSignedData" : "hnbAWqqOob5RrAlqMyLbuUvkpK0Bfe9hm3MlZwI7Q2tbu4SRUMqeivIKvvjenzkDo+8mdS0jQUuCfjgVyZhg4Uj3rk3KENbyFj7dV7H3f3T2QDnxU+7T0aIuw17PwkRKx0Rg9IpwBkOMXxoSMTQuN30Dem5SIGDYpHCQ0Y6KVo1tmynp4+6XKha/sD3BMZtHlQ=="

}

How to generate strings for Header & Body

How do we generate these strings for header & body?

You could use sample Java code provided by Anaplan on Anapedia. There are, however, other simpler alternatives:

• certAuthGenerator.batis a windows-based application available via Anaplan Support (and downloadable from this blog). Using public certificate & private key stored in a Java Keystore (.jks), this application outputs required header & body information you will need to generate authentication token.
• vEncrypt_0_4.jaris a custom Java application provided with this community blog. This application is provided as a reference and is not supported by Anaplan. This java application performs following functions:
  • Generates a 128-bit AES Key
  • Generates a valid connection string with encoded certificate.
  • Using generated key, encrypts/decrypts any string value to be used in Anaplan Connect Scripts.
• Python Script:You may also use Python scripts to generate required header & body strings. Instructions to generate authentication strings using Python can be foundhereon Anaplan Community. Sample python script is also provided with this article for your reference. Similar tovEncrypt_0_4.jarjava application, this script is NOT supported by Anaplan Support. It is provided as a reference.

Pros & Cons

Table below summarizes advantages and disadvantages of each utility listed above.

	Pros	Cons
certAuthGenerator	Supported by Anaplan Generates strings required for authentication API header & body	Windows Only Extract public certificate (in pem format) & private key Requires Public Certificate & Private key in a Java Keystore (.jks)
vEncrypt_0_4.jar	Need only .pfx 做es not require any additional steps (ex: create Java Keystore) Generates strings required for authentication API header & body Platform independent (Windows, Linux, MacOs) Encrypts/Decrypts sensitive information (ex: passwords in Anaplan Connect scripts) using generated AES 128-bit key	No Anaplan Support Use “as-is”
Python Script	Flexible, Customizable, & reusable Community article outlining steps Sample python script Can make authentication via CA Certs simpler	示例Anaplan增刊python脚本不支持的ort Requires knowledge of Python Requires python and required packages

Generate authentication strings for Header & Body

In this section, we will present step-by-step instructions on how to use utilities listed above to generate authentication strings.

certAuthGenerator.bat

• Create a Java Keystore (.jks), Alias, and Password with Public Certificate (.pem) and Private Key. Detailed instructions on how to generate a Java Keystore are available on Anaplan Communityhere.
• 做wnload certAuthGenerator.zip file
• Unzip contents of certAuthGenerator.zip file to a folder of your choice on a Windows platform.
• Ensure both .bat & .jar are in the same directory.
• Edit certAuthGenerator.bat file and provide Java Keystore information for KeystorePath, KeystoreAlias, KeystorePass.

• Execute certAuthGenerator.bat. Result will be a bas64 encoded Public Certificate for Header, and base64 encoded strings for the Body of authentication service API request to generate Anaplan authentication token.

• Using information from the batch program, you will, now, be able to generate authentication token using authentication services API. Documentation on Anaplan Authentication Services API is found here. In the next part of this blog series, we will present “real-world” use cases on how many of Anaplan customers are leveraging Anaplan REST APIs with in other ETL/iPaaS (Ex: Talend) & analytics (Ex: Microsoft PowerBI) tools to build integrations.

Python Script

Using instructions provided in this communityarticle, you can build a script that not only generates authentication strings but also authentication token you will need for integration APIs. A sample python script (getAuthStringsCACert.py) is provided with this article for your reference. This script is NOT supported by Anaplan. It is intended to provide you an example of how Python scripting can be used in Anaplan integrations.

This article assumes you have met following requirements:

• Familiarity with Python
• Installed latest Python version. The script has been tested on Python 3.8.2
• Installed required Python libraries
  • Crypto, json, os, base64, requests

ExecutegetAuthStringsCACert.pyon your system. The script will output two strings: Header String and Body String (JSON) to be used in your authentication services API requests to generate authentication token.

Java Utility (vEncrypt_0_4.jar)

vEncrypt_0_4.jar is a custom Java utility that provides following functionality:

• Generates hexbinary AES 128-bit key
• Encrypts Anaplan or CA Certificate credentials using generated hexbinary AES 128-bit key.
• 使用生成的密钥解密凭证和过时的s values to Anaplan Connect scripts
• Generates authentication strings for header and body of an API request directly from a certificate (.pfx). It doesn’t require you to extract public certificate (.pem format) & Private key, nor does it require an additional step to create a Java Keystore (.jks).

We will first look at how to generate authentication strings for Authentication service request using a CA Certificate in .pfx format followed by a sample python script that generates an authentication token using this java utility.

Before we get started, let’s recall the disclaimer.This utility is provided “as is”. It is intended for illustration purposes only. There is no support provided for this utility.

Pre-requisites

• Familiarity with Anaplan Authentication Services APIs
• Install Java 8
• Install Python 3.8.2 or latest version
• CA Certificate issued to an Anaplan user account (e-mail). Certificate should be in pfx format.
• Public certificate has been registered with Anaplan using Tenant Administrator
• 做wnload & copy vEncrypt_0_4.jar (provided with this community article) to a directory.
• 做wnload & copy getAuthTokenCACertvEncrypt.py to a directory.
• Ensure both vEncrypt_0_4.jar & getAuthTokenCACertvEncrypt.py have read permissions.

vEncrypt_0_4.jar

Use following syntax on the command line to generate authentication strings from a CA Certificate (.pfx).

java -jar vEncrypt_0_4.jar SIGNEDDATA {path}/{certificate} {cert passphrase}

Output from the utility is a string that contains three fields, delimited by “*++*”:

• Encoded String, Encoded Signed String, & Public Certificate (.pem) base64 encoded.

Encoded String & Encoded Signed String can be used to build a JSON structure that’s passed in the body of Anaplan Authentication services API request.

Public Certificate string is passed in the header of API request. Details were presented in earlier sections of this article.

Any scripting language can be used to parse these fields from the result of this Java Utility. In the next section, we will present how a sample Python script can be used to execute the java utility, generate required authentication strings, and generate authentication token.

getAuthTokenCACertvEncrypt.py

This sample python script generates authentication token directly from a CA Certificate in pfx format. The script performs following tasks to generate Anaplan authentication token:

• Executes java utility, vEncrypt_0_4.jar, and generates a string with required authentication information.
• Parses output from Java utility to extract encoded_string, encoded_signed_string, and public certificate base64 encoded.
• Builds required Headers & Body for authentication service API POST request.
• Makes a POST request tohttps://auth.anaplan.com/token/authenticate.
• Parses JSON response to output Authentication token.

The python script takes 5 input arguments:

1. Path to vEncrypt_0_4.jar
2. Name of Java utility (vEncrypt_0_4.jar)
3. Path to .pfx file
4. CA Certificate (.pfx) name
5. Certificate pass phrase

Syntax:

python getAuthTokenCACertvEncrypt.py {path_to_jar} vEncrypt_0_4.jar {path_to_cert} {cert_name} {cert_password}

Authentication Token can, now, be used in any Anaplan integration APIs (Bulk API, Transactional API, CloudWorks API, ALM API, etc…).

Encrypting strings in Anaplan Connect Scripts

Anaplan Connect scripts can authenticate to Anaplan Platform via Basic authentication (username & password), CA certificates (Public Key, Private Key), and Java Keystore. With each of these authentication methods, passwords are exposed as ASCII text. Anaplan Connect, by default, doesn’t offer ways to encrypt or hide this information, posing potential security risk. In this section, we will present howvEncrypt_0_4.jarutility helps solve for this by providing encryption functionality and enhancing security for authentication credentials.

This utility provides following functionality:

• Generates hexbinary AES 128-bit Key
• Encrypts Anaplan or CA Certificate credentials using generated hexbinary AES 128-bit key.
• Decrypts credentials using the key and passes values to Anaplan Connect scripts.

This java utility requires following pre-requisites:

1. Anaplan Connect downloaded & installed in a directory (Windows or Linux).
2. vEncrypt_0_4.jar utility
3. Working Anaplan Connect script that successfully authenticates to Anaplan Platform.
4. Ability to create & save a text file on the system running Anaplan Connect.

Next, we will walk through steps on how to encrypt/decrypt sensitive password information in Anaplan Connect scripts using vEncrypt_0_4.jar utility. Below is a list of steps we will follow.

1. Setup Anaplan Connect Environment
   • Copy vEncrypt_0_4.jar to the same directory as Anaplan Connect script (.bat or .sh).
2. Generate AES 128-bit Key

java -jar vEncrypt_0_4.jar generate 128

3. Encrypt Credentials

Encrypt Anaplan credentials (username:password for Basic Authentication), Private Key pass phrase (CA Certificate authentication), or Java Keystore (keystore pass phrase) using generated key from step 2.

java -jar vEncrypt_0_4.jar encrypt {yourcredentials} {generatedkey}

4. Store Encrypted Value in a text file (ex: encryptedCredentials.txt). Optionally, change permissions on the file so only authorized user(s) have read permissions.

5. Modify Anaplan Connect Script
   • We will use Anaplan Connect script with Basic Authentication as an example. This approach can be used for any string that needs to be encrypted in your script.
   • Replace value for AnaplanUser with “$1” (Linux) or “%1” (Windows)

6. Execute Anaplan Connect Script

Execute Anaplan connect script using vEncrypt_0_4.jar, encryptedCredentials.txt, and generated key. Use following syntax.

Java -jar vEncrypt_0_4.jar {path/AC script} {path/encrypted_cred.txt} {generated key}

Summary:With this utility, you were able to successfully encrypt sensitive password information in your script and use encrypted information to run Anaplan Connect script. You were also able to add enhanced security by restricting file permissions on encrypted credentials so only authorized users or service accounts are able to read encrypted data.

Got feedback on this content? Let us know in the comments below.