Skip to main content

OAuth 2.0 Configuration

Documentation Team
  • Updated

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.

When populating the Authorization Scope field, you must often specify a specific authorization scope to indicate that the API usage will take place over time, after the user has logged out of the authentication server. This is called "offline" access and triggers the authentication to provide a "refresh token". Refresh tokens allow the Web API plugin to obtain a new access token from the authentication server in the background, whenever the current access token expires.

The Web API plugin requires offline access to be requested, which requires the correct scope to be entered, dependent on the authentication server being used:

  • Atlassian: Request the offline_access scope.

  • Google APIs: Offline access isn't requested via a scope at all. Instead, you must add the access_type = offline and include_granted_scopes = true query arguments to the Authorization URL.

Authorization scope can also be used to request that the user's identity (email address) be made available to the Web API plugin. For example, requesting the scope user:email from GitHub allows the Web API plugin to know who's logged in. This is used only to show the logged-in user's email in the Sign-in button, but it can be very useful.

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

If the authentication server fails to return a refresh token value for Authorization Code flow, the following error displays after returning from the authentication server web page: Token URL failed to return refresh_token; ensure you request offline access in your authorization request.

Client Credentials

If selected, no additional information is required.

Password

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

 

Comments

0 comments

Please sign in to leave a comment.