Introduction

The new Anaplan APIs and integration connectors leverage Certificate Authority (CA) issued certificates. These certificates can be obtained through your company's intermediary CA (typically issued by IT or Security group) or by purchasing it from a trusted Certificate Authority. Anaplan clients leveraging REST API v2.0 use both basic authentication and CA certificate-based authentication. Examples of these clients include Anaplan Connect 1.4.x, Informatica Anaplan Connector, and Mulesoft 2.0.1.

If you are migrating your Anaplan Connector scripts from v1.3.x to v1.4.x, your available options for authentication will be basic authentication or CA certificate-based authentication.

This article outlines steps to perform in preparation for CA certificate authentication.

Steps to Prepare for CA Certificate Authentication

  1. Obtain a certificate from a CA authority
  2. Convert CA certificate to either a p12 or pfx file
    • Import CA certificate into Internet Explorer/Mozilla Firefox to convert to a p12/pfx file
    • Export CA certificate from Internet Explorer/Mozilla Firefox to convert to a p12/pfx file
  3. Optional: Install OpenSSL tool
  4. Convert the p12/pfx file into a Java Keystore
  5. Manage CA certificates in Anaplan Tenant Administrator
  6. Validate CA certificate authentication via Anaplan Connect 1.4 script.

Obtain a Certificate From a CA Authority

You can obtain a certificate from CA authority by submitting a request or submit a request with a certificate signing request (CSR) containing your private key. 

Contact your IT or Security Operations organization to determine if your company already has an existing relationship with a CA or intermediary CA.

  • If your organization has an existing relationship with a CA or Intermediate CA you can request a client certificate be issued for your integration user.
  • If your organization does not have an existing CA relationship, you should contact a valid CA to procure a client certificate.

The type of certificate needed is a TLS Web Client Authentication or an E-mail protection certificate.  The OID can help your IT/Security request the correct type of certificate. The OIDs for this theses type of certificate are:

  • TLS Web Client Authentication (1.3.6.1.5.5.7.3.2)
  • E-mail protection (1.3.6.1.5.5.7.3.4)

Convert CA Certificate to Either a p12 or pfx File

Import CA certificate into IE/Firefox to convert to a p12/pfx file.

This section presents steps to import CA certificate into Internet Explorer and Mozilla Firefox. CA certificate will be exported in the next section to either a p12 or pfx format.

CA certificates may have .crt or .cer as file extensions.

Internet Explorer

  1. Within Internet Explorer, click on the Settings icon and select Internet option.1.jpeg

  2. Navigate to the Content tab and then click on Certificates.2.jpeg

  3. Click Import to launch the Certificate Import Wizard.3.jpeg

    4.jpeg

  4. Click Browse to search & select the CA Certificate file. This file may have a file extension of .crt or .cer.5.jpeg

  5. If a password was used when requesting the Certificate, enter it in this screen. Ensure that the “Mark this key as exportable” option is selected and click Next.6.jpeg

  6. Select the certificate store in which to import the certificate and click Next.7.jpeg

  7.  Review the setting and click Finish.8.jpeg

  8.  The certificate should appear in the certificate store selected.9.jpeg

Mozilla Firefox

  1. Within Firefox, select Options from the settings menu.10.jpeg

  2. In the Options window, click Privacy & Security from the navigation pane on the left. Scroll to the very bottom and click on the View Certificates… button.11.jpeg

  3. In the Certificate Manager, click the Import… button and select the certificate to convert and click Open.12.jpeg

  4. If a password was provided when the certificate was requested, enter that password and click OK.13.jpeg
  5. The certificate should now show up in the Certificate Manager.14.jpeg

Export CA Certificate From IE/Firefox to Convert to a p12/pfx File

This section presents steps to export CA certificate from Internet Explorer (pfx) and Mozilla Firefox (p12).

Internet Explorer (pfx)

  1. Select the certificate imported above and click the Export… button to initiate the Certificate Export Wizard.15.jpeg

    16.jpeg  

  2. Select the option “Yes, export the private key” and click Next.17.jpeg

  3. Select the option for Personal Informatica Exchange – PCKS #12 (.PFX) and click Next.18.jpeg

  4. Create a password, enter it and confirm it in the following screen.  This password will be used later on in the process. Click Next to continue.19.jpeg

  5. Select a location to export the file and click Save.20.jpeg

  6. Verify the file location and click Next.21.jpeg

Review the export settings, ensure that the Export Keys settings says “Yes”, if not start the export over. If all looks good, click Next. A message will appear when the export is successful.22.jpeg

23.jpeg 

 Mozilla Firefox (p12)

  1. To export the certificate from Firefox, click the Backup… button in the Certificate Manager.  Select a location and a name for the file.  Ensure that the Save as type: is “PKCS12 Files (*.p12)”. Click the Save button to continue.24.jpeg

  2. Enter a password to be used later when exporting the public and private keys. Click the OK button to finish.25.jpeg

Install OpenSSL Tool (Optional)

If you haven't done so already, install the OpenSSL tool for your operating system.  List of third party binary distributions may be found on www.openssl.org or here. Examples in this article are shown for Windows platform.

Export the Keys From the p12/pfx File

Execute the following to export the public and private keys exported above. In the commands listed below, the values that are customer-specific are in Bold Italics. There is a screen shot at the end of this section that shows all of the commands run in sequence and it shows how the passwords relate between the steps.

Examples in this article assume the location of the certificate as the working directory. If you are executing these commands from a different directory (ex: ...\openssl\bin), then ensure you provide absolute directory path to all the files.

Export the Public Key

Public key will be exported from the certificate (p12/pfx) using OpenSSL tool. The result is a .pem (public_key.pem) file that will be imported into Anaplan using Anaplan's Tenant Administrator client.

NOTE: The command below will prompt for a password. This password was created in steps above during export.

openssl pkcs12 -clcerts -nokeys -in <path to p12/pfx file> -out <path to public key file>

Edit the Public Key File

Remove everything before ---Begin Certificate --- (section highlighted in yellow). Ensure that the emailAddress value is populated with the user that will run the integrations.

26.jpeg

Export the Private Key

The private key can be exported in two methods, one that will encrypt the private key and one that will leave the key non-encrypted. 

NonEncrypted:

This command will prompt for a password. This password is the password created in the export above. It will not prompt for a password for the output file.

openssl pkcs12 -nocerts -in <path to p12/pfx file> -out <path to unencrypted private key file> -nodes

direct_use_unencrypted_screenshot.png

Encrypted:

This command will prompt for a password. This password is the password created in the export above. It will the prompt for a new password for the Private Key. It will also ask to confirm that password. 

openssl pkcs12 -nocerts -in <path to p12/pfx file> -out <path to encrypted private key file>

When using the private key directly in an Anaplan Connect script, the file must be converted to PKCS8 format. The command below will convert that file.

openssl pkcs8 -inform PEM -in <path to encrypted private key file> -outform PEM -out <path to pkcs8 formatted private key file> -passout pass:<pkcs8 file password>

direct_use_encrypted_screenshot.png

Creating a Java Keystore 

Create P12 Bundle

This command will prompt for the private key password from the step above. It will the prompt for a new password for the Bundle. It will also ask to confirm that password.

openssl pkcs12 -export -in <path to public key file> -inkey <path to encrypted private key file> -out <path to bundle file> -name <alias name for the entry>

In the command above, 

  • public_key.pem is the file that was created in the step "Export the Public Key".  This is the file that will be registered with Anaplan using Anaplan Tenant Administrator. 
  • private_key.pem is the file that was created in the step "Export the Private Key".
  • bundle.p12  is the output file from this command, which will be used in the next step to create Java Keystore.
  • Scott is the keystore alias.

Add to Java Keystore (jks)

Using keytool (typically found in <Java8>/bin), create a .jks file. This file will be referenced in Anaplan Connect 1.4 scripts for authentication. The Command below will prompt for a new password for the entry into the keystore. It will also ask to confirm that password.  It will, then, prompt for the Bundle password from the step above.

keytool -importkeystore -destkeystore <path to java keystore file> -srckeystore <path to bundle file> -srcstoretype PKCS12

In the command above:

  • my_keystore.jks is the keystore file that will be referenced in your Anaplan Connect 1.4.x scripts.
  • bundle.p12 is the P12 bundle that was created in the last step.java_keystore_screenshots.png

Manage CA Certificates in Anaplan Tenant Administrator

In this step, you will add public_key.pem file to list of certificates in Anaplan Tenant Administrator. This file was created & edited in the first two steps of the last section.

Log on to Anaplan Tenant Administrator. Navigate to Administration --> Security --> Certificates --> Add Certificate.

28.jpeg

Validate CA Certificate Authentication via Anaplan Connect 1.4.x script.

Since you will be migrating to CA Certificate-based authentication, you will need to upgrade your Anaplan Connect and associated scripts from v1.3.x to v1.4.x. Community article, Migrating from Anaplan Connect 1.3.x.x to Anaplan Connect 1.4.x will guide you through necessary steps. Follow the steps outlined in the article to edit & execute your Anaplan Connect 1.4 script. Examples provided (Windows & Linux) at the end of the article will validate authentication to Anaplan using CA Certificates.