Authentication

Refer to the documentation here for more information on authorization: here

Our goal is to unite all SaaS applications in the cloud to help run the world’s business processes. To do this, we must support SaaS applications used by businesses, and the first step to enabling a new connector is by handling authentication. This guide will outline the most popularly used authentication methods used by applications and how to use them in the connector building environment.

Authentication Steps

When you first enter the connector building environment you will be greeted with the settings page for an empty connector. The first step is to create a new connector, enter the authentication tab, and select your authentication type.

1. Enter the Connector Building Environment

1. Select New Connector

1. Select New Connector

1. Select Authentication

1. Select the authentication method used by your SaaS app

1. A skeleton JSON object is initialized for your authentication BLOB (auth blob)

1. Collect the required inputs and add them to the auth blob (e.g. consumer key and consumer secret)

Be sure to give your connector a name after creating a new connector. Note that best practice is to append your org id to the name of your test/production connector, e.g. salesforce_quickstart_3137. You can add a name to the connector by clicking the gear icon next to the connector and then editing the display name

Helpful Authentication tips

When working with the authentication portion of the connector keep these tips in mind. These tips relate specifically to OAuth 2.0 authentication: * The base_site field is pre-appended to a few of the other field in our auth blob: * authorize_path * access_token_path * refresh_path

This means that the true value of a field like {{authorization_path}} is actually equal to {{base_site}}{{authorization_path}}. * When any code reference in the connector uses auth.SOMETHING it is referring to the object called authparam Inside the auth blob:

This is evident in the connector template where we reference {{auth.env}} which is the value the user chose under authparam ⇨ env object.

• The redirect_uri field is the callback that the authentication server calls to pass the token to Azuqua.

Authentication Quick Start Reference

Each of the different supported authentication methods require a different set of inputs saved into the auth blob to successfully enable a connector. For this reason, Azuqua will identify the authentication method and provide necessary inputs via LastPass. The following is a table of required inputs to be sure to include for each auth type. Please refer to the salesforce_quickstart_3137 connector code provided in the /examples/ folder for an demonstration on using OAuth 2.0 fields properly.

Auth Requirement Look Up Table:

Auth Type	Required Input	Description
Basic	No requirements
Custom	Custom	Custom authentication allows you to define your own authentication parameters. Often, custom auth is used for key/secret authentication.
OAuth 1.0	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
	Redirect	the redirect URL; replace “{YOUR APP}” with the connector name provided in LastPass
optional	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
optional	type	can be ‘string’ or ‘password.’ If type is ‘password,’ the input will be hidden as the user types it in
optional	displayname	the name that will display above the authentication parameter in the UI
OAuth 2.0	base_site	the base URL (may be omitted if the authorize_path and access_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.
	appParams.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.
	appParams.one.state	a boolean that if true will include an unguessable state value in the OAuth exchange
	appParams.one.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 “FILENAME”, but leave “{server}”- as our engine will make that swap for you at runtime.
	appParams.one.response_type	This parameter is specific to Authorization Code Grant OAuth 2.0
	appParams.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.
	appParams.two.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 “FILENAME”
	appParams.two.grant_type	This parameter is specific to Authorization Code Grant type of OAuth 2.0
optional	appParams.refresh	an object that contains the parameters required to exchange a refresh token for a new auth_token if the token expires
Key/Secret	Custom	This is the same as custom auth, except that it includes a commonly used template