While building a Flow, users can connect an account to a connector, set up their Flow, and then let it run. Azuqua handles all the hard work of authentication, and securely stores any pertinent authentication information (like credentials, API keys, or access keys obtained from an OAuth exchange) so it can be used whenever the Flow runs.

Azuqua supports 4 kinds of authentication: Basic, OAuth 1.0, OAuth 2.0, and Custom (often used for Key/Secret). In Custom authentication, you also may choose to define an authentication object that takes in custom parameters that you can then send over as part of your request to the API.

To set up authentication, go the Authentication section on the sidebar, and select the authentication type your API requires. Each form has slight variations, but all authentication types come in the basic form:

{
    "type": "",
    "authparams": {
        "<parameterName>": {
            "type": "",
            "displayname": ""
        }
    }
}

Fields:

  • “type”: The type of authentication (will be automatically populated)
  • “authparams”: The set of parameters you would like to show up in the authentication visual elements of your Connector.
  • “<parameterName>“: An individual authentication parameter that will be on your Connector. This name will not be surfaced onto the Connector itself, but will be the key you use to refer to the value throughout your methods. You may have as many of these as you need. Make sure to not include the “<” characters in your parameter name.
  • “type”: The type of this parameter. Can be string, or password (hides the inputted value on the UI)
  • “displayName”: The name that will be shown to the user on your Connector while they are building a Flow

Although Azuqua will handle the storage of authentication information, many APIs require you to use this authentication information to sign requests. To do this, all authentication parameters can be referred to in other methods using Mustache, in the form: “{{auth.parameterName}}”.

Setting Up Basic Authentication

Use basic authentication when all you need to grant access to the API is a username and password, sent over in the headers or body of the request.

Template:

{
    "type": "basic",
    "authparams": {
        "username": {
            "type": "string",
            "displayname": "Username"
        },
        "password": {
            "type": "password",
            "displayname": "Password"
        }
    }
}

Fields:

  • “type”: must be set to ‘basic’ for basic authentication
  • “authparams”: an object that contains the authentication parameters users will enter. For Basic auth, these are usually “username” and “password”
  • “type”: can be ‘string’ or ‘password.’ If type is ‘password,’ the input will be hidden as the user types it in
  • “displayname”: the name that will display above the authentication parameter in the UI

Example:

{
    "type": "basic",
    "authparams": {
        "username": {
            "type": "string",
            "displayname": "Username"
        },
        "password": {
            "type": "password",
            "displayname": "Password"
        },
        "instance_url": {
            "type": "string",
            "displayname": "Instance URL (w/o https)"
        }
    }
}

Later on, you can reference these parameters using the Mustache templates {{auth.username}} and {{auth.password}}.

Setting Up OAuth 1.0

Template:

{
    "type": "oauth",
    "version": "1.0",
    "request_url": "",
    "access_url": "",
    "consumer_key": "",
    "consumer_secret": "",
    "callback": "{server}/app/oauth/(YOUR APP)/authorize",
    "signature_method": "HMAC-SHA1",
    "nonce_size": null,
    "redirect": ""
}

Fields:

  • “type”: must be set to ‘oauth’
  • “version”: must be set to 1.0 for OAuth 1
  • “request_url”: the external URL where the token request will be made
  • “access_url”: the external URL where the request token will be exchanged for the access token
  • “consumer_key”: the access key obtained from the application
  • “consumer_secret”: the access secret obtained from the application
  • “callback”: the callback URL. Substitute the Connector’s unique filename (the one you created when you first saved your Connector) for “(YOUR APP)”
  • “signature_method”: must be ‘HMAC-SHA1’
  • “nonce_size”: must be null
  • “redirect”: the redirect URL (may also be called the authorize 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.(parameter key)}} using Mustache.
  • “type“: can be ‘string’ or ‘password.’ If type is ‘password,’ the input will be hidden as the user types it in
  • “displayname”: the name that will display above the authentication parameter in the UI

The access token that results from the OAuth exchange can be referenced from inside each method and hashed into HTTP calls using the Mustache template {{auth.access_token}}. After you have set up your authentication, all requests to the API will be automatically signed for you according to OAuth 1.0 protocol.

OAuth 2.0 Redirect URL

Some applications require you to set acceptable callback or redirect URLs when you register your application. You must add this redirect URL to your application to be able to run OAuth 1.0 from the Connector Builder, Beta Environment, and Production Environment:

https://api.azuqua.com/app/oauth/(YOUR APP)/callback

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

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

Setting Up Custom Authentication

Custom authentication allows you to define your own authentication parameters. Often, custom auth is used for key/secret authentication.

Template:

{
    "type": "custom",
    "authparams": {
        "parameterName": {
            "type": "string",
            "displayname": ""
        }
    }
}

Fields:

  • “type”: must be set to “custom” for custom authentication
  •  ”authparams”: an object that contains the authentication parameters users will enter. For custom auth, you can define any authparams as you like
  • “parameterName” : Replace this with the name of the parameter you’d like to add.
    • “type”: can be ‘string’ or ‘password.’ If type is ‘password,’ the input will be hidden as the user types it in
    • “displayname”: the name that will display above the authentication parameter in the UI

Example:

{
    "type": "custom",
    "authparams": {
        "apikey": {
            "type": "string",
            "displayname": "Username"
        },
        "secret": {
            "type": "password",
            "displayname": "Password"
        }
    }
}

No matter how you define your authentication schema, you’ll be able to reference your authentication parameters later on using Mustache in the form: “{{auth.parameterName}}”