Rendering with User Input

The base domain, header, url token extension, and config can be flexibly rendered with user input from Connector Auths.

Introduction

In the authentication configuration, additional fields can be configured which are then shown in the Connector Auth creation and can be used for rendering in these fields:

• Base Domain

• Header (inside custom_headers)

• URL Token Extension

• Authentication Configuration (inside config)

If the api_endpoint variables is specified (i.e. all older Connector Auths with a custom base domain), it will always be used instead of trying to render the base domain. This ensures that changes are backwards compatible.

Available variables

For security reasons, not all variables that can be specified can be used, only these variables are available:

• account_id

• api_endpoint

• api_version

• authorization_request_url

• client_id

• client_secret

• config

• domain

• encoding

• environment

• grant_type

• integration_code

• key

• port

• protocol

• refresh_request_url

• region

• scope

• secret

• slug

• subdomain

• system_id

Examples

EverReal - Custom subdomain and multiple OAuth2 environments

EverReal has custom subdomains, OAuth2, and different environments which have different client ids and secrets.

Thus, the user needs to specify their subdomain and can optionally set their environment (default is production); see our EverReal Connector docs for an example.

Authentication Configuration

{
  "oauth2": {
    "auth_form": {
      "subdomain": {
        "title": "Subdomain",
        "type": "text",
        "required": true,
        "info": "Will be filled in for {{ subdomain }} in https://{{ subdomain }}.everreal.co/api/prism/",
        "pattern": "/^[\\w-_]+$/",
        "regexErrorMessage": "The subdomain can only contain letters, numbers, -, and _"
      },
      "environment": {
        "title": "Environment",
        "type": "select",
        "required": false,
        "default": "Production",
        "enum": [
          "Production",
          "QA"
        ]
      }
    },
    "config": {
      "client_id": "{% if environment is defined and environment == 'QA' %}production_client_id{% else %}qa_client_id{% endif %}",
      "client_secret": "{% if environment is defined and environment == 'QA' %}production_client_secret{% else %}qa_client_secret{% endif %}",
      ...
      "step1_authorize_url": "{% if subdomain is defined %}https://{{ subdomain }}.everreal.co{% else %}{{ api_endpoint | url_origin }}{% endif %}/accounts/dialog/authorize",
      ...
    }
  }
}

In order to be fully backwards compatible, for Connector Auths created before this change (these have the api_endpoint variable specified, which consists of the entire base domain), one needs to check whether subdomain is defined and based on that use either the subdomain or the api_endpoint in order to construct the OAuth2 specific URLs.

Base Domain

https://{{ subdomain }}.everreal.co/api/prism/

As mentioned above, the base domain is backwards compatible by design, as it's by default overwritten with the api_endpoint variables if it is specified.

All other fields are not affected by the rendering.

Snowflake - Custom subdomain, headers, OAuth2 clients

Snowflake is an especially complex connector, as it requires custom OAuth2 clients and multiple account identifiers; see our Snowflake Connector docs for more details and the rendered Connector Auth form.

In order to not overcomplicate the rendering even more, all existing Snowflake Connector Auths were migrated to work with the updated Connector setup, so that backwards compatibility was not an issue.

Authentication Configuration

Due to the high number of required details by Snowflake, this is one of the most extensive configurations. Additionally all fields are required, as no defaults can be set.

{
  "oauth2": {
    "auth_form": {
      "system_id": {
        "title": "Organization Name",
        "type": "text",
        "required": true,
        "info": "The name of your Snowflake organization"
      },
      "account_id": {
        "title": "Account Name",
        "type": "text",
        "required": true,
        "info": "The unique name of your account within your organization. https://docs.snowflake.com/en/user-guide/admin-account-identifier.html#account-name"
      },
      "subdomain": {
        "title": "Account Locator",
        "type": "text",
        "required": true,
        "info": "Identifier assigned by Snowflake when the account was created. https://docs.snowflake.com/en/user-guide/admin-account-identifier.html#format-2-legacy-account-locator-in-a-region"
      },
      "client_id": {
        "title": "Client ID",
        "type": "text",
        "required": true,
        "info": "See authentication documentation for details"
      },
      "client_secret": {
        "title": "Client Secret",
        "type": "password",
        "required": true,
        "info": "See authentication documentation for details"
      }
    },
    "config": {
      "client_id": "{{ client_id }}",
      "client_secret": "{{ client_secret }}",
      ...
      "step1_authorize_url": "https://{{ system_id | lower }}-{{ account_id | lower }}.snowflakecomputing.com/oauth/authorize",
      ...
    }
  }
}

Not all variable names are corresponding to the names in Snowflake as only a limited number of variable names are available in order to keep configurations uniform.

However, for the user this does not matter, as the title (that's the field name that will be seen by the user) can be set freely.

Base Domain

For Snowflake, and most other Connectors, the 'base' part of the base domain is the same as the 'base' part of the OAuth2 authorization URL:

https://{{ system_id | lower }}-{{ account_id | lower }}.snowflakecomputing.com/api/v2/

This is also a good example of making the input for the user as easy as possible, as users can simply copy and based their organization and account name (which are by default shown in upper case letters in Snowflake) in the form and they do not need to know how exactly the URL is constructed.

Header

The header follows the standard OAuth2 header, except for one custom header, whose value is rendered from the Connector Auth user input:

{
  ...
  "custom_headers": {
    "Snowflake-Account": "{{ subdomain }}"
  }
}

SharpSpring - URL token extension

For SharpSpring, the auth token and another variable need to be sent as query parameters instead of header values.

Authentication Configuration

The configuration is a fairly regular basic auth configuration, except for the Account ID field.

{
  "basic_auth": {
    "account_id": {
      "title": "Account ID",
      "type": "text",
      "required": true
    },
    "auth_token": {
      "title": "Secret Key",
      "type": "password",
      "required": true
    }
  }
}

URL Token Extension

Here the {{ endpoint }} always needs to be specified and the auth token is always referenced to as token.

{{ endpoint }}&secretKey={{ token }}&accountID={{ account_id }}

Header

In the Header token_in_header needs to be set to false, so that it is available in the URL Token Extension fields.

{
  "encode": false,
  "token_in_header": false,
  "content_type": "application/json",
  "token_format": "{{token}}"
}