Introduction

The OAuth 2 client credentials flow allows client applications (i.e. Patchworks) to authenticate and obtain access to resources, without involving specific user intervention.

How it works

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.

OAuth 2 (client credentials) authentication examples

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.

Related information

• Configuring OAuth 2 authentication (client credentials)

Introduction

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.

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 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.

The Steps

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:

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:

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?

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.

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.

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.