Configuring OAuth 2 authentication (authorisation code)
Introduction
This page walks through the steps required to configure OAuth 2 authentication (authorisation code flow) for a connector.
Here, we're using NetSuite as an example. General principles will be the same for any system that supports this authentication method but please refer to your own API documentation for specific setup requirements.
Preparation
For this task, we'll be using techniques described in previous connector variables and authentication method options sections - we advise getting familiar with these before attempting steps detailed here.
Ensure that you have API documentation to hand, for your third-party application (we're using NetSuite as an example).
Check the documentation for your third-party application and ensure that any in-app setup required for OAuth 2 has been completed. For example, NetSuite's documentation includes a section on tasks that administrators must complete to support OAuth 2 for integrations.
Ensure that you have all required OAuth 2 credentials for testing.
We recommend using Postman to test any authentication methods that you're adding for a connector.
Redirect URIs
When specifying redirect URIs for OAuth 2, the following values can be used:
| Environment | URI |
|---|---|
Staging | |
Production |
The Steps
Step 1 Check the API documentation for the third-party application that you're using - confirm that OAuth 2 authentication (authorisation code flow) is supported, and for any special requirements.
Step 2 Log in to the Patchworks dashboard and navigate to process flows > connectors & instances, where all of your installed connectors are shown. From here, access settings for the connector that you need to update with a new authentication method - for example:
If you're building a new connector, you can pick up these steps when you reach the authentication section of the connector builder.
Step 3 Access authentication details:
Step 4 Click the add new authentication method button:
Step 5 Complete basic details for this authentication method - ensure that you set the authentication type to OAuth 2 authorisation code and enter the required URL(s) from your API documentation.
For OAuth 2 (authorisation code) authentication, two URLs are required. The first (URL) is the authentication endpoint and the second (Additional URL 1) is the authorise endpoint. Please refer to your API documentation for these values.
Click the create button when you've finished, for more configuration options - for example:
Step 6 By default, the OAuth 2 authorisation code type includes a range of default auth variables:
These are known variables that a user must provide to authenticate an instance of this connector using this authentication method.
Mandatory variables are locked however, you can change the display name if required. You can also add more auth variables here if needed.
Some APIs are case sensitive when it comes to adding variables - be sure to enter key names exactly as they are specified in API documentation.
Step 7 Now we'll check to see if there are any shared connector variables that need to be used as auth variables.
In our example, we need to use the accountid connector variable for authentication, because this is a user-provided value that forms part of our authentication request URL path (defined in step 5). So, we can simply choose to use the accountid connector variable as an auth variable for this authentication method:
To do this:
Click the connector variables tab.
Click the use button associated with the variable we want to use for our new authentication method.
That variable is added to this authentication method as an auth variable.
Step 8 Next, we need to confirm/change where any information that users provide for auth variables should be injected into authentication requests.
Default auth variables are pre-configured to be passed into API requests, as most commonly needed. For example, if we check the URL parameters tab now, we'll see that some of our user-provided auth variables have been added automatically:
And if we check the body tab now, we'll see that remaining user-provided auth variables have been added automatically:
Check the API documentation for your third-party application and ensure that all required auth variables have been added, and are being passed in the right place. Don't forget to save any changes that you make.
Step 9 This completes our setup for OAuth 2 authorisation code authentication. Now, when a user adds an instance of this connector and chooses to use this authentication method, they are prompted to provide all required/configurable authentication variables. Upon confirmation, they will be directed to your third-party authorisation server and asked to authorise access - then redirected back to Patchworks.
Next steps
When you configure a process flow connection shape to use a given instance, you can then choose from a list of available endpoints. For example:
This list will only include endpoints for which the same authentication method is enabled, as was used to add/authenticate the selected instance.
So, having added a new authentication method, you must enable it for any connector endpoints that you might want to use with instances that are added using this authentication method.
Last updated
