Skip to main content

Set up an OAuth 2.0 HTTP connection

Stephen Brandt
  • Updated

OAuth 2.0 documentation: Framework, Standard

OAuth 2.0 is an increasingly common server API authorization protocol. In fact, many built-in integrator.io connections already gain access via OAuth 2.0, and it has become required or preferred by providers like Google, eBay, and Microsoft.

You can select this option to connect to any OAuth 2.0-compliant app that does not have a standard integrator.io connection, or you can build your own OAuth 2.0 connection for a supported app and exercise finer control over each setting, as described below:

Contents

A. Set up an HTTP connection

Start establishing the universal, or generic, OAuth 2.0 connection in either of the following ways:

  • Select Connections from the Resources menu.

    Next, click + Create connection at the top right. In the resulting Create source panel, select HTTP from the Application list, under the Universal connectors group.

  • While working in a new or existing integration, you can add an application to a flow simply by clicking Add source or Add destination/lookup. From the Application list, under Universal connectors, select HTTP.

  • After the HTTP Application is added, click the Connection setting’s + button to proceed.

B. Provide general HTTP connection settings

Name (required): Provide a clear and distinguishable name. Throughout integrator.io imports and exports, you will have the option to choose this new connection, and a unique identifier will prove helpful later when selecting among a list of connections that you’ve created.

Application (required, non-editable): A reminder of the app you’re editing. 

Mode (required): Select one of the following options:

  • Cloud to connect to a publicly accessible server application
  • On-premise to connect to a server that is publicly inaccessible and has integrator.io agent installed on it

Agent (required, if On-premise selected for Mode; otherwise not displayed): Select an agent from the list. To connect to an on-premise application, integrator.io requires that an agent be installed on a networked computer. An agent is a small application that allows you to connect to data behind your firewall. When installing an agent, you will specify a unique access token, which then populates the Agent drop-down list. The installed agents connect to integrator.io and establish a reverse SSH tunnel, allowing secure communication without the need to whitelist integrator.io IP addresses in your firewall settings. A single agent can be used by multiple different connections.

C. Edit OAuth 2.0 settings

Continuing in the Create connection pane, select OAuth 2.0 for the Authentication type. The settings then become specific to OAuth 2.0:

As with all API connections, the parameters are unique to the vendor’s conventions. Before proceeding, review the developer documentation and your account settings.

Grant type (required): You can use the Authorization code to get an access token for web and native apps after you authorize the app, or Client credentials for apps to request an access token on their own behalf.

  • Authorization code – the provided code is obtained by using an authorization server as an intermediary between the client, integrator.io, and resource owner. Selecting Authorization code enables additional required and informational fields.
  • Client credentials – limits the authorization scope to the protected resources under control of the client, or to protected resources previously arranged with the authorization server.

Callback URL (not editable): Click the copy icon (  ) to be able to provide the integrator.io callback URL to your app.

Authentication URL (required): Enter the endpoint for the API provider’s authorization server where the authorization code is retrieved.

Scopes (optional): If applicable, provide a list of the scopes of access being requested from the authorization server. By default, a space character delimits multiple scopes.

Custom scope delimiter (optional checkbox and delimiter): If you are requesting access to more than one scope and the authorization server expects the list to be delimited by a space character, leave the box This provider uses a scope delimiter other than space unchecked. Otherwise, check this box, and enter a custom delimiter below.

iClient (required): Select the iClient pair that stores the client ID and client secret provided to you by your app. To add an iClient and configure your credentials, click the plus (+) button. Click the edit ( ) button to modify a selected iClient. Be sure to give the iClient a recognizable name for use in any other connections.

Access token URL (required): Enter the URL to the endpoint where an authorization code for an access token can be exchanged. In most cases, this URL is also on the authentication server itself.

Client authentication (optional): Select one of the following options to configure the location where client credentials should be sent at the server:

  • Send as basic auth header
  • Send client credentials in the body

Access token headers (optional): Enter a name and a value to replace default header values with custom values. In rare cases, it may be necessary to include custom HTTP headers with your API requests. The default content-type header value is application/x-www-form-urlencoded. 

Access token body (optional): Configure your own access token body in JSON format if it is different from the default access token body. This JSON format is finally converted to the form-urlencoded format on the wire. 

  • Default access token format if Client authentication set to Send client credentials in the body:
    { code: {{{query.code}}}, redirect_uri: {{{redirectUri}}}, client_id: {{{clientId}}}, client_secret: {{{clientSecret}}}, grant_type: "authorization_code"}
  • Default access token format if Client authentication set to Send as basic auth header:
    { client_id: {{{clientId}}}, client_secret: {{{clientSecret}}} grant_type: "client_credentials" }

Refresh token headers (optional, enabled when Authorization code selected): In some cases, it may be necessary to include custom HTTP headers with your token refresh requests. Any value from the connection can be referenced using {{{placeholders}}} with a complete path matching the connection field.

Refresh token body (optional, enabled when Authorization code selected): Configure your own refresh token body in JSON format if it is different from the default refresh token body. This JSON format is finally converted to the form-urlencoded format on the wire. 

  • Default refresh token body format:
    {
      client_id: {{{clientId}}}, 
      client_secret: {{{clientSecret}}}, 
      "grant_type": "client_credentials", 
      "refresh_token": "{{{connection.http.auth.token.refreshToken}}}" 
    }

Revoke token URL (optional): Enter a URL where integrator.io will make an HTTP post request to revoke a particular token.

Revoke token headers (optional): In some cases, you may need to include custom HTTP headers with your API requests. The default content-type header value is application/x-www-form-urlencoded, and the authorization header value is basic.

Revoke token body (optional): Configure your own revoke body in JSON format if it is different from the default revoke token body. This JSON format is finally converted to the form-urlencoded format on the wire.

  • Default revoke body format:
    { token: {{{connection.http.auth.token.token}}} }

Location (required): Specify where your API expects to find the authentication token:

  • Body – If your API requires the token to be embedded in the body structure of your HTTP request, place the token in your body template using the placeholder {connection.http.token.token}
  • Header – Specify the header name and authentication scheme to use when constructing the HTTP request
  • URL parameter – If the authentication token is located in the URL, you can specify the query string parameter name that holds the token value.

Header name (optional): By default, integrator.io sends all authentication type info in the authorization HTTP header field. If the API you are connecting to requires a different HTTP header, use this setting to provide an override.

Scheme (required): By default, integrator.io follows the HTTP specs for authentication scheme names (for example: Bearer, OAuth, MAC). If the API you are connecting to doesn't follow the specs exactly, use this field to provide an override. 

D. Edit common HTTP settings

Additional HTTP settings are found in the other sections in the Create connection pane (optional sections are collapsed by default):

  • Application details
  • Nonstandard API rate limiter
  • How to test connection?
  • Advanced

For complete documentation of these settings, see Fundamentals of HTTP connections.

E. Save, test, and authorize

Once you have configured the OAuth 2.0 HTTP connection, you have a few options for continuing:

  • Save & authorize – click this button to test the connection, commit the new connection so that it will be available to all integrations for your account (and applied to the current source or destination app, if you created it within a flow)
  • Cancel – click this link to exit connection creation without saving
  • Test connection – click this button to verify that your new connection is free of errors

When you request Save & authorize, a new browser window opens to ask you to grant access to integrator.io for the specified scopes. If you allow the request, the refresh token is stored within this connection.

See also

Related articles

Comments

0 comments

Please sign in to leave a comment.