Configuring the authentication

One of the big pillars for creating a connector is identifying and correctly integrating its authentication setup. If done correctly, once the connector is published to the Integration Service catalog, users can create connections to it just like with any other connector within the catalog.

All connectors reuse the authentication framework so that the full authentication flow and connection management can be handled in a unified approach.

The end-result of authentication is that any subsequent request within this connector uses the result of the authentication process for every API call. For example, a Bearer token is sent in the headers on every API call:

Connector Builder supports the following industry standards through simple configuration rather than extensive coding:

• OAuth 2.0 Authorization code
• OAuth 2.0 Authorization code with PKCE
• OAuth 2.0 Client credentials
• Basic
• API key
• Personal Access Token (PAT)
• Custom
• No authentication

Since Connector Builder ties into the Integration Service framework, defining your authentication setup is now a matter of configuration rather than a complex process. This means that the framework deals with token exchanges, refreshes, and any other such tasks. Connector Builder defaults to OAuth 2.0 Authorization code, since this is the most common vendor approach to handle authentication.

The authentication page is made out of three components:

1. The Authentication type, which drives how the authentication framework reflects with additional validation for PKCE, full token exchange (for OAuth), etc. In addition, it also reconfigures the table with properties underneath so that the required properties are outlined.
   

   

   
   
2. The properties table can be modified with custom parameters and/or editing existing ones. Depending on the Authentication type selection in the drop-down menu, some fields might be mandatory and specified in red.
   Note: Changing these properties within this table or the Authentication type in general invalidates the connection you might have already created within Connector Builder. There is only one connection during design time, and it needs to be set up and tested against the latest authentication configuration.
3. The Authentication screen is automatically generated based off the configuration you provided. What you see during configuration within Connector Builder is exactly the end-result that users of your activity pacakge will see.
   
   
   
   

Authentication table configuration

Disregarding the Authentication type, the loaded properties table identifies two items:

1. What the user sees within the authentication screen.
2. How authentication is handled by the authentication framework.

• Every line item in the table represents a property that can or can not be overwritten by the user. To present a given field on screen, it needs to be flagged as Ask the user - Yes.
• Every line item has a Name and a Display name. The Name is what the vendor is expecting for the technical setup and the latter is of importance on how to ask this input from the user on the authentication screen.
• Every line item holds an action menu which allows editing the property into far more detail. This is where you can state that a given property needs to be sent as a header. See more examples in the API Key section.

Authentication types

In the Authentication tab, you configure the authentication type for your connector. The supported options are:

• OAuth 2.0 Authorization code
• OAuth 2.0 Authorization code with PKCE
• OAuth 2.0 Client credentials
• Basic
• API key
• Personal Access Token (PAT)
• Custom
• No authentication

Note: When configuring the authentication, you are configuring how anybody using your connector needs to authenticate. This will be you while you are building the connector, but could also be others that end up using your creation.

Basic authentication

1. Select the Edit button under the Action column to configure each property. Username and Password are available by default.

2. Select Add parameter if you want to add another field to be used during authentication:

   • Display name – Shown to the user when connecting.
   • Type – Defines the input field on the connection dialog. Select an option from the drop-down: true/false, password, test, yes/no.
   • Ask the user – Set to Yes when user input is required.
   • Value – Use this field to set a default value.
   • Hint text – User guidance for the input field.
   • Provider name - The technical key for the API call.
   • Send to provider as type – How the API receives the value. Select an option from the drop-down: configuration, header, path, body, query, form. Default value: header.
   
   

   

   
   
3. Select Save to save your new authentication parameter.
4. Use the Reset to default option if you want to reset your authentication to the original values for Basic. This operation cannot be undone.

OAuth 2.0 Authorization Code

To use OAuth 2.0 Authorization Code, you need to create an OAuth app in the application you want to integrate with, and retrieve from there the credentials necessary for configuring your connector.

Configure the following fields:

• Client ID
• Client secret
• Scope
• Authorization URL
• Token URL
• Refresh token URL
• Basic header
• Token revoke URL

• Refresh interval

  Note: The Authorization, Token, and Refresh token URLs should be available in the app's API documentation.

OAuth 2.0 Authorization Code with PKCE

OAuth 2.0 Authorization Code with PKCE is identical to the OAuth 2.0 Authorization Code method, but it also includes the OAuth2 PKCE Code Challenge Method field.

OAuth 2.0 Client Credentials

For OAuth 2.0 Client Credentials, you must configure the following fields:

• Client ID
• Client secret
• Scope
• Token URL
• Basic header

• Refresh interval

API Key

Use this option for integrating with apps that require an API key to make API calls against.

Set the API Key field to your desired value.

Personal Access Token

Use this option for integrating with apps that require a bearer token to make API calls against.

Set the Personal Access Token field to your bearer token.

Custom

You can also set up a custom authentication, using whatever fields you want.

No authentication

Use this option if you don’t need users to authenticate to use the connector.