The OAuth 2 client credentials flow allows client applications (i.e. Patchworks) to authenticate and obtain access to resources, without involving specific user intervention.
The exact mechanism used for client credentials authentication depends on the implementation of the authorisation server for the system in question, but a common mechanism is client secret.
This is where a client application (in this case, Patchworks) authenticates itself by sending its unique client identifier and client secret to the authorisation server, and receives a token in response.
If you'd like more detailed information about how OAuth 2 client credentials authentication works, there's some great background information on the Postman website.
It can be useful to compare how existing connectors have been configured for OAuth 2 (client credentials) authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:
You can install any of these for comparison.
The OAuth 2 authorisation code flow requires a user (in this case, a Patchworks user, adding a connector instance for use in process flows) to log into an authorisation server and grant permission for Patchworks to access the required data.
When a Patchworks user adds an instance of a connector and chooses to authenticate with OAuth 2 (authorisation code) they are directed to the authorisation server for a third-party service, where they log in and 'allow' requested access. A sample user journey for NetSuite is shown below:
Here, we:
Add an instance and confirm credentials.
Are redirected to NetSuite, where we log in.
Are presented with information about what access is being requested, and choose to proceed.
Return to the Patchworks connector page, where our new NetSuite instance is added and ready to use in process flows.
If you'd like more detailed information about how OAuth 2 authorisation code authentication works, there's some great background information on the Postman website.
When setting up 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.
The following example is for a NetSuite implementation - please check your API documentation for your own required values:
When specifying redirect URIs for OAuth 2, the following values can be used:
Production
It can be useful to compare how existing connectors have been configured for OAuth 2 (authorisation code) authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:
You can install any of these for comparison.
OAuth 2 is a protocol which allows users to grant limited access to their resources/data in an application or service (e.g. NetSuite), to another application or service (in this case, Patchworks) without ever sharing their login credentials.
The authentication flow and associated configuration for OAuth 2 vary according to which grant type is used. Patchworks supports the following OAuth 2 grant types:
OAuth 2 provides a more streamlined, standardised approach than OAuth 1 - it’s easier to implement and more suitable for a wide range of applications.
This page walks through the steps required to configure OAuth 2 authentication (client credentials flow) for a connector.
Here, we're using Shopware 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.
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 Shopware API docs for this example).
Check the documentation for your third-party application and ensure that any in-app setup required for OAuth 2 has been completed.
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.
Step 1 Check the API documentation for the third-party application that you're using - confirm that OAuth 2 authentication (client credentials 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 client credentials and click the create button.
Step 6 Authentication variables are displayed. By default, the OAuth 2 client credentials type includes a range of default authentication variables:
These are known variables that a user must provide to authenticate an instance of this connector with this authentication method.
The following parameters are required for the OAuth 2 client credentials flow, and are configured to be displayed to users when they attempt to add an instance for this connector:
Scope
scope
If your API documentation does't direct you to add a specific value, leave the default value of scope in place. The default value is displayed to your users when they choose to add an instance for this connector.
Grant type
client_credentials
If your API documentation does't direct you to add a specific value, leave the default setting of client_credentials in place. The default value is displayed to your users when they choose to add an instance for this connector.
Client ID
None
A client id is required whenever a user chooses to add an instance for this connector - default values are not applicable.
Client secret
None
A client secret is required whenever a user chooses to add an instance for this connector - default values are not applicable.
Response authentication token key
access_token
If your API documentation does't direct you to add a specific value, leave the default value of access_token in place. The default value is displayed to your users when they choose to add an instance for this connector.
In each case, you can change the parameter name, default value and settings for how the field is made available to users when they choose to add connector instances. You cannot change the parameter key.
Step 7 Check your API documentation for any additional parameters that are required for authentication - do you need users to provide any additional information to authenticate instances of this this connector?
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 8 Select the URL parameters tab and provide a request URL for authentication - you'll find this in your API documentation:
Also check your API documentation for any query parameters required for this URL and add them as needed.
Depending on the authentication method, you may find that some default authentication and/or other variables have been added as URLparameters, automatically. For OAuth 2 (client credentials) there are no default URL parameters.
Step 9
Select the header tab and add any authentication variables that need to be passed in the authentication request header - you'll find this in your API documentation:
For OAuth 2 (client credentials), a content-type parameter is added by default, with a value of application/x-www-form-urlencoded. Check your API documentation - if necessary you can change this value.
Step 10 Select the body tab and add any authentication parameters/content to be passed in the authentication request body - you'll find this in your API documentation.
Depending on the authentication method, you may find that some default authentication and/or other variables have been added as bodyparameters/content, automatically. For OAuth 2 (client credentials) there is no defaultbodycontent.
Step 11 This completes our setup for OAuth 2 (client credentials) 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.
If an authentication variable is required elsewhere in the connector setup (for example, we know that the url variable is required for authentication AND endpoint requests) it's worth adding it to the connector variables tab once and then choosing to 'use' it wherever needed in the connector setup.
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.
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.
When specifying redirect URIs for OAuth 2, the following values can be used:
Staging
Production
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.
Consider the following when setting your client_type parameter value:
confidential . Setting this value means that when a second call is made to get a token, basic auth is added to the header using the client_id and client_secret.
public (or any other value). Setting this value means the second request does not send authorisation in the header.
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.
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.
.svg?alt=media&token=ddeb7ae5-d7c7-46f5-baf3-55a3d5b1478f)
