Connector Builder Guide – Authentication Type: Custom

[former_member604434]

Connector Builder Guide – Authentication Type: Custom

Open Connectors consists of over 170 connectors to 3rd Party Applications natively embedded in the SAP ecosystem. If the Connector you need does not exist in the catalog, you can build it quickly with Connector Builder. This instruction guide will walk you through using this tool, with concrete examples throughout. The beginning, Part 1, can be found here.

 

Selecting Custom Authentication allows you to create any authentication type that doesn’t fit one of the established selections, like basic or oauth 2.0. As you can see from the image below, you will be starting with a blank slate without any configuration variables or authentication parameters. Let’s go through a few examples (API Key Authentication, JWT, and Client Credentials):



Example 1 - API Key Authentication

API Key Authentication requests an API Key from the user and will then append a header to every subsequent API call that looks something like this:

{ "Authorization":"API_KEY XXXXXXXXX" }

We need to request the API Key from the user. To do that, we will add a configuration variable and set it as Required.





Now, when the user creates a Connector Instance, he will be prompted to enter in their API Key.

Next, we need to create a global parameter, that will append this header

{ "Authorization":"API_KEY XXXXXXXXX" }

To every subsequent API call made in the Resources Screen of Connector Builder.



Since we’ve selected value, anything written will be entered exactly as the value to the property Authorization, which will be sent as the header on a request. To use a configuration value, you use the format ${configuration.<<key name>>}. Since we are on the Setup Screen of Connector Builder, the Parameters here represent global parameters.

 

Example 2 - JWT Token

This example will be generating a JWT Token from the Zoom documentation.

The first thing that is required to generate a JWT token is the user’s key and secret provided from Zoom. Let’s add those configuration variables so that we can request them from the user when he creates a Connector Instance:



Now we will set up a prehook to take care of the complex hashing that is required.

let key = configuration['key'];

let secret = configuration['secret'];

let header = {"alg":"HS256","typ":"JWT"};

let headerString = JSON.stringify(header);

let headerEncode = CE.b64(headerString);

let payload = {"iss":key,"exp":1496091964000};

let payloadString = JSON.stringify(payload);

var payloadEncode = CE.b64(payloadString);

let headerPlusPayload = headerEncode+"."+payloadEncode;

let sig = CE.hmacSha256Base64(secret, headerPlusPayload);

let jwtToken = headerPlusPayload+"."+sig;



request_vendor_headers.Authorization = "Bearer "+ jwtToken;

done({"request_vendor_headers":request_vendor_headers,      

      "contintue":true});

Let’s break down what this prehook is doing.

First it is accessing the configuration value for the key and secret that the user entered. Next, it is generating the jwtToken based on this article. The libraries that are accessible in prehooks can be found here. Finally, it is adding an Authorization key to the request_vendor_headers object. This is a global prehook since it is in the Setup Screen of Connector Builder. This header object {“Authorization”:”Bearer XXXXX”} will be sent on all subsequent calls created on the Resources Screen. In this case we do not need to add a global parameter to do this as the prehook can take care of it.

 

Example 3 - Client Credentials Authentication

This example will be generating an access token from the OneLogin API Documentation. The Connector will then store this token in a configuration variable and a global parameter will be created that will send this token in the header of each subsequent API call. A configuration variable called expires_in will be used to make sure this generated access token is refreshed appropriately.

First, the user has to enter her client_id and client_secret when creating a Connector Instance. Let’s add three configuration keys. A key, secret, and a token, to store the access token once we generate it.



To generate the token, we will create a resource on the next screen, the Resources screen, of Connector Builder.



Editing this newly created resource expands the resource



First, the vendor method is changed to POST. The vendor path is changed to https://api.<us_or_eu>.onelogin.com/auth/oauth2/token so that it isn’t appended to the base URL in Setup screen. A parameter is added to send the Authorization header with a value of client_id:<client_id>, client_secret:<client_secret>

To use a configuration variable here, the format is ${configuration.<<key name>>}

A different parameter is created to store the response, specifically the bodyToken data[0].access_token value in the configuration variable we created before called token. Notice how the source this time is set to Response.

Here is the response in full:

{

  "status": {

    "error": false,

    "code": 200,

    "type": "success",

    "message": "Success"

  },

  "data": [

    {

      "access_token": "xx508xx63817x752xx74004x30705xx92x58349x5x78f5xx34xxxxx51",

      "created_at": "2015-11-11T03:36:18.714Z",

      "expires_in": 36000,

      "refresh_token": "628x9x0xx447xx4x421x517x4x474x33x2065x4x1xx523xxxxx6x7x20",

      "token_type": "bearer",

      "account_id": 555555

    }

  ]

}

We should also create a configuration variable to hold the expires_in and refresh_token bodyTokens.

To recap to this point we have asked the user for their client_id and secret, have made a call out to OneLogin to get the token, and stored the access_token in the token configuration variable. The only step left is to place this token the header for every subsequent API call.

But first, there is an important point to explain. In the Configuration, the resource type is set to Provision Auth Validation. For normal API calls, it is set to API. Provision Auth Validation means that when you create a Connector Instance, this call will run automatically, which means it will get the access_token and store it to the configuration variable called token.

To finish up, we need to go back to the Setup Screen and add a global parameter to place this token in the header for all subsequent API calls.



Note that if I had created a parameter on the Resource itself, it would have only applied to that one resource. Since this is an authentication header, it is better to place it globally.

One last point. If we add a configuration variable called expires_in, this will tell the resource with type PROVISION AUTH VALIDATION when to run again. It is in seconds.