What is OAuth2?

OAuth 2.0, short for Open Authorization, is an access standard that allows a website or application to access resources hosted by other web applications on behalf of a user. It replaced OAuth 1.0 in 2012 and is now the de facto industry standard for online authorization. We will not go into a detailed description of the OAuth process here. More information can be found on the official site: https://oauth.net.

The following process applies here: If the corresponding channel with active OAuth configuration is stored in a profile, the validity of the token in the channel is checked before the cronjob is started, and it is renewed automatically if necessary.

Prior to the initial setup

Before you start the setup, check the following points:

• Is it an official OAuth2 connection? Some web services and APIs talk about OAuth, but do not adhere to the official standard (RFC). If the response differs from the standard, it cannot be interpreted and the token cannot be extracted. Have a look at section How to Use a Generic Bearer Token below in that case.

• Is the endpoint accessible, or do firewalls/ports need to be enabled?

• Are all required login credentials available?

Where to find the Oauth2 configuration?

To do this, switch to the channel overview (Administration → Partners → Channels) and create a new HTTP(S) channel. In addition to simple authentication methods such as Basic/Digest, OAuth can also be set up and tested there.

In the Own ID tab you will find the OAuth section.

How do I configure OAuth2? (Quickstart/Wizard)

1. To perform an initial connection test, click the Configure OAuth2.0... button.

2. Select the grant type you need.

3. Enter all necessary credentials (Client ID, Client Secret, etc).

4. Enter the endpoint URL. You can usually find this in your application or the documentation for the API.

   1. For grant type authorization code, the (O)Auth URL must also be provided. This usually ends with .../authorize
      In addition, a callback URL/redirect URL is required, which is automatically filled.

5. Click Fetch Access Token to get an access token.

   1. For Grant Type Authorization Code, additional login/authorization via browser is required.

If the window closes automatically, the token was successfully extracted! Open the channel again, to see the expiration date of the token:

If no token could be found in the response, a pop-up window with error log appears. The log can be very informative, depending on the OAuth implementation of the web service,

In case of problems, please take a look at the error message in the log, alternatively contact our support.

Automatic token refresh

If the token was successfully fetched via Configure OAuth2.0... it can automatically be refreshed.

For this purpose, the OAuth2 Refresh URL field in the channel has to be adjusted. The Refresh URL must contain all information from the wizard! The following templates can be inserted via the small button %.

Additional parameters, depending on whether the checkboxes were set in the wizard:

Note: From version 4.6.11 the OAuth2 Refresh URL is generated automatically!

Important: The endpoint https://<server>/oauth/token, i.e. everything up to the "?", must be adjusted manually. This corresponds to the Endpoint URL in the wizard. Parameters like scope can also differ.

If a DMZ is used: If a DMZ is used, the redirect URL must be entered in configuration file ./etc/forward.properties of the DMZ server for grant type Authorization Code! See section Inwards forwarding for HTTP(S) requests.

Custom OAuth2

As described before, it is possible that there is no official implementation on the server side, but the server still returns a response including token and validity. For this, you can use the Generic Bearer Token option. This is available as of version 4.6.5.