Anaplan's Device Grant API Flow: A Seamless Machine-to-Machine Authentication Option
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:
- 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.
After your OAuth client has been created, it should be similar to the following:
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:
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.
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:
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:
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
- Anaplan's Authorization Code Grant API Flow: A Seamless App-to-App Authentication Option
- Anaplan REST API with Python OAuth Example
- Using OAuth with Anaplan Connect
Author: Quin Eddy, @QuinE - Director of Data Integration, Operational Excellence Group (OEG)
Comments
-
Another exemplary set of documentation. Thank you, Quin!
0
