Anaplan's Authorization Code Grant API Flow: A Seamless App-to-App Authentication Option

AnaplanOEG · November 2023

In the realm of contemporary application development, achieving seamless authentication is paramount for delivering an exceptional user experience. Anaplan, a prominent player in the realm of planning and performance management, presents a flexible and robust solution for enabling resource authorization between Anaplan and third-party applications that support OAuth, courtesy of its Authorization Code Grant API Flow. In the following blog post, we will delve into the intricacies of the Authorization Code Grant option, showcasing its exceptional utility in facilitating a frictionless integration between Anaplan and other cloud-based applications.

Create an OAuth Client

As a first step, please follow the detailed steps outlined in the Create an OAuth 2.0 client Anapedia article. When configuring your client, you'll need to make a choice between the following two options:

Non-Rotatable (Non-Expiring) Refresh Tokens: If your application requires Refresh Tokens that never expire, you can achieve this by configuring a non-rotatable Refresh Token in the OAuth client settings within the Anaplan Administration console. With this setting in place, the device that has been initially authorized (as explained in the next step) will never require manual authentication again.
Rotatable Refresh Tokens: On the other hand, if you prefer Refresh Tokens with a predefined expiration time, you can select the "Rotatable" setting and specify a maximum expiration time, typically set to one year (31,556,926 seconds). By default, the expiration time is set to 43,000 seconds (equivalent to 12 hours). Once this predefined time has passed, the refresh token will become invalid, necessitating manual re-authentication.

Please note that you must be a Tenant security administrator to create and work with OAuth 2.0 clients.

In the configuration of the OAuth client, you will also need to specify a callback URL. A callback URL, in the context of Anaplan's Authorization Code Grant API Flow, is the designated endpoint where the user is redirected after granting or denying permission for a third-party application to access their Anaplan resources. The third-party application typically provides this URL and serves as a crucial bridge in the OAuth authentication process. When the user approves access, it signals the granting of authorization to the third-party application, allowing it to securely interact with and utilize specific Anaplan resources. This pivotal step ensures a seamless and secure integration between Anaplan and other cloud-based applications while maintaining the privacy and security of Anaplan users' data.

After your OAuth client has been created, it should be similar to the example below. Note that the example has two callback URLs. In the first step of the Authorization code grant flow, one of the callback URLs must be used in the verification URL.

Authorization Code Grant API Flow

Let's now delve into the steps of the Authorization Code Grant API Flow and discover how to authenticate with Anaplan seamlessly.

Step 1: Assemble the Verification URL

To kickstart the Authorization Code Grant process, the initial step entails assembling the Verification URL, with subsequent authentication by an end-user within the Anaplan environment, either through basic authentication or Single Sign-On (SSO).

Here is an example that is described below:
https://us1a.app.anaplan.com/auth/authorize?response_type=code&redirect_uri=https://anaplan.com&scope=openid%20profile%20email%20offline_access&client_id=XXXXXXXXXXXXXXXXXXXXXXXXXX&state=YW5hcGxhbg==

Let's now dissect this Verification URL in a methodical fashion:

Base URL: https://us1a.app.anaplan.com/auth/authorize
This serves as the URL's foundational point, clearly marking it as Anaplan's dedicated authentication and authorization gateway.

Parameters:

Response Type: The response_type parameter takes center stage here, dictating the kind of response the client application anticipates. In this scenario, it's set to code, signifying the client's expectation of receiving an authorization code in response.
Redirect URI: As for the redirect_uri parameter, it designates the specific web address to which the user will be directed after making the decision to grant or decline authorization. In this instance, it's firmly anchored to https://anaplan.com.
Scope: The scope parameter plays a pivotal role by outlining the extent of access and permissions that the client application seeks. This parameter has multiple values, including:
- openid: An indicator of the client's request to access the user's OpenID information.
- profile: A request for access to the user's profile information.
- email: A request for permission to view the user's email address.
- offline_access: A crucial inclusion, signaling the client's desire for long-lasting access, often employed for vital tasks such as token refreshing.
Client ID: The client_id parameter is a unique credential provided by Anaplan in the creation of the OAuth Client. The value performs the critical task of identifying the client application initiating the request and ensures that the request is both genuine and endorsed.
State: While optional, the state parameter adds an extra layer of security. It generates a random value on the client's side, serving as a safeguard to maintain the user's session state and thwart potential cross-site request forgery (CSRF) attacks.

In summary, this URL serves as the launchpad for initiating the OAuth 2.0 authorization code flow within Anaplan. It clearly outlines the response type, redirect URI, requested scopes, client ID, and even incorporates a state parameter for enhanced security. When users interact with this URL, they are presented with the choice to grant or deny authorization to the third-party application. If consent is granted, an authorization code is bestowed upon them, ready to be redirected to the specified web address for further authentication, thereby granting access to Anaplan's invaluable resources.

Step 2: Get an Authorization Code

Once a Verification URL has been assembled, it needs to be opened in a browser to allow an end user to authenticate either through basic authentication or Single Sign-On (SSO). Once there has been a successful authentication, an authorization code will be returned in the URL as indicated in the demonstration below. In the next step, this authorization code will be used in the body of the following REST API request.

The authorization code has a relatively short lifespan of just a few minutes. It is designed to be a one-time-use code to help reduce the risk associated with intercepted or stolen authorization codes, as they become useless after their expiration. Once the authorization code expires, the client application must use it promptly to exchange it for an access token and a refresh token if needed. If the code expires before it is used, the authorization process must be initiated again.

Step 3: Get the Access and Refresh Token

Once there is a valid authorization code, it needs to be used in the body of a POST API request to the following endpoint.

https://us1a.app.anaplan.com/oauth/token

Include the following parameters:

{
    "grant_type": "authorization_code",
    "code": "<< INSERT YOUR AUTHORIZATION CODE >>",
    "client_id":"<< INSERT YOUR CLIENT ID >>",
    "client_secret":"<< INSERT YOUR CLIENT SECRET >>",
    "redirect_uri": "<< INSERT YOUR CALL BACK URL >>"
}

On execution, you should see an API response similar to the following:

Step 4: Refresh the Access Token

To ensure continuous access to Anaplan resources, you'll need to refresh the Access Token periodically (every < 2,100 seconds).

Make a POST request to the following endpoint:

https://us1a.app.anaplan.com/oauth/token

Include the following body parameters:

{
    "grant_type": "refresh_token",
    "client_id":"<< INSERT YOUR CLIENT ID >>",
    "client_secret":"<< INSERT YOUR CLIENT SECRET >>",
    "refresh_token": "<<INSERT YOUR PRIOR REFRESH TOKEN>>"
}

On execution, you should see an API response similar to the following:

Access Token Duration
Keep in mind that the Access Token has a limited validity of 2,100 seconds (equivalent to 35 minutes). To maintain uninterrupted access to your resources, it's essential to align your application's logic accordingly, utilizing a valid Refresh Token to obtain a fresh Access Token. It's worth noting that the Access Token renewal process exclusively relies on the presence of a valid Refresh Token.

Summary

In summary, Anaplan's Authorization Code Grant API Flow offers a streamlined and robust mechanism for authenticating your third-party application, enabling it to obtain essential access authorization for Anaplan's valuable resources. By diligently following the step-by-step instructions provided in this guide and incorporating the recommended best practices, you can establish a secure and uninterrupted pathway to access Anaplan's resources. This approach adheres to contemporary security standards, providing a reliable and well-established foundation for your integration efforts.

Other Related Resources

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

AnyaS · February 1

Superhelpful step-by-step. Thank you for taking the time to put this article together, Quin.