OEG Best Practice: Using Anaplan Connect with OAuth


How to Use Anaplan Connect with OAuth Authorization

Anaplan Connect is a powerful command line interface that allows you to automate your Anaplan environment, enabling seamless data integration and synchronization between Anaplan and other systems. While Anaplan Connect offers various authentication methods, including basic authentication and certificate authentication, this blog post will guide you through the process of using Anaplan Connect with OAuth authorization—a more secure and flexible method for managing authentication. It's essential to note that OAuth is supported in Anaplan Connect 4.x and later versions.

Prerequisites for Using OAuth Authorization

Before you can use OAuth authorization with Anaplan Connect, you'll need to meet several prerequisites:

  1. Create a Device Grant OAuth Client
    1. Begin by creating a Device Grant OAuth client. You can find detailed instructions in the official documentation.
    2. When creating the OAuth client, you must choose whether to have a rotatable refresh token or a non-rotatable one. The choice depends on your organization's policies regarding the maximum Time To Live (TTL) for a refresh token. If you opt for a rotatable token, it can expire after a maximum of one year (31,536,000 seconds). In contrast, a non-rotatable token never expires.
    3. Save the Client ID, as this will be used in the Anaplan Connect Script
  2. Create an "Exception User"
    1. Anaplan OAuth device grants require an "exception user" with Single Sign-On (SSO) toggled off. During the initialization of Anaplan Connect with OAuth, this user will need to be authenticated using a standard username and password.

After the prerequisites are established, follow the next steps to use Anaplan Connect with OAuth.

Step #1: Copy the Sample Script

  1. Navigate to the examples folder within your Anaplan Connect installation directory.
  2. Locate the sample script named Authentication - Generate OAuth Token With Force Register.bat (on Windows) or Authentication - Generate OAuth Token With Force Register.sh (on macOS or Linux).
  3. Copy this script to a new location for customization and rename the file (per your preferences).

Step #2: Update the Script

  1. Depending on where you've installed AnaplanClient.bat (Windows) or AnaplanClient.sh (macOS/Linux), update the path in your copied script to point to the correct location.
  2. In your copied script, paste the ClientId obtained in prerequisites.
  3. In the Operation line, confirm the --forceRegister parameter is after the -auth ${AuthUrl} and before any operations such as listing objects, uploading files, or executing a Process or Action.
  4. When creating the OAuth client, if you selected a rotatable refresh token, also add --rotatable after the --forceRegister parameter.

Step #3: Execute the Script and Authorize the Device

  1. Open a command prompt (Windows) or a terminal window (macOS/Linux), and execute the modified script. When using the --forceRegister parameter, the script will provide a URL that you need to copy and open in an incognito browser session.
  2. In the incognito browser session, open the provided URL and authenticate the user with basic authentication. This step will authorize the device where the Anaplan Connect script is running.

Step #4: Remove the Force Register Parameter and ready the script for unattended script execution

  1. After successfully authorizing the device through user authentication, edit the script and remove the --forceRegister parameter.
  2. Your script is now ready to execute unattended as a scheduled task, automating your Anaplan processes. Please note that device authorization cannot be transferred to another device.

By following these steps, you can leverage Anaplan Connect's OAuth authorization to enhance the security and automation of your Anaplan integration processes, ensuring smooth data synchronization with Anaplan and other systems.

Other helpful articles about Anaplan Connect:

Author: Quin Eddy, @QuinE - Director of Data Integration, Operational Excellence Group (OEG)