Authenticating with OAuth 2.0 and Authorization Code Grant

This topic describes how to connect to a REST API that requires OAuth 2.0 authentication using the authorization code grant.

Before starting the configuration in GENESIS, you need to register the desired application on the REST API that you want to access. Learn more

The following procedure uses the Fitbit application page as an example. Fitbit is a company that produces wearable fitness trackers and smartwatches. Their REST API allows developers to access and interact with Fitbit's health and fitness data, enabling integration of the data into other applications and services. The following image shows the application page on Fitbit.

To connect to a REST API using OAuth 2.0 with the authorization code grant:

  1. Open Workbench and in Project Explorer, expand your project > Data Connectivity.

  2. Right-click Web Services and select Create a new Folder. Give the folder a name and click Apply.

    You can skip this step and use an existing folder, like the default Sample Web Services folder.

  3. In Project Explorer, right-click the desired folder and select Add REST Service. The REST service configuration dialog is displayed.
  4. Give the service a name and in the General Settings section in Base URL, enter the URL for the desired REST API. This information is typically available in the API documentation. Then click Apply.

  5. In Authentication, select OAuth 2.0.

  6. In the Connection Credentials section in Grant Type, select Authorization Code. The authentication options for authorization code are displayed.

  7. Configure the authentication options as needed. See the table for more information.

    Authentication Option

    Description

    Client Id

    The OAuth 2.0 Client ID that you received when you registered the application on the REST API.

    Client Secret

    The Client Secret code that you received when you registered the application on the REST API.

    Scope

    The desired scope of data that you want to access. You can typically enter multiple values separated by a space. This is an API-dependent parameter, and usually can be found in the API's documentation.

    Callback Url

    The URL that you entered in the Redirect URL field when you created the application on the REST API. For GENESIS integration, since the authentication is completed by Workbench (which is a desktop application), this must be a localhost URL (127.0.0.1), on a port that is free on the machine, with HTTP protocol. Enter the URL exactly as in the application registration, with no trailing or leading spaces, and with the same casing.

    Use State Parameter

    When selected, it adds a random state value to the authentication request for added security. For more information, refer to The Authorization Request.

    Authorize Token URL

    The URL on the REST API that is used to request a code that will be exchanged for an access token. This URL is usually contained in the API's documentation.

    Access Token URL

    The URL on the REST API that is used to obtain the access token. This URL is usually contained in the API's documentation.

    Access Token Request Type

    The way to pass the parameters to the REST API when requesting the access token. Select one of the following options.

    • Authorization Header: all parameters are passed as HTTP header values
    • POST Body: all parameters are passed in the request body as application/www-url-form-encoded values.

    This setting is API-dependent. Most APIs work with either value, but you can try Post Body in case that Authorization Header does not work.

    Add Extra Values

    When selected, it allows to add custom values to the request for the access token if the API requires them.

  8. When finished, click Authorize to start the authentication process. You may be requested to first log in with the authentication provider. Once that is done, a consent page may be displayed, indicating what kind of access is being requested by the application. Apply all the necessary permissions and click Allow.

    The browser window redirects to the configured local Redirect URL, displaying a confirmation message that the authentication is complete. A success message is displayed in Workbench.

    If the REST API sends back a set of scopes allowed for the current credentials that is different from the requested scopes, GENESIS updates the Scope field with the values received from the REST API.