How to create authentication for triggers and actions using Connection Builder

The authentication module performs necessary validation to allow only authorized users access their third-party accounts. You can add authentication to your custom triggers and actions through Connector Builder.
Once you have created a trigger/action in Connector Builder, you can create an authentication for same using the ‘flow auth’ command in Connector Builder. On executing this command, you will be prompted to select an authentication method you want to use.

auth-list.png

The Connector Builder supports four types of authentication methods listed below:

1. Basic authentication
2. API Key authentication
3. OAuth authentication
4. Custom authentication

When the user selects an authentication method, an ‘authentication.js’ file is automatically created in the app directory. You can then add the authentication logic to this ‘authentication.js’ file.
Note: If you choose to create a custom OAuth authentication module, an additional ‘oauth.json’ file will be created in the app directory. You will need to add your authentication logic in this ‘oauth.json’ file.

1-auth.js.png

You can then add the authentication logic to this ‘authentication.js’ file.

We will now understand the authentication methods in detail.

1. Basic authentication

If your action/trigger only needs two pieces of information from the user, i.e., ‘Email ID’ and ‘Password’, you can use the basic authentication method.


Basic authentication structure

module.exports = 
{
  label : 'Connect to Demo',    
  mock_input: {
    "username" : "myuser",
"password" : "mypassword"
},
  validate : function (input, output)
  {
    // auth data will be available in input.auth
    // var username = input.auth.username
    // var password = input.auth.password
    // make call to third party api to validate user credentials
    // and return callback output(null, true) in case of successful validation
    // or return callback output(‘error message’) in case of unsuccessful validation
  }
}

Let’s understand more about this structure with the help of an example.


Example


Suppose, you want to create an authentication for the ‘Github’ action/trigger. Since Github requires only ‘Username’ and ‘Password’ to authenticate a user, we will create this authentication using the ‘Basic authentication’ method.

label: Provide a display label for the authentication field to be added in the trigger/action input form.

1-label.png

The structure for basic authentication includes two main blocks:
1. mock_input: Lets you add sample input data which can be used to test your authentication.
2. validate: Lets you add validation logic for the input provided by the user.


1. mock_input

This block includes a sample input data which can be used to test the authentication module before deploying it.

Convention for mock_input block

 mock_input: {
    "username" : "myuser",
"password" : "mypassword"
},

2-mock_input.png

2. validate

This block contains the validation logic for the auth inputs provided by the user in the trigger/action form and is called at the time of authentication creation. If any errors are encountered, an error will be displayed to the user and authentication will not be created.

Convention for validate block

 validate : function (input, output)
  {
    // auth data will be available in input.auth
    // var username = input.auth.username
    // var password = input.auth.password
  }
}

The input.auth key contains the details of your auth data. Using it, you can add validation logic in the validate block, as shown in the image below:

3-validate.png

2. API Key

If your action/trigger requires an API Key to authenticate the user, you can use the API Key authentication method. User can pass the API Key either as a query string parameter or via an HTTP header.

API key authentication structure
 

module.exports = 
{
  label:  'Connect to Demo',  
  mock_input: {
"api_key" : "my api key"  
  },
  input: {},
  validate: function (input, output)
  {
    // this function will be executed when running unit test cases and authData will 
    // be available in input.auth
  }
}

Let’s understand more about this structure with the help of an example.


Example


Suppose you want to create an API Key authentication for a particular service. 

label: Enter the display label for the authentication field.

1.png

It has three main input blocks:

1. mock_input: Lets you add sample input data which can be used to test your authentication.
2. input: Lets you define input fields for authentication window.
3. validate: Lets you add validation logic for the input provided by the user.


1. mock_input

This block includes a sample input data which can be used to test the authentication module before deploying it.

Convention for mock_input block
 

mock_input: 
  {
    "Api_key" : "my api key"  
  },

2-mock-input.png


2. input

This block includes the definition for the input fields of authentication window.

Convention for input block
 

input:
 {
   type: 'object',
   title: 'API Key',
   description: "Enter API key",
   properties:
   {
     //input field definition
   }
},

1. type (required): This key is used internally. The value for this key should always be set to 'object' and should not be changed.

2. title (required): Provide a title for the object.

3. description: Enter a short description about the trigger.

4. properties: The ‘properties’ object is used to define the fields of your authentication window, as given below:

4.1 Defining authentication input fields
  To define a authentication input field, you will need to create an object for the input field with the following keys:
 
    - type (mandatory): The type of the input field. Supported input field types are: ‘String’, ‘Object’, ‘Array’, ‘Boolean’, and ‘Any’.
    - title (mandatory): The display name for the input field.
    - minLength (optional): Used to mark the input field as mandatory. The value for this field should always be set to ‘1’.
    - propertyOrder (optional): Used to specify the sequence of the input field in the authentication window.

4-input.png


3. validate

This block contains the validation logic for the inputs provided by the user in the authentication field and is called at the time of authentication creation. If any errors are encountered, an error will be displayed to the user and authentication will not be created.

Convention for validate block
 

 validate: function (input, output)
  {
    // this function will be executed when running unit test cases and authData will 
    // be available in input.auth
  }
}

The input.auth key contains the details of your auth data. Using it, you can add validation logic in the validate block, as shown below:

3-validate.png

3. OAuth authentication

OAuth is a token-based authentication method that allows the user’s account information to be used by any external service, and subsequently provide secure access, without exposing the password. For example, many websites offer login multiple methods. One of the login methods you commonly see is ‘Login via Gmail’ or ‘Login via Facebook’. This is an example of OAuth.

There are two ways to create OAuth authentications:

  1. 1. Using built-in OAuth authentication modules provided by Built.io Flow
  2. 2. Creating custom OAuth authentication modules


1. Using built-in OAuth authentication modules


Built.io Flow provides built-in OAuth authentication modules for a number of services. You can find the the list here.

To use these built-in OAuth authentication modules to create authentications, follow the steps given below:

Step 1: Execute ‘flow auth’ command in connector builder, and select ‘oauth > built-in’ option. You can see the list of services for which Built.io Flow provides built-in OAuth authentication modules.

7-built-in-list.png

Step 2: Select the service for which you want to create OAuth authentication. 

This will create a ‘authentication.js’ file in your app directory, in which you can add your authentication logic. The basic OAuth authentication structure is given below: 

OAuth authentication structure
 

module.exports = {
  label : 'Connect to Twitter',    
  mock_input: 
   { 
     access_token: 'token' 
   }, //can be obtained from https://flowoauth.built.io
  oauth: 'dropbox',
  input: {},
  validate : function (input, output)
  {
    // auth data will be available in input.auth
    // var accessToken = input.auth.access_token;
  }
}

Let’s understand more about this structure with the help of an example.


Example


Suppose you want to create an OAuth authentication for ‘Gmail’ service. 

label: Provide a display label for the authentication field to be added in the trigger/action input form.

1-label.png

oauth: The ‘oauth_label’ of the service. Click here to find the list of ‘oauth_label’ for services supported by Built.io Flow.

2-oauth_label.png

The structure for OAuth authentication includes three main blocks:


1. mock_input

This block includes a sample input data which can be used to test the OAuth authentication module before deploying it.

Convention for mock_input block
 

mock_input: 
   { 
     access_token: 'token' 
   }, 
//can be obtained from https://flowoauth.built.io

Click here to obtain the access token associated with a particular service.

3-input_data.png


3. validate

This block contains the validation logic for the inputs provided by the user in the authentication field and is called at the time of authentication creation. If any errors are encountered, an error will be displayed to the user and authentication will not be created.

Convention for validate block
 

 validate : function (input, output)
{
    // auth data will be available in input.auth
}

The input.auth key contains the details of your auth data. Using it, you can add validation logic in the validate block.

4-access.auth.png


2.  Creating custom OAuth authentication modules


Built.io Flow allows you to create custom OAuth authentication modules for any external service. To do this, follow the steps given below:

Step 1: Execute the ‘flow auth’ command in Connector Builder, and select ‘oauth > create new’ option. 

1. oauth-options.png

Step 2: You can see two options: ‘OAuth 1’ and ‘OAuth 2’. Select the OAuth type for which you want to create an authentication.

3. oauth 2.png

Step 3: Provide a name for your custom OAuth authentication module. 

4. oauth name.png

Once you have provided these details, a file named ‘oauth.json’ will be created in your app directory. You can then populate relevant values for the keys present in this file.

5. oauth notification.png

Note: You don’t need to make any modifications to the ‘authentication.js’ file for custom OAuth authentications.

The structure for ‘OAuth1’ authentication module is given below: 

  "type": "oauth1",
  "title": "twitter",
  "consumerKey": "<CONSUMER KEY>",
  "consumerSecret": "<CONSUMER SECRET>",
  "signatureMethod": "HMAC-SHA1",
  "requestURL": "<REQUEST URL>",
  "authURL": "<AUTH URL>",
  "accessURL": "<ACCESS TOKEN URL>",
  "validate": {
    "url": "ANY API URL TO VALIDATE TOKEN OF THIRD PARTY SERVICE",
    "headers": {
      //<optional>
    },
    "query": {
      //<optional>"oauth_token": "{oauth_token}",
      "oauth_token_secret": "{oauth_token_secret}"
    }
  },
  "redirectURL": "https://flowoauth.built.io/oauth/twitter_hjcxop8fz/cli/return"
}

Let’s understand more about this structure with the help of an example.

Example
Let’s say you want to create a custom OAuth authentication for ‘Twitter’ that supports ‘OAuth1’ protocol. 

type: The type of the OAuth being used.
title: Provide a display label for the authentication field to be added in the trigger/action input form.
consumerKey: Provide a consumer key.
consumerSecret: Provide a consumer secret key.
signatureMethod: Provide the signature method to be used. By default, the value for this key is set to ‘HMAC-SHA1’
requestURL: Provide the service API URL for creating a new access token
authURL: Provide the URL to authenticate the access token
accessURL: Provide the OAuth API endpoint to get the access token

12-first blovk.png

validate: 
This block includes the details required to check the validity of the access token. 

Convention for validate block 

"validate": {
    "url": "ANY API URL TO VALIDATE TOKEN OF THIRD PARTY SERVICE",
    "headers": {
      //<optional>
    },
     "query": {
      //<optional>"oauth_token": "{oauth_token}",
      "oauth_token_secret": "{oauth_token_secret}"
    }

url: Enter the endpoint to validate the access token. 
headers: Pass the data required to validate the access token as key-value pairs in headers.
query: Set the query parameters to validate the access token.

You must provide values for either ‘header’ block or ‘query’ block.

13-validate.png

redirectURL: This block contains the redirect URL to be registered with your OAuth application.

15-redirect.png

The structure for ‘OAuth2’ authentication module is given below: 

{
  "type": "oauth2",
  "title": "twitter",
  "clientId": "<CLIENT ID>",
  "clientSecret": "<CLIENT SECRET>",
  "authURL": "<AUTHORIZATION URL>",
  "tokenURL": "<ACCESS TOKEN URL>",
  "refreshURL": "<REFRESH TOKEN URL, DEFAULT TO tokenURL>",
  //<optional>
  "scope": {
    //<optional>"READABLE SCOPE TITLE": "SCOPE"
  },
  "validate": {
    "url": "ANY API URL TO VALIDATE TOKEN OF THIRD PARTY SERVICE",
    "headers": {
      //<optional>"Authorization": "Bearer {access_token}"
    },
    "query": {
      //<optional>
    }
  },
  "redirectURL": "https://flowoauth.built.io/oauth/twitter_ryfudvifm/cli/return"
}

Let’s understand more about this structure with the help of an example.

Example
Let’s assume that you want to create a custom OAuth authentication for ‘Github’ service with ‘OAuth2’.

  type: Type of OAuth being used
  title: Provide a display label for the authentication field to be added in the trigger/action input form.
  clientId: Provide the client ID
  clientSecret: Provide the client secret
  authURL: Provide the URL to authenticate the access token
  tokenURL: Provide the OAuth API endpoint to get the access token
  refreshURL: Provide the refresh URL to refresh your expired access token

16-block1.png

scope: This block includes the scope name and the display label associated with it.

Convention for scope block
 

 "scope": {
    //<optional>"READABLE SCOPE TITLE": "SCOPE"
  },

17-scope.png

validate: This block includes the details required to check the validity of the access token. 

Convention for validate block:
 

 "validate": {
    "url": "ANY API URL TO VALIDATE TOKEN OF THIRD PARTY SERVICE",
    "headers": {
      //<optional>"Authorization": "Bearer {access_token}"
    },
    "query": {
      //<optional>
    }
  },

18-validate 2.png

redirectURL: This block contains the redirect URL to be registered with your OAuth application.

19-redirect 2.png


Deploying the custom OAuth


Once you have created a custom OAuth, you need to deploy it on Connector Builder in order to start using it in your triggers and actions.

To deploy your custom OAuth, execute ‘flow oauth deploy’ command in Connector Builder. 

20-github-oauth-deploy.png

This will add your custom OAuth in the the ‘Authorization’ fields of all Github actions and triggers.

Updating the Custom OAuth

In case you want to make any changes in the custom OAuth of any service, you need to update the relevant details in the ‘oauth.json’ file for that custom OAuth and redeploy it using ‘flow oauth deploy’ command in the Connector Builder.

4. Custom authentication

If your action/trigger requires some extra details such as, access token, client ID, client secret from the user along with the account credentials, you can use the custom authentication method. 

Custom authentication structure
 

 module.exports = 
{
  label : 'Connect to Test',    
  mock_input: {
     "username" : "myuser",
    "apikey" : "my api key",
    "pass" : "my password"
 },
  input: 
  { 
    type: "object", 
    properties: 
    {
      //input field definition
    } 
  },
  validate : function (input, output)
  {
    // auth data will be available in input.auth
    // var username = input.auth.username
    // var password = input.auth.pass
   // var apiKey = input.auth.apikey
  }
}

Let’s understand more about this structure with the help of an example.

Example

Suppose you want to create an Custom authentication for a particular service. 

label: Enter the display label for the authentication field.

1-label.png

It has three main input blocks:

1. mock_input: Lets you add sample input data which can be used to test your authentication.
2. input: Lets you define input fields for authentication window.
3. validate: Lets you add validation logic for the input provided by the user.

1. mock_input

This block includes a sample input data which can be used to test the authentication module before deploying it.

Convention for mock_input block
 

 mock_input: 
{
    "username" : "myuser",
    "apikey" : "my api key",
    "pass" : "my password"
 },

2-mock_input.png


2. input

This block includes the definition for the input fields of authentication window.

Convention for input block
 

 input:
 {
   type: 'object',
   properties:
   {
     //input field definition
   }
},

1. type (required): This key is used internally. The value for this key should always be set to 'object' and should not be changed.

2. properties: The ‘properties’ object is used to define the fields of your authentication window, as given below:

2.1 Defining authentication input fields
  To define a authentication input field, you will need to create an object for the input field with the following keys:
 
    - type (mandatory): The type of the input field. Supported input field types are: ‘String’, ‘Object’, ‘Array’, ‘Boolean’, and ‘Any’.
    - title (mandatory): The display name for the input field.
    - minLength (optional): Used to mark the input field as mandatory. The value for this field should always be set to ‘1’.
    - propertyOrder (optional): Used to specify the sequence of the input field in the authentication window.

3-input.png


3. validate

This block contains the validation logic for the inputs provided by the user in the authentication field and is called at the time of authentication creation. If any errors are encountered, an error will be displayed to the user and authentication will not be created.

Convention for validate block
 

 validate : function (input, output)
  {
    // auth data will be available in input.auth
    // var username = input.auth.username
    // var password = input.auth.pass
   // var apiKey = input.auth.apikey
  }
}

The input.auth key contains the details of your auth data. Using it, you can add validation logic in the validate block, as shown below:

4-validate.png


Once you have created the authentication module, it will be automatically injected to the trigger/action it has been used in. You can now test the trigger/action to see if it works as expected.