Community Perspective: Using OAUTH2 to develop custom Anaplan connector for Azure

Introduction

The release of OAUTH2 authentication for the Anaplan API opens the door to developing more native connectors across all the major cloud platforms. In this article, I explain how you can configure a custom connector on Azure for use in Logic Apps. The benefit of a custom connector is that you can expose all the Anaplan API functionality in a structured and controlled manner for deployment and use across your Azure environment. In addition, the OAUTH2 authentication flow gives you strong control over access, as access can be assigned or revoked at the connector level and also via the Tenant Admin console in Anaplan.

Configuration

Anaplan OAuth client

The first step is to configure an OAuth client in Anaplan. This is done via the Administration section on your tenant. As a Tenant Admin, log in and open the Administration section. Select Oauth Clients in the left panel, and then in the Security > OAuth clients add a new OAUTH client:

In the window, above populate the following for now:

• Name: Enter a sensible name for the client (i.e., "Azure_Logic_Apps")
• Type: Select authorization code grant
• Allowed callback URLs: Leave this blank for now. We will update this once we configure Azure and get a URL assigned.

Azure connector configuration

Login to your Azure portal. From the home page, select + Create a Resource. Search for "Logic Apps Custom Connector" and select Create.

Complete the Basics section as follows:

• Subscription: Select the subscription to use
• Resource Group: Select the resource group for the connector
• Custom Connector Name: Enter a sensible name for the connector. In my design, I have created different connectors for the various Anaplan APIs so I can segregate between different roles in my org, and so I have "Anaplan_Integration;Anaplan_SCIM" and "Anaplan_Cloudworks". It may be this segregation is not needed for you, so you may just use "Anaplan".
• Region: The region is important. When you use the custom connector in a Logic App, the region of the Logic App must be the same as the region of the connector.
• Associate with integration service environment: If you have configured an integration service environment, then tick this and select the environment below (this is not required if you do not want to enforce a segregation of environments for the connector).

Once you have made your inputs, add any tags, and then review and create the resource. Once the deployment is complete, you can now configure the connector.

General > Custom Connectors

If you have a Postman Collection or OpenAPI definition, then you can try and import this. I tried using a Postman collection, but Azure didn't like it so I configured my connector manually. It may be my instance was buggy, so give it a try as it may save you some steps.

General > General Information

In this section, you can add a logo and description for the connector, and set up the host details. Note: the host below is the host for the API calls and not the authentication end point.

Security > Authentication Type

Select OAuth 2.0:

Security > OAuth 2.0

Enter the OAuth 2 configuration details below:

• Identify Provider: Generic OAuth 2
• Client Id: See Fig 1 below. This is the client ID value generated in Anaplan when you create the OAuth Client.
• Client Secret: See Fig 1 below. Copy the client secret from Anaplan.

Fig 1. OAuth Client Details in Anaplan Admin Console

Authorization URL: This is the correct URL: https://us1a.app.anaplan.com/auth/authorize. In the Anaplan docs and Postman, the configuration uses a "?" at the end of the URL; do not do this in Azure as Azure will add the "?".

• Token URL: https://us1a.app.anaplan.com/oauth/token
• Refresh URL: https://us1a.app.anaplan.com/oauth/token
• Scope: openid profile email offline_access

Once you have entered these details, update the connector to get a redirect URL. When this is available, copy the value and paste this into the field Allowed callback URL's in the Anaplan Admin console, and save this configuration in Anaplan.

Definition

With the authentication configured, you are now free to define the scope of your API as needed. Use the API documentation from Anaplan and copy the actions that you need.

As an example, you can retrieve cell data for a view for a selected model and workspace. Reviewing the documentation on Anaplan, the path looks like the below:

We can reflect this in the connector setup either by updating the swagger definition (via the swagger editor) or through the wizard, which I show below.

Under Actions select new action:

General setup

• Summary: A user friendly name for the action
• Description: A description of the action
• OperationID: a short system name for the action

Request

Click the button + Import from Sample. In the menu bar, enter the details per the documentation above:

URL: Do not include the base URL below (api.anaplan.com/2/0/); just add the path for this call. You can see I have also created variables below by wrapping items in single curly brackets. When the connector is used, then the field will be available to populate as variables.

Once you have populated the above you should end up with something like the below:

If you wish to add templating for the responses, then you can adjust this and include further validations. But, at this point, you now have a connector that gets view data for a selected workspace, model and view.

Update the connector and test in a new Logic App.

Testing

Below I have a simple Logic App, with a recurrence trigger:

If you add a new step and select Custom Connector, then you should now see your connector with the operations displayed:

If you select Get View Data and enter the variables, you can test the connector. Notice how the variables we defined in the configuration are now available to populate.

If we manually run the flow to test the connection we can see that it runs successfully and returns some data:

Conclusion

OAuth 2 has finally opened the door to enable us to develop custom connectors on the major cloud platforms. The purpose of this guide is to share the mechanics with Community and I hope that, with the API documentation and a bit of learning about Logic Apps, you can see the potential for to develop more complex integration flows in the future.