Skip to main content

Create an OAuth 2.0 iClient resource

Kathyana Rule
  • Updated

Rate this feature
Included in the Jan. 2023 release Use an iClient when authenticating your HTTP connection with OAuth 2.0. OAuth 2.0 iClients are available in the Resources menu → iClient. When creating an iClient in an application connector, you can toggle between a simple or HTTP view. You can use a single OAuth 2.0 iClient for multiple connections if they have the same provider. To create an iClient for a specific API or version, select your application and the available APIs or versions will appear. 

Contents

iClient resource configuration
Simple iClient application configuration
HTTP iClient configuration

To create an OAuth 2.0 iClient, fill in the required fields:

Configure OAuth 2.0

Fields Description
Client ID Enter your client ID as found in your application.
Client secret

Enter the client secret as found in your application.

Multiple layers of protection are in place, including AES 256 encryption, to keep your connection’s secret safe. When editing this form later, you must generate this value again; it is stored only when the connection is saved and never displayed as text.
Grant type OAuth 2.0 authentication currently supports two grant types: authorization code and client credentials.
  • Choose Authorization code to use an authorization server to obtain an authorization code as an intermediary between the client and resource owner.
  • Choose Client credentials if authorization scopes are limited to protected resources under the client's control or previously configured on the authorization server.
    • Use JWT – Use JWT (JSON Web Token) as a secure digital pass to improve your app’s identity for OAuth specification.
  • Choose Authorization code with PKCE (Proof Key for Code Exchange) to extend security to the OAuth 2.0 authorization code grant flow. This improves the security of public client applications, such as mobile or single-page web applications.

Authorization code

The provided code is obtained by using an authorization server as an intermediary between the client, integrator.io, and resource owner. Selecting Authorization code enables additional required and informational settings.

  • Send client credentials via: Sends a basic auth request in the header or client credentials in the request body.
  • Authorization URL: This is the authorization code retrieval endpoint on the API provider’s authorization server.
  • Access token URL: integrator.io retrieves the access token from this URL.
  • Valid domain names: integrator.io validates the HTTP requests sent to various OAuth URLs using the domain name value. If the Authorization URL, access token URL and revoke token URL have different domain names, provide them as comma-separated values in any order.

Client credentials

Limits the authorization scope to the protected resources under the client's control or to those previously arranged with the authorization server. Selecting Client credentials exposes additional required settings.

  • Send client credentials via: Sends a basic auth request in the header or client credentials in the request body.
  • Use JWT: Use JWT (JSON Web Token) as a secure digital pass to improve your app’s identity for OAuth specification. You can generate secure JWT tokens by signing in using signature methods such as RSA-SHA and HMAC-SHA. Then, you can utilize these JWT tokens or access tokens to invoke your APIs securely.
  • Signature method (JWT only): Select the required method to sign the API call. For HMAC signature options, the secret key appears. For all other options, a private key is required.
    • Secret key (HMAC only): Use this key as a secret password that generates the JWT signature.
    • Private key: Copy the private key from the portal you want to use to authenticate the connection. Before you add it to integrator.io, you must replace all newline characters (\n) throughout the private key. The private key must be in PEM format. You can convert PFX certificates or convert from a PPK file.
    • Payload: The JSON object contains the message sent to the application. This is used along with the secret key to ensure no alteration to the message along the way.
    • Header: The JWT header is a JSON object that typically consists of two properties:
      • alg (Algorithm): Specifies the algorithm used to sign the token. It can be HMAC SHA256, RSA SHA256, or others, depending on the chosen cryptographic algorithm.
      • typ (Type): Indicates the token type, typically set to "JWT" for JSON Web Tokens.
  • Access token URL: integrator.io retrieves the access token from this URL.
  • Revoke token URL: integrator.io makes an HTTP post request to the token revocation endpoint URL to revoke a particular token.
  • Valid domain names: integrator.io validates the HTTP requests sent to various OAuth URLs using the domain name value. If the Authorization URL, access token URL and revoke token URL have different domain names, provide them as comma-separated values in any order. This field protects your OAuth 2.0 credentials so other users creating connections with the same iClient resource can't point their connection to a nonsecure URL that would receive your client secret.

Paste your private key:

  1. Paste the private key into a text editor.
  2. Find \n.
  3. Delete the \n characters and press Enter or Return. Repeat this for each instance of \n.
  4. Ensure -----BEGIN PRIVATE KEY----- appears before the key, and -----END PRIVATE KEY----- appears after the key.
  5. Copy and paste the reformatted private key (including the begin and end declarations) into integrator.io.

Authorization code with PKCE (Proof Key for Code Exchange)

PKCE, often used for public client applications like mobile or single-page web apps, adds an extra layer of security by requiring the generation of a unique code verifier. This random value is transformed into a code challenge using a cryptographic hash function, protecting your data from code injection and interception attacks. Meanwhile, the Password Credentials grant type simplifies the authentication process for trusted clients and direct user interactions, eliminating the need for additional authorization servers.

  • Code challenge method: Algorithm used for generating code challenge.
  • Access token URL: integrator.io retrieves the access token from this URL.
  • Revoke token URL: integrator.io makes an HTTP post request to the token revocation endpoint URL to revoke a particular token.
  • Valid domain names: integrator.io validates the HTTP requests sent to various OAuth URLs using the domain name value. If the Authorization URL, access token URL and revoke token URL have different domain names, provide them as comma-separated values in any order. This field protects your OAuth 2.0 credentials so other users creating connections with the same iClient resource can't point their connection to a nonsecure URL that would receive your client secret.

OAuth 2.0 overrides

Field

 Description
Override default scope delimiter Enter the non-space scope delimiter used by your API provider.
Override access token HTTP headers In some rare cases, it may be necessary to include custom HTTP headers with your API requests. The default content-type header value is application/x-www-form-urlencoded. Enter a name and a value to replace default header values with custom values.
Override access token request body Configure your own access token body in JSON format if it is different from the default access token body. This JSON format is finally converted to the form-urlencoded format on the wire. Default access token body format if 'Client Authentication' set as 'body':
{ code: {{{query.code}}}, redirect_uri: {{{redirectUri}}}, client_id: {{{clientId}}}, client_secret: {{{clientSecret}}}, grant_type: “authorization_code”}.
Default access token body format if 'Client Authentication' set as 'header': { client_id: {{{clientId}}}, client_secret: {{{clientSecret}}} grant_type: “client_credentials” }.
Override refresh token HTTP headers In some cases, it may be necessary to include custom HTTP headers with your token refresh requests. As with the 'body' field, any value from the connection can be referenced using {{{placeholders}}} with a complete path matching the connection field.
Override refresh token HTTP request body Configure your own refresh token body in JSON format if it is different from the default refresh token body. This JSON format is finally converted to the form-urlencoded format on the wire.
Default refresh token body format:
{ client_id: {{{clientId}}}, client_secret: {{{clientSecret}}}, grant_type: “refresh_token” }
Override revoke token HTTP headers In some rare cases, you may need to include custom HTTP headers with your API requests. The default content-type header value is application/x-www-form-urlencoded, and the authorization header value is basic.
Override revoke token HTTP body

Configure your own revoke body in JSON format if it is different from the default revoke token body. This JSON format is finally converted to the form-urlencoded format on the wire.
Default revoke body format:{ token: {{{connection.http.auth.token.token}}} }.

Configure token auth

Send token via: Select the location where your API expects to find the authentication token

HTTP body

The API requires the token to be embedded in the body structure of your HTTP request. In such cases, place the token in your body template using the handlebars placeholder {connection.http.token.token}

HTTP header

Allows you to specify the header name and authentication scheme to use when constructing the HTTP request.

  • Header name: By default, integrator.io will send all authentication type info in the 'Authorization: ' HTTP header field. If the REST API you are connecting to requires a different HTTP header, use this field to provide an override.
  • Header scheme: Use this field to set the HTTP authorization header scheme value. For example, 'Bearer' would be the scheme value for 'Authorization: Bearer my_secret_api_token'

URL parameter

The authentication token is located in the URL. Specify the query string parameter name that holds the token value.

Parameter name: Use this field to specify the name of the URL parameter that holds the API token value. For example, if you specify myAPITokenURLParam, then all HTTP requests will include ?myAPITokenURLParam=[token]

Non-standard API response patterns

Field

 Description
Override HTTP status code for auth errors This field only needs to be set if the HTTP status code for auth errors is not 401. For example, an API could return a generic 400 status code instead, and then use a field in the HTTP response body to indicate auth errors.
Path to auth error field in HTTP response body This field only needs to be set if the API returns a field in the HTTP response body to indicate auth errors. For example, if an API returns the field 'errorMessage' with the value 'Auth failed', then you would set this field to 'errorMessage'.
Auth error values Use this field to limit the exact values in the HTTP response body field that should be used to determine auth errors. To provide multiple values, use a comma-separated list.

Related articles

Comments

0 comments

Please sign in to leave a comment.