Authentication

Setting Up OAuth 2.0

For information about OAuth 2.0 types, please check out this article. We currently allow integration with one part, two part and refresh-able OAuth 2.0 exchanges. We default our template for Authorization Code grants (a two part OAuth exchange, with a refresh option).

Template:

{
  "type": "oauth",
  "version": "2.0",
  "base_site": "",
  "authorize_path": "",
  "access_token_path": "",
  "access_token_name": "access_token",
  "refresh_token_name": "refresh_token",
  "client_id": "",
  "client_secret": "",
  "appParams": {
    "one": {
      "response_type": "code",
      "state": true,
      "redirect_uri": "{server}/app/oauth/(YOUR APP)/authorize"
    },
   "two": {
     "grant_type": "authorization_code",
     "redirect_uri": "{server}/app/oauth/(YOUR APP)/authorize"
    },
    "refresh": {
      "grant_type": "refresh_token",
      "redirect_uri": "{server}/app/oauth/(YOUR APP)/authorize",
      "refresh_token_path": ""
    }
  }
}

Fields:

• “type”: “oauth” - must be set to ‘oauth’ for OAuth 2
• “version”: “2.0” - must be set to 2.0 for OAuth 2
• “base_site”: the base URL (may be omitted if the authorize_path, access_token_path, and refresh_token_path do not come from the same base_site)
• “authorize_path”: the URL (in addition to base_site) where users will be directed to give authorization
• “access_token_path”: the URL (in addition to base_site) where the access token will be obtained
• “access_token_name”: the key of the access token in the response
• “refresh_token_name”: the key of the refresh token in the response
• “client_id”: the client ID obtained from the application. Automatically appended to all steps of your authentication.
• “client_secret”: the client secret obtained from the application. Automatically appended to all steps of your authentication.
• “appParams”: an object representing the parameters you’ll be sending in each step of your OAuth exchange.
  • “one”: an object that contains the query parameters required for the first exchange of your authentication process. The parameters included in the template are common parameters, but not all applications use the same fields.
    • “state”: a boolean that if true will include an unguessable state value in the OAuth exchange
    • “redirect_uri”: the URL where users will be sent after authorization. Substitute the Connector’s unique filename (the one you created when you first saved your Connector) for (YOUR APP), but leave {server}- as our engine will make that swap for you at runtime.
    • “response_type”: This parameter is specific to Authorization Code Grant OAuth 2.0
  • “two”: an object that contains the parameters required for the second step of your authentication except for code, which is automatically passed to the second leg of the authentication exchange. The parameters included in the template are common parameters, but not all applications use the same fields.
    • “grant_type” : This parameter is specific to Authorization Code Grant type of OAuth 2.0
    • “redirect_uri”: the URL where users will be sent after authorization. Substitute the Connector’s unique filename (the one you created when you first saved your Connector) for (YOUR APP)
  • “refresh” (optional): an object that contains the parameters required to exchange a refresh token for a new access_token if the token expires.
    • “grant_type”: “refresh_token”
    • “redirect_uri”: Same redirect URL as before. Optional - dependent on the API.
    • “refresh_token_path”: The URL path / route for refreshing your access token. Required if the API has a unique route for the refresh token that is not the access_token_path route. See the ‘Addtional Support for Refresh URL’ section below for more info.

Example:

{
  "type": "oauth",
  "version": "2.0",
  "base_site": "https://slack.com",
  "authorize_path": "/oauth/authorize",
  "access_token_path": "/api/oauth.access",
  "access_token_name": "access_token",
  "refresh_token_name": "refresh_token",
  "client_id": "74297942.0982801055",
  "client_secret": "xy02840282fs280202z",
  "appParams": {
    "one": {
      "response_type": "code",
      "state": true,
      "scope": "read,chat:write",
      "redirect_uri": "{server}/app/oauth/slack_99/authorize"
    },
    "two": {
      "grant_type": "authorization_code",
      "redirect_uri": "{server}/app/oauth/slack_99/authorize"
    },
    "refresh": {
      "grant_type": "refresh_token",
      "refresh_token_path": "/api/oauth.access"
    }
  }
}

Addtional Oauth 2 Grant Types

While most connectors adhere to standard Oauth 2 authorization code grant flows there are applications that will require different grant types. The following Oauth 2 grant types are supported:

• Client Password
• Password Grant Type/Resource Owner

Client Password

This oauth grant type will add an authorization header during token exchange with the application being authenticated. The value will be constructed from the schema application client_id and client_secret. These two will be encoded as the value for the header.

Authorization: Basic RandomStringEncodedHere //base 64 encoded application credentials

To implement this type of oauth grant type add the “auth_header” field to the schema as follows:

"appParams": {
    ...
    "refresh": {
      "auth_header": "basic", //BASIC HEADER OAUTH EXCHANGE
    }

Password Grant Type/Resource Owner

The password grant type will simply prompt the user to enter their credentials (no pop up window with redirect url will be opened). This prompt will enable the user to directly enter their application credentials and an access token will be retrieved on their behalf.

To implement this type of oauth grant type use the grant_type field as follows:

"appParams": {
    "one": {
      ...
      "grant_type": "password", //PASSWORD GRANT TYPE
    }

Addtional Support for Refresh URL

Most connectors utilize the access_token_path as the URL to carry out the initial authentication process. Additionally this field is also used when refreshing the access token. However some connectors may require a specific URL for token refresh that is different from the initial oauth URL. To support a different URL for token refresh simply add the refresh_token_path field to the appParams.refresh object, as shown below:

"appParams": {
    ...
    "refresh": {
      "refresh_token_path": "/<REFRESH-PATH-HERE>",
      ...
    }

If you are using a base_site, then your refresh path will be a relative URL. If you are not using a base_site, then it will be an absolute URL.

Optional Fields:

•  ”authparams”: an object that contains the authentication parameters users will enter. Only include authparams in the OAuth object if you require users to enter additional data before you can run the OAuth exchange, such as an instance URL. Each parameter defined in this object can be referenced as {{auth.parameterName}} using Mustache throughout the rest of your connector JSON.
•  ”type”: can be ‘string’, ‘password’, or ‘option’. If type is ‘password,’ the input will be hidden as the user types it in. If the type is ‘option’, you will need to provide an array of objects called “choices”, where each item contains an “optionValue” and “displayName” field, for more information on ‘option’ types see Parameters.
• “displayname”: the name that will display above the authentication parameter in the UI

The access token and refresh token that results from the OAuth exchange can be referenced from inside each method and hashed into HTTP calls using the Mustache reference {{auth.access_token}} or {{auth.refresh_token}}.

OAuth 2.0 Redirect URL

Some applications require you to set acceptable callback or redirect URLs when you register your application. You must add these redirect URLs to your application to be able to run OAuth 2.0 from the connector builder and from the production environment:

{server}/app/oauth/(YOUR APP)/authorize

Substitute the Connector’s unique filename (the one you created when you first saved your Connector) for (YOUR APP).