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

   If you update your authentication settings, existing connections will fail. You must create a new connection and update your processes to use the new connection.
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 package 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 following options are supported:

• 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 setting up the authentication, you are configuring how anybody using your connector needs to authenticate. This is you while you are building the connector, but could also be others that end up using your creation.

OAuth 2.0 Authorization code

Overview

OAuth 2.0 authorization code is one of the most commonly used authentication protocols.

Authentication fields

URL fields such as Authorization URL and Token URL do not inherit the base URL from the connector and require the entire URL. This allows for use cases where a provider uses a different base URL for authentication than that of the rest of the API.

Required fields

Note: The client ID and client secret are often generated from the API provider. Please reference the provider’s documentation to learn how to generate these values for authentication.

Field	Description
Client ID	Provider-generated application identifier.
Client secret	Provider-generated application secret key.
Authorization URL	URL that redirects the user to complete the authentication process. Returns a authorization code.
Token URL	URL that UiPath uses to exchange the authorization code for a token.

Additional fields

Field	Description
Scope	Add necessary scopes for a connector with a space separating each scope (i.e., read write openid).
Refresh token URL	URL needed to generate a new access token if a refresh token is also returned. This is often the same URL that is used for Token URL.
Token Revoke URL	URL needed to revoke the access token.
Refresh interval	How long the access token is valid. The default value is 3600 seconds or 60 minutes.
Connection name	The name of the connection in UiPath once authentication is completed.
Basic Header	Indicates whether the client ID and secret are sent as a Base64-encoded value in the Authorization header. Boolean value (true/false); default is true.

How it works

Once all the field values are added or configured for the connector, UiPath® automatically guides you through the necessary steps to complete the authentication flow. UiPath supports the protocol and, if provided with a Refresh token URI, automatically regenerates access tokens in the background as needed. This keeps the connection alive and functional for as long as the underlying refresh token is valid.

Post-authorization request format

After the initial configuration is complete and a connection is made, all requests made for that connector have the authorization header automatically included in the request.

curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {yourToken}'

OAuth 2.0 Authorization code with PKCE

Overview

OAuth 2.0 authentication code with PKCE (Proof Key for Code Exchange) is a common authentication protocol that is leveraged largely by single page applications, applications that cannot securely store a Client Secret or applications that cannot ensure secure retrieval of an authorization code.

Authentication fields

URL fields such as Authorization URL and Token URL do not inherit the base URL from the connector and require the entire URL. This allows for use cases where a provider uses a different base URL for authentication than that of the rest of the API.

Required fields

Note: The client ID and client secret are often generated from the API provider. Please reference the provider’s documentation to learn how to generate these values for authentication.

Field	Description
Client ID	Provider-generated application identifier.
Client secret	Provider-generated application secret key.
Authorization URL	URL that redirects the user to complete the authentication process. Returns a authorization code.
Token URL	URL that UiPath uses to exchange the authorization code for a token.

Additional fields

Field	Description
Scope	Add necessary scopes for a connector with a space separating each scope (i.e., read write openid).
Refresh token URL	URL needed to generate a new access token if a refresh token is also returned. This is often the same URL that is used for Token URL.
OAuth2 PKCE Code Challenge Method	The method used to generate the challenge. Can be either S256 or plain (recommended: S256).
Token Revoke URL	URL needed to revoke the access token.
Refresh interval	How long the access token is valid. The default value is 3600 seconds or 60 minutes.
Connection name	The name of the connection in UiPath once authentication is completed.
Basic Header	Indicates whether the client ID and secret are sent as a Base64-encoded value in the Authorization header. Boolean value (true/false); default is true.

How it works

Once all the field values are added or configured for the connector, UiPath® automatically you through the necessary steps to complete the authentication flow. UiPath supports the protocol and, if provided with a Refresh token URI, automatically regenerates access tokens in the background as needed. This keeps the connection alive and functional for as long as the underlying refresh token is valid.

UiPath supplies the challenge string necessary for PKCE based authorization, only the OAuth2 PKCE Code Challenge Method is required.

Post-authorization request format

After the initial configuration is complete and a connection is made, all requests made for that connector have the authorization header automatically included in the request.

curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'Authorization: Bearer {yourToken}',

OAuth 2.0 Client credentials

Overview

OAuth 2.0 client credentials is a method for returning an access token granting access to protected resources using application specific credentials which grant the permission necessary. Client credentials are often used for machine-to-machine (M2M) applications and are not usually representative of user permissions.

Authentication fields

URL fields such as Token URL do not inherit the base URL from the connector and require the entire URL. This allows for use cases where a provider uses a different base URL for authentication than that of the rest of the API.

Required fields

Note: The client ID and client secret are often generated from the API provider. Please reference the provider’s documentation to learn how to generate these values for authentication.

Field	Description
Client ID	Provider-generated application identifier.
Client secret	Provider-generated application secret key.
Token URL	URL used to retrieve the access token.

Additional fields

Field	Description
Scope	Add necessary scopes for a connector with a space separating each scope (i.e., read write openid).
Refresh interval	How long the access token is valid. The default value is 3600 seconds or 60 minutes.
Connection name	The name of the connection in UiPath once authentication is completed.
Basic Header	Indicates whether the client ID and secret are sent as a Base64-encoded value in the Authorization header. Boolean value (true/false); default is true.

How it works

Once all the field values are added or configured for the connector UiPath® generates an authorization request, passing through the necessary credentials to generate an access token. Since OAuth 2.0 client credentials is meant for M2M applications, you only see the initial UiPath authorization page and will have no further redirects.

Once a successful authorization flow is detected, UiPath maintains the connection as long as the provided credentials are valid.

Post-authorization request format

After the initial configuration is complete and a connection is made, all requests made for that connector have the authorization header automatically included in the request.

curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'Authorization: Bearer {yourToken}',

Basic authentication

Overview

The basic authentication type allows you to define a username and password that are then Base64-encoded and prefixed with Basic. The username and password, which can be modified, are used in all connector requests as the value for the Authorization header.

Authentication fields

Field	Description
Username	The first value in the two-part colon delineated and Base64-encoded Authorization header value.
Password	The second value in the two-part colon delineated and Base64-encoded Authorization header value.
Connection name	The name of the connection in UiPath once authentication is completed.

How it works

When provided with the username and password values, UiPath® combines and colon-separates the values, Base64-encodes them, and prefixes Basic to generate an Authorization header value (e.g. Authorization: Basic base64(username:password)). This header value is passed into each request as a means of authentication.

Post-authorization request format

After the initial configuration is complete and a connection is made, all requests made for that connector have the authorization header automatically included in the request.

curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'Authorization: Basic base64(username:password)'

API key

Overview

Some providers offer an API key as a form of authentication to access their API resources. In Connector Builder, this authentication type results in the use of an 'X-Acess-Token: <provider_api_key>' header that is passed into connector requests.

Authentication fields

Field	Description
API key	The API key generated from the API provider to be used as the value for the X-Access-Token header on all connector requests.
Connection mame	The name of the connection in UiPath once authentication is completed

How it works

When you use the provider-generated API key value for the API Key parameter in Settings- Authentication, every request made for that connector includes an X-Access-Token header with the API key provided as the header value.

Post-authorization request format

After the initial configuration is complete and a connection is made, all requests made for that connector have the X-Access-Token header automatically included in the request.

curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'X-Access-Token: {yourtoken}'

Personal Access Token

Overview

Some providers provide non-expiring access tokens and use the Authorization: {access_token} header pattern for authenticating requests. The PAT authentication method allows you to provide the necessary access token and applies the headers previously listed but does not maintain the access token if it expires at any point.

Authentication fields

Field	Description
Personal access token	The provider-generated access token to be used as a value in the Authorization header field on all connector requests. Field defaults to prefix the token with Bearer to accommodate the common bearer authentication pattern.
Connection name	The name of the connection in UiPath once authentication is completed.

How it works

When you use the provider-generated API key value for the Personal Access Token parameter in Settings- Authentication, every request made for that connector includes an X-Access-Token header with the Personal access token provided as the header value.

Post-authorization request format

After the initial configuration is complete and a connection is made, all requests made for that connector have the Authorization header automatically included in the request.

curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
  --header 'Authorization: {personal_access_token}'

Custom

Overview

Custom authentication should be used when the vendor configuration does not follow any of the standards but does require authentication details to be exchanged and sent on every request.

Authentication fields

The Custom authentication fields come with an Authorization parameter as an example field but can be customized to match the authentication patterns of the API provider.

Any parameters added to the authentication from Custom authentication apply to the connector's requests.

Note: For now, Custom authentication does not allow you to create a custom authentication flow. It lets you customize the standard authentication parameters applied to requests within the connector.

How it works

Parameters added to the authentication section are automatically included in any connector requests.

No authentication

The No authentication option provides a quick selection from the listing and deletes all properties from the authentication configuration table.

How to use it

Use this option if the vendor application you are connecting to is available without having to sign in. This can be an online public service or an API that is exposed internally within the company. It requires no headers to be sent on any requests identifying who is making the API call.

Outcome when sending a request

curl --request GET \
  --url https://{baseUrl}/{resource} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'