Configuring OAuth 2 authentication (authorisation code)
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:
The Steps
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.
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.
Access authentication details
Select the authentication option:
Add a new authentication method
Click the add new authentication method button:
Add a new authentication method
Complete basic details for this authentication method, using the table below as a guide:
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:
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.
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.
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_codeThe 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.
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.
Review & update URL parameters
For OAuth 2 (authorisation code authentication, you can specify three URLs:
URL / Token URL
Used to obtain a token, based on the code that is returned from the Authorise URL request. For example:
https://oauth.myapp.com/token/{{account}}
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:
https://oauth.myapp.com/authorize/{{account}}
(Optional) Re-authenticate URL
If you are using refresh tokens, this is the URL to be used. For example:
https://oauth.myapp.com/refresh-token/{{account}}
Review & update remaining configuration tabs
There are no special considerations for configuration options on the remaining tabs. Check the API documentation for your third-party system and update these as needed.
For general guidance on these tabs, refer to the Authentication method options section.
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.
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.
Last updated
Was this helpful?