Configuring OAuth 2 authentication (authorisation code)

To view this content in our official product documentation, click here.

Introduction

This page summarises the configuration for the OAuth 2 authentication (authorisation code flow) authentication method.

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 the steps detailed here.
• Ensure you have API documentation for your third-party application to hand.
• 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 the 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 (also known as callback URLs) for OAuth 2, the following values can be used:

Environment	URI
Staging	https://stage.app.wearepatchworks.com/oauth/authenticate
Production	https://app.wearepatchworks.com/oauth/authenticate

The Steps

{% stepper %} {% step %} Review OAuth 2 requirements for the API

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. {% endstep %}

{% step %} Edit the required connector

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.

{% endstep %}

{% step %} Access authentication details

Select the authentication option:

 

{% endstep %}

{% step %} Add a new authentication method

Click the add new authentication method button:

 

{% endstep %}

{% step %} Add a new authentication method

Complete basic details for this authentication method, using the table below as a guide:

Field	Summary
Enter a name...	The name to be displayed to users when this authentication method is shown.
Select an authentication method	Select OAuth 2 Authorisation Code from the dropdown list.
Timeout limit	Set the number of seconds to wait for an authentication request to complete before timing out.
Enter a link to documentation	It's often useful to provide a link to the API documentation that you are working from to configure this authentication type. Adding a link here ensures that the relevant documentation can be accessed easily if you or someone else needs to edit/understand this configuration later.

For example:

 

{% endstep %}

{% step %} Create this authentication method

Click the create button to confirm details - for example:

 

The authentication method is saved, and configuration options are displayed in the authentication setup panel, over a series of tabs. For example:

 

The same set of tabs is displayed for any authentication type, but the default options may vary depending on the authentication type you have chosen to configure.

For general information about these configuration tabs, please see Authentication method options.

{% endstep %}

{% step %} Review & update authentication variables

By default, a range of default auth variables is included - these are typically expected for the OAuth 2 authorisation code authentication type. For example:

 

These are variables that must be passed in when a user attempts to authenticate an instance of this connector. Values might be set as default, or provided by the user during the instance creation process.

You should review/update/add/remove authentication variables according to the API documentation for your connector. Some general guidelines are summarised below.

Variable	Notes
State length	This is a numeric value which determines the length of a random string generated (behind the scenes) during the OAuth process, for verification purposes.
Scope	Determines the scope of access that Patchworks will have to associated data.
Client ID & Client secret	These credentials allow Patchworks to authenticate and interact with your third-party system.
Response authentication token key	Tells Patchworks where to find the auth token in your system's response. Typically set to access_token.
Grant_type	Tells the OAuth server what kind of request you're making and what credentials you are providing to prove your identity. Typical options for OAuth 2 authorisation code are:   grant_type=authorization_code The server checks the code and returns a token. grant_type=refresh_token.  A refresh token is provided, which proves prior authorisation. This is used to retrieve a new token. Note that some systems will use the grant_type parameter to handle authorisation and refresh tokens, whereas others will use a separate parameter (e.g. refresh_grant_type) for refresh tokens. Your API documentation should guide you on this.
Response type key	Determines what is returned from the authentication request. The most typically used option for OAuth 2 authorisation code is code. This sets an authorisation code and appends it to the given callback URL. This code is then exchanged for an access/refresh token (depending on the associated grant type).
OAuth Authorised Code	This advanced setting is not required for general use.
Dashboard OAuth Callback URL	Sometimes known as a redirect url, this is the address used for returning the authorisation code. The default value is: https://app.wearepatchworks.com/oauth/authenticate. Typically, this should not be changed.
Refresh Grant type	Some systems will use the grant_type parameter to handle authorisation and refresh tokens, whereas others will use a separate parameter for refresh tokens (e.g. refresh_grant_type set to refresh_token). Your API documentation should guide you on this.
Response Refresh Token Key	Tells Patchworks where to find the refresh token in your system's response. Typically set to refresh_token.

{% hint style="warning" %} Some APIs are case-sensitive when it comes to adding variables. Be sure to enter key names exactly as they are specified in the API documentation. {% endhint %} {% endstep %}

{% step %} Review & update URL parameters

For OAuth 2 (authorisation code authentication, you can specify three URLs:

URL	Notes
URL / Token URL	Used to obtain a token, based on the code that is returned from the Authorise URL request. For example: Authorise URL	This URL is triggered when a user chooses to save an instance of this connector. Typically, it's a page in your third-party system where the user can confirm that access is allowed. For example:  (Optional) Re-authenticate URL	If you are using refresh tokens, this is the URL to be used. For example:  For general guidance on these tabs, refer to the Authentication method options section. {% endstep %} {% step %} Test authentication 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 are directed to your third-party authorisation server and asked to authorise access - then redirected back to Patchworks. {% endstep %} {% endstepper %} 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 only includes 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.