With the Anaplan® (Standard) connector, you can use commands to perform standard Anaplan functions as part of a chain. To use a chain to automate security settings through robotic process automation (RPA), such as to upload a new data source, use the Anaplan (RPA) connector instead.
For example, with this connector, you can:
- Download and upload files in Anaplan
- Manage imports, exports, and other Anaplan actions
- Manage files, views, and processes in Anaplan
Note: This connector is built by Workiva and connects to a third-party system. While our Support team can help configure this connector within your workspace, we are unable to troubleshoot or otherwise assist with any issues that originate outside of the Workiva platform.
Requirements
To perform its commands, the Anaplan (Standard) connector uses the Anaplan REST API. To secure the connection to Anaplan, the connector can authenticate via:
- Basic username and password authentication
- A Certificate Authority (CA)-signed certificate authenticated with a private key or Java® KeyStore (JKS)
- 0Auth 2.0 using an Anaplan OAuth2 Authorization Code
Note: With certificate authentication, chains can interact with Anaplan without interruption from basic authentication errors, such as password resets or mandatory password updates.
To set up the connection, you'll need:
- The base URI for the Anaplan API, such as the default https://api.anaplan.com
- A designated integration user or service account created in Anaplan tenant to connect to
- The authentication credentials of the integration user or service account:
- For basic authentication, the username and password
- For a certificate with a private key:
- The CA-signed certificate as a PEM file
- The private key and—If encrypted—its password
- For a certificate with a Java KeyStore, the JKS file that contains the users' certificates, and its password and alias
- For OAuth 2.0, the Client ID and Secret. Additionally, the "Refresh Token Behavior" setting in Anaplan must be set to non-rotatable.
- If using a proxy server, its URI, username, and password
For certificate authentication, you can manually create the files required or automatically generate them for macOS or Linux via a shell script.
Note: To avoid tying the connector to individual users, we recommend its own designated service account in Anaplan.
Setting up an 0Auth2 token within Anaplan
To authenticate using 0Auth 2.0, you must create an OAuth 2.0 client within Anaplan by following the instructions at this link:
When setting up your token, the "Refresh Token Behavior" setting in Anaplan must be set to non-rotatable. Only non-rotatable refresh tokens are supported — a rotatable token will expire and cause the connection to fail. Learn more about using the Anaplan OAuth2 Service.
Automatically create files for certificate authentication on macOS or Linux
To enable certificate authentication for macOS® or Linux, you can run the create-cert.sh
shell script to automatically create the files the connection requires to authenticate via a CA-signed certificate:
-
ca_certificate.pem
, a public certificate to upload and register with Anaplan -
unencrypted_private_key.pem
orencrypted_private_key_pkcs8.pem
, a private key to also use with Anaplan Connect® - An optional
keystore.jks
, the Java KeyStore that houses the certificate's private key
To generate these files, update these parameters, and then run the shell script in a Terminal window:
CertP12Format
CertP12Password
PemPassPhrase
KeyStoreAlias
KeyStorePassword
-
CreateUnencryptedPrivateKey
(true or false) -
EncryptedPrivateKey
(true or false) -
CreateJks
(true or false)
create-cert.sh
#!/bin/sh # For MAC OS : This script will create a CA Certificate that is compatible with Anaplan Connect # Update the variables below with your particular settings. # Provide the path and file name of the exported certificate in .p12 format CertP12Format="PATH TO CERTIFICATE IN P12 FORMAT" CertP12Password="PASSWORD FOR CERTIFICATE IN P12 FORMAT" CertPEMFormat="ca_certificate.pem" # Set the line number where the public key starts StripLinesUpUntil=82 # Provide the path and file name of the unencrypted export key. # This file is required for creating a Java Key Store CreateUnencryptedPrivateKey="true" UnencryptedPrivateKey="unencrypted_private_key.pem" # Provide the path and file name of the encrypted export key. # This is only required if opting to not use a Java Key Store CreateEncryptedPrivateKey="true" EncryptedPrivateKey="encrypted_private_key_pkcs8.pem" PemPassPhrase="pem-password" # Provide the path and file name of the Java Key Store CreateJks="true" JavaKeyStore="keystore.jks" KeyStoreAlias="PROVIDE ALIAS" KeyStorePassword="jks-password" #____________________________ Do not edit below this line ______________________________ echo "************* Creating CA Certificate (PEM Format) *************" echo "You will be prompted to enter a few passwords. Be sure to enter the Import Certificate password: \"${CertP12Password}\"" read -p "Press any key to continue... " -n1 -s openssl pkcs12 -in $CertP12Format -nokeys -out ./temp_cert sed -e "1,${StripLinesUpUntil}d" < ./temp_cert > ${CertPEMFormat} ### https://www.computing.net/answers/programming/delete-all-lines-afterbefore-line-number-with-dos-batch/29963.html cat ${CertPEMFormat} rm ./temp_cert echo "CA Certificate (PEM Format) created: $CertPEMFormat" if [ $CreateUnencryptedPrivateKey == "true" ] then echo "************ Creating Unencrypted Private Key ******************" echo "You will be prompted to enter the Import Certificate password. Be sure to enter the password: \"${CertP12Password}\"" openssl pkcs12 -in $CertP12Format -nocerts -out $UnencryptedPrivateKey -nodes echo "Unencrypted Private Key created: $UnencryptedPrivateKey" else echo "************** Unencrypted Key was NOT created *****************" fi if [ $CreateEncryptedPrivateKey == "true" ] then echo "************ Creating Encrypted Private Key ******************" echo "You will be prompted to enter the Import Certificate password. Be sure to enter the password: \"${CertP12Password}\"" echo "You will also be prompted to enter the pem passphrase. Be sure to enter the passphrase: \"${PemPassPhrase}\"" read -p "Press any key to continue... " -n1 -s openssl pkcs12 -in $CertP12Format -nocerts -out ./temp_cert openssl pkcs8 -inform PEM -in ./temp_cert -outform PEM -out $EncryptedPrivateKey -passout pass:$PemPassPhrase rm ./temp_cert echo "Encrypted Private Key created: $EncryptedPrivateKey" else echo "************** Encrypted Key was NOT created *****************" fi if [ $CreateJks == "true" ] then echo "************ Creating Java Key Store ******************" echo "You will be prompted to enter a password. Be sure to enter \"${KeyStorePassword}\" (3x)" read -p "Press any key to continue... " -n1 -s openssl pkcs12 -export -in ${CertPEMFormat} -inkey $UnencryptedPrivateKey -out ./keystore_bundle.p12 -name $KeyStoreAlias -CAfile $CertPEMFormat -caname root keytool -importkeystore -deststorepass $KeyStorePassword -destkeystore $JavaKeyStore -srckeystore ./keystore_bundle.p12 -srcstoretype PKCS12 rm ./keystore_bundle.p12 echo "Java Key Store created: $JavaKeyStore" else echo "********* Java Key Store was NOT created **************" fi
Manually create files for certificate authentication
To enable certificate authentication, you can manually create a CA-signed certificate for the connection's integration user or service account and its private key or Java KeyStone. To manually create these files, you'll need:
- Mozilla Firefox® or Microsoft® Internet Explorer®
- For macOS or Linux, a Terminal window; for Microsoft Windows®, OpenSSL
- Tenant Administrator rights in Anaplan
- To authenticate with a JKS, Java® SE Development Kit (JDK)
Step 1. Procure a certificate
Order a personal authentication certificate for Anaplan from Sectigo®. To ease connector maintenance, we recommend a three-year certificate. When completing the order, leave the default values under Advanced Security Options.
When the transaction is complete, Sectigo sends an email with instructions to collect your certificate. To install the certificate, click the link in the email in Mozilla Firefox® or Microsoft® Internet Explorer® (IE) on your desktop.
Note: Use Firefox or IE to collect your certificate; neither Google Chrome® nor Microsoft Edge® can generate it.
Step 2. Download the certificate
After you click the link in the email to install the certificate in Firefox or IE, download it from the browser. In Firefox, the certificate downloads as a P12 file; in IE, a PFX file.
To download the certificate:
- In Firefox for Windows, select Tools, Options, Privacy & Security, and then, under Certificates, click View Certificates. On the Your Certificates tab, select the certificate, click Backup, and save the certificate as a PKCS #12 (P12) file with a unique name and a password for the private key.
- In Firefox for macOS, select Preferences, Privacy & Security, and then, under Certificates, click View Certificates. On the Your Certificates tab, select the certificate, click Backup, and save the certificate as a P12 file with a unique name and a private key with a password.
- In IE, select Tools, Internet Options and then, on the Content tab, click Certificates. On the Personal tab, select the certificate, click Export, and save the certificate as a PKCS #12 (PFX) file with a unique name and a password for the private key.
Step 3. Extract the certificate
In macOS or Linux, perform the following in a Terminal window; in Windows, use OpenSSL:
- Navigate to the directory where the certificate was downloaded from the browser.
- Execute this command, replacing
<DOWNLOADED FILE>
with the full path of the downloaded P12 or PFX file.- In macOS or Linux:
openssl pkcs12 -in <DOWNLOADED FILE> -nokeys -out client_certificates.pem
- In Windows, also replace
<PATH TO .PEM FILE>
with the path to the certificate file's output directory:openssl pkcs12 -in "<DOWNLOADED FILE>" -nokeys -out "<PATH TO .PEM FILE>"\client_certificates.pem
Enter the password for the certificate's private key when prompted.
- In macOS or Linux:
- To confirm the certificate was extracted, verify
client_certificates.pem
appears in the output directory.
Step 4. Isolate and register the public certificate
The client_certificates.pem file contains three certificates—the root, intermediate, and public certificates. To isolate the public certificate:
- In a plain text editor, open the client_certificates.pem file.
- To delete the root and intermediate certificates, remove all text before the third instance of
-----BEGIN CERTIFICATE-----
. - Save the edited file as
ca_certificate.pem
, and note the fully qualified path to the file. - In Anaplan, upload and register the ca_certificate.pem file.
Step 5. Create a private key
To create a private key to use with the public certificate:
- In the Terminal window or OpenSSL, execute this command, replacing
<DOWNLOADED FILE>
with the full path of the downloaded P12 or PFX file:- For macOS or Linux:
openssl pkcs12 -in <DOWNLOADED FILE> -nocerts -out private_key.pem -nodes
- For Windows, also replace
<PATH TO PRIVATE KEY>
with the path to where to generate the private key:
openssl pkcs12 -in "<DOWNLOADED FILE>" -nocerts -out "<PATH TO PRIVATE KEY>\private_key.pem" -nodes
- For macOS or Linux:
- Note the fully qualified path to the generated
private_key.pem
file.
Step 6. Create the Java KeyStore
To house the private key, create a Java KeyStore (JKS) using the ca_certificate.pem
and private_key.pem
files. When you create the JKS, you assign its alias and password, which the connection uses to authenticate with Anaplan.
- In the Terminal window or OpenSSL, execute this command to create the KeyStone bundle as a P12 file, replacing
<ALIAS>
with the name for the JKS:- For macOS or Linux:
openssl pkcs12 -export -in ca_certificate.pem -inkey unencrypted_private_key.pem -out keystore_bundle.p12 -name <ALIAS> -CAfile ca_certificate.pem -caname root
- For Windows, also provide the
<PATH>
to the PEM files and the output directory for the KeyStore bundle:openssl pkcs12 -export -in "<PATH>\ca_certificate.pem" -inkey "<PATH>\private_key.pem" -out "<PATH>\keystore_bundle.p12" -name <ALIAS> -CAfile "<PATH>\ca_certificate.pem" -caname root
- For macOS or Linux:
- To create the JKS using the KeyStone bundle, execute this bundle, replacing
<PASSWORD>
with the password for the JKS:- For macOS or Linux:
keytool -importkeystore -deststorepass <PASSWORD> -destkeystore keystore.jks -srckeystore keystore_bundle.p12 -srcstoretype PKCS12
- For Windows, also provide the
<PATH>
to the KeyStone bundle:keytool -importkeystore -deststorepass <PASSWORD> -destkeystore keystore.jks -srckeystore "<PATH>\keystore_bundle.p12" -srcstoretype PKCS12
Note:
keytool
requires Java SE Development Kit (JDK). - For macOS or Linux:
Set up the Anaplan (Standard) connector
Note: To make the connector available for use in your organization's chains, an org security administrator first enables it from Configuration.
- From Chain Builder, click Connections , and then Create at the top right.
- Under Connector Connection, select Anaplan (Standard) and the default CloudRunner.
- Enter a unique name and description to help identify the connection.
- If using certificate authentication, under Resources, upload the public certificate and its JKS or private key file.
- Under Properties, enter the connector's details.
Property Details API base URI Enter the base URI for the Anaplan API. By default, http://api.anaplan.com
.Proxy URI If using a proxy server, enter its URI. Proxy username If using a proxy server, enter its username. Proxy password If using a proxy server, enter the password for the Proxy username property. Debug Select whether to display additional information when troubleshooting. - Under Authentication, enter the authentication details
Property Details Authentication type Select how to secure the connection:
- Basic/Certificate Auth for username/password or a CA-signed certificate
- Anaplan OAuth2 Authorization Code for OAuth 2.0
Depending on the authentication type selected, only the relevant properties detailed below will appear.
Learn more:
Note: When using an Anaplan OAuth2 Authorization Code, the "Refresh Token Behavior" setting in Anaplan must be set to non-rotatable.
Client ID (OAuth 2.0 only) Enter the ID for the integration users' OAuth grant. Client secret (OAuth 2.0 only) Enter the secret for the ID property. Authentication method (Basic/Certificate Auth only) Select an authentication method:
- For username and password, select Basic.
- For a CA-signed certificate, select Certificate.
Authentication URI (Basic/Certificate Auth only) Enter an Authentication URI. Defaults to https://auth.anaplan.com Username (Basic/Certificate Auth only) For basic authentication, enter the username of the connector's Anaplan integration user or service account. Password (Basic/Certificate Auth only) For basic authentication, enter the password for the Username property. Certificate path (Basic/Certificate Auth only) For certificate authentication by private key, enter the filename of the public certificate uploaded under Resources. KeyStore path (Basic/Certificate Auth only) For certificate authentication, enter the filename of the JKS uploaded under Resources. KeyStore alias (Basic/Certificate Auth only) For certificate authentication, enter the alias of the JKS. KeyStore password (Basic/Certificate Auth only) For certificate authentication, enter the password of the JKS. Private key (Basic/Certificate Auth only) For certificate authentication with a private key, enter the filename of the private key uploaded under Resources. Private key password (Basic/Certificate Auth only) For certificate authentication with an encrypted private key, enter the password for the Private key property. Note: All sensitive credentials are automatically encrypted and stored at Advanced Encryption Standard (AES)-256 encryption.
- Select the environments to use with the connection, and click Save.
- To test the connection, create and run a chain with the connector's List Actions command, and verify it returns a valid output.
Troubleshooting
If the connection to Anaplan fails:
- Verify the authentication credentials are correct.
- If using certificate authentication, verify the certificate hasn't expired, and renew if necessary.