OAuth 2.0 Configuration

This article covers the use of OAuth 2.0 authentication with the Web API plugin, and explains the process of configuring the client details and authorization using the available grant types.

What is OAuth 2.0?

OAuth 2.0 is a standard designed to allow a website or application to access resources hosted by other web apps on behalf of a user. This is achieved through using "grant types" (otherwise known as "flows") to exchange and authorize credentials between applications.

The Web API plugin supports the Authorization Code, Client Credentials and Password grant types when using the OAuth 2.0 authentication option. Depending on the grant type you use, the information you must enter varies slightly.

Third-party authentication servers

For access to a web API to be authorized using OAuth 2.0, a third-party authentication server is required to issue access tokens which allow that API to be used by specified set users. This is achieved by creating an "Application" (otherwise known as a "Client Application" or "Client"), maintaining a set of users and providing a means for those users to authenticate (sign in).

There are many different third-party authentication servers available and, while they all adhere to the same OAuth 2.0 standard, many details are left to the discretion of a given server. Therefore, the configuration experience can differ depending on the authentication server used.

Configuring the Web API plugin

This section describes the fields used to configure the Web API plugin when you select anAuthentication of OAuth 2 in the Configure data source window.

Fields / options for all grant-types

The following client details must be completed regardless of the Grant Type you select.

Token URL

The Token URL value that you must enter is specific to the particular third-party authentication server you are using. You must therefore refer to the documentation of your chosen authentication server to determine this value.

It is normal for this URL to be on a different host to the actual Web API (Base URL) being used .

Client ID / Client Secret

After setting up your Client Application, you should have access to your Client ID and Client Secret values.

Authorization Scope

The Authorization Scope values you enter are specific to the particular third-party authentication server you are using, and describe the permissions you require.

For example, if you are using the Web API plugin to access the https://www.googleapis.com/ API and you wish to use the drive/v3/files endpoint, youmust enter an authorization scope https://www.googleapis.com/auth/drive.readonly. If you require more than one scope, you add them all here separated by spaces.

How to send credentials to the Token URL

Use this field to select the method in which the client credentials are sent to the Token URL. Choose from:

Authentication servers can differ in how they expect these credentials to be sent. Refer to your third-party authentication server documentation for this information.

  • Query string: The credentials are sent as part of the request string.

  • Body: The credentials are sent in the body of the request.

  • Header: The credentials are sent in the header of the request.

Fields / options for specific grant types

The Web API plugin supports the Authorization Code, Client Credentials and Password grant types . Depending on the grant type you use, the information you must enter varies slightly.

Authorization Code

If selected, you must enter a Authorization URL; refer to your third-party authentication server documentation for this information. The Authorization URL is the URL of the web page you are directed to that allows you to log in. Often, this URL may take query arguments to tailor its behavior. These can be pasted into the URL field or, if more convenient, may be added by clicking the Add new argument button under the Additional arguments for the Authorization URLheading.

After filling in the Authorization URL field and clicking the Sign in button, the user may log in and tell the authentication server that they consent to the Web API plugin having access to the requested authentication scopes. When they return to the Cloud product, the sign in button should show that they are now logged in (or show an error if something went wrong).

Client Credentials

If selected, no additional information is required.

Password

If selected, you must then enter a Username and Password.

 


Have more questions or facing an issue?