Anaplan's Device Grant API Flow: A Seamless Machine-to-Machine Authentication Option

AnaplanOEG
AnaplanOEG
edited February 29 in Best Practices

In the world of modern application development, seamless authentication is key to providing a smooth user experience. Anaplan, a leading platform for planning and performance management, offers a versatile approach to authentication through its Device Grant API Flow. In this blog post, we'll explore the Device Grant option, which is particularly useful for machine-to-machine communication, and provide you with essential tips to make the most of it.

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:

  1. 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.
  2. 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.

After your OAuth client has been created, it should be similar to the following:

image.png

Device Grant API Flow

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

Step 1: Get the Device Grant Verification URL

To initiate the Device Grant process, you need to make a POST request to the following endpoint:

https://us1a.app.anaplan.com/oauth/device/code

Include the following body parameters:

{
    "client_id":"<< INSERT YOUR CLIENT ID >>",
    "scope":"openid profile email offline_access"
}

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

image.png

Step 2: Authenticate in Incognito Mode

Once you have received the Device Grant Verification URL from the previous step, open a browser in Incognito mode and navigate to the URL to complete the authentication process.

2023-11-01_15-00-17 (1).gif

Step 3: Get the Access and Refresh Tokens

After successful authentication, it's time to obtain the Refresh Token. Make a second POST request to the following endpoint:

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

Include the following body parameters:

{
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
    "device_code":"<< INSERT THE DEVICE CODE FROM THE FIRST REST API CALL >>",
    "client_id":"<< INSERT YOUR CLIENT ID >>"
}

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

image.png

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 >>",
    "refresh_token": "<<INSERT YOUR PRIOR REFRESH TOKEN>>"
}

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

image.png

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 Device Grant API Flow offers a streamlined and effective method for authenticating your applications, particularly in machine-to-machine interactions. By adhering to the steps detailed in this guide and implementing the suggested best practices, you can establish a secure and uninterrupted pathway to access Anaplan's resources, all without the need for usernames, passwords, or cumbersome certificates.

Other Related Resources

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

Tagged:

Comments

  • AnyaS
    AnyaS

    Another exemplary set of documentation. Thank you, Quin!

Categories