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:

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:

Name	Default value	Notes
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?

Shopware example

If we check the Shopware API documentation, it's clear that some additional variables are needed for authentication. (1) We need to pass username and password values into the request body, together with client_id, grant_type, and scopes:

So, username and password keys must be added as authentication variables (in order that users can provide these details when adding a connector instance) AND as body parameters (so values provided by users get passed in the request body). (2) This API is looking for a scopes variable for authentication rather than our default scope key. We can take care of this when we reach setup for the request body, later in this task, using the existing scope key.

(3) Looking further into the API documentation, we find that the base URL for all requests requires a shop URL:

So, we need to add an authentication variable to capture a url value.

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.

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:

Shopware example

Shopware API documentation provides the authentication endpoint, to be added to the base URL:

So, we'd add it as follows (incorporating the url connector variable that we identified in step 7):

https://{{url}}/api/oauth/token

For example:

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.

Shopware example

From previous steps, we already know that some authentication variables are needed in the request body:

So, these would be added here:

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.