[Start Here] OAuth - Part 1: The Basics

AnaplanOEG · February 2022

What is available today?

Up until the release of OAuth support, when it came to integration, Anaplan supported 2 different methods:

Basic Authentication: Scripts and other tools whose purpose is integrating with Anaplan would simply store the credentials of a known Anaplan user. This method requires maintenance as those credentials need to be updated every 3 months (the same way Users need to update their password when logging into Anaplan). It also poses security risks as usernames and passwords need to be stored somewhere accessible by the tool or script.

The usual best practice is to use a dedicated "service account" user, i.e an email that is not intended to be used by an Anaplan end user, but solely for integrations.
There may be license implications, please contact your Anaplan Business Partner.

Certification Authority (CA) certificates: These are certificates issued by a third-party provider. The certificate allows Anaplan to verify that the integration request is legitimate and is an authenticated request from the user.
It adds an additional layer of security and unlike basic authentication, there will be no need to amend the authentication method every 3 months.

To have a better understanding of how CA certificates work, have a look at this article.

In a nutshell, these two ways to authenticate an integration request by using private information to generate an authentication token,

What are the key benefits from OAuth?

How do OAuth works?

Self-service (SS) OAuth is an industry-standard protocol for authorization delegation. It lets customers build secure integrations to third-party client applications without exposing privileged credentials or maintaining certificates while sharing digital resources.

So OAuth is more about "authorization" than "authentication". If you analyze the steps of implementing it, you'll see that you need to authorize a client to use OAuth with Anaplan.

The difference with authentication might be slim but this is something that needs to be remembered.
The analogy of the hotel key card explained in this article is very clear and helps to understand why there is a difference between those 2 concepts.

To know more about OAuth, visit Anapedia.

There are 2 supported flow types for SS OAuth: Authorization Grant, and Device Grant.

Their concept is similar:

Step 1 is to connect to the Anaplan Authorization Service, the app will manage to make the Anaplan login screen appear.
Once successfully logged in, you will be prompted with a message stating that a client (yours) is trying to connect to Anaplan. You'll need to validate that request.

Step 2, you will receive OAuth information that can be used for Steps 3 and 4.

There are 2 important pieces of information here: the access token (identical to a token that you'd get if you tried to use Anaplan Authentication API) and the refresh token. We will see how to use them in the use case.

Authorization grant

The schema below shows the Authorization Grant flow.

The authorization code grant is the most common OAuth 2.0 grant type used to protect confidential credentials. It obtains and exchanges a single-use authorization code for an access token, which is made only available to the client and not shared with the resource owner.

Device grant

The device grant is a grant that lets devices with limited input capabilities, such as a smartphone, obtain access tokens. Rather than authenticate the user directly, the device prompts the user to authorize their device via a link on their computer or smartphone.

The Device Grant varies a bit in the sense that there is no web client, and the user needs to perform the requests directly (via some dedicated tools or code). We illustrate this device grant type later in another next article.

How to leverage the OAuth protocol?

In this section, we'll discuss what OAuth can bring to the current way to integrate with Anaplan.

Improving the way to generate API tokens

The main outcome of the OAuth protocol is the generated tokens out of successful API calls. The most important one is the access token, it is similar to the authentication tokens you could get by basic or certificate-based authentication process (more information here).

This is done by storing the credentials information in the scripts and there are some elements to consider:

You need to store the credentials, which is always a concern in terms of security.
Actions cannot be executed under the Anaplan credentials of the user that clicked on that link.

Now, with OAuth support and some tooling, there is something you can achieve in a more native and secure way!

Using the refresh token

The refresh token is used to get new access tokens. As we all know, they are mandatory for Anaplan APIs calls.

The access tokens also last 2.100 seconds or 35 minutes.
As you can see in the OAuth screen, a refresh token can be either "Non-rotatable" like here:

or "Rotatable". In which case you need to specify a lifetime.

The impact is important in terms of how to use the refresh token.

When the refresh token is "Non-Rotatable"

In that case, the same refresh token can be used on an unlimited basis as it never expires.

You can execute this API call several and over the 35 minutes limit, you'll get a valid response.

When the refresh token is Rotatable

When the refresh token has been set to this setting, there are 2 main consequences:

The refresh token will stop being usable after the defined lifespan.
The refresh token can only be used once during the lifespan.

Those aspects increase the security around the refresh token use, although it can heavily impact the way you code around it.

Indeed, in the response you get from using the refresh token, you'll get another refresh token. You can use it for the next call and you'll need to store it.

Now that we know the benefits of OAuth and the concepts, let's move on to Part 2: an illustrated Use Case.

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

Contributing authors: Christophe Keomanivong and Joey Morisette.