Skip to Content

Sites and aliases in Jitterbit App Builder

Overview

On a default install, App Builder accepts and responds to HTTP requests regardless of the URL. This is convenient when getting started, but it can lead to problems down the road. Issues arise from the different treatments of URLs.

  • HTTP cookies can be restricted to a specific path, e.g. /App Builder. The client web browser treats cookie paths as case-sensitive; the web server, may not.
  • Similarly, external authentication providers may treat the path as case-sensitive when validating redirect URLs such as https://example.com/App Builder/signin-SAML.
  • Additionally, the client web browser will not allow the application server to overwrite an insecure cookie with a secure cookie.

To avoid these and other issues, administrators should take steps to canonicalize the URL. Although this can be achieved through web server rewrite rules, App Builder provides support for URL canonicalization via the Sites and Aliases feature.

Sites

A site defines a canonical URL. A default install includes a single site. The site does not have a specific URL. Instead, the URL is inferred from the HTTP request.

It is possible to define multiple sites and, thus, multiple canonical URLs. This can be useful, for example, when framing an App Builder application. See Framing below.

Only one site can be configured as the "default" site. The default site is used when determining the canonical URL. See Matching below.

Aliases

A site may have zero or more aliases. An alias is an alternative, non-canonical URL which can be used to access the App Builder instance.

For example, the App Builder instance may have been published on the internal address https://machinename/App Builder before it was published on the external address https://example.com/App Builder. The internal address can be configured as an alias for the external address. If the Redirect option is enabled, App Builder will automatically redirect client browsers from the internal address to the external address.

Configuration

To manage Sites and Aliases, start by signing into App Builder as an administrator, then:

  1. Switch to the App Builder IDE application.
  2. In the Connect panel, click the Connect To Your Enterprise button.
  3. In the menu on the left, click the Security Providers button.
  4. In the Configuration panel, click the Manage Sites button.

Sites are composed of the following properties:

  • URL - Fully qualified, canonical URL. Example: https://example.com/App Builder.
  • Default - Indicates whether the site is treated as the default site when matching an HTTP request to a site. See Matching below.
  • Redirect - Indicates that App Builder should redirect client browsers if an HTTP request matches the site (or one of the site's aliases) but does not match the canonical URL. See Redirect below.
  • Aliases - List of alternative URLs associated with the site. These are used to match an HTTP request to a site. See Matching below.

To make a site the "default" site, click the Make Default button. Note that this button is only visible if the site is not already the default site.

Canonicalization

Canonicalization consists of two steps. First, App Builder matches the HTTP request to a site. Then, App Builder redirects the client web browser to the canonical URL if necessary.

Matching

When App Builder receives an HTTP request, it attempts to match the URL to a site or alias. App Builder starts by performing a "loose" match. A loose match considers the following criteria:

  • Host - HTTP host name. Example: example.com
  • Port - HTTP port number. Example: 80, 443
  • Path - URL path component. Case-insensitive. Example: /App Builder.

Note that App Builder does not consider the scheme at this stage.

For the purposes of a loose match, the following URLs are considered equivalent:

  • http://example.com/vinyl - HTTP scheme, lowercase path.
  • https://example.com/App Builder - HTTPS scheme, mixed case path.

Note that this algorithm does not allow for one App Builder site to exist within another. The following is not supported:

  • https://example.com/App Builder
  • https://example.com/App Builder/App Builder2

App Builder chooses the best match with the following precedence:

  1. If the URL matches a site, the site is selected.
  2. If the URL matches an alias, the alias's site is selected.
  3. Otherwise, the default site is selected.

Redirect

Once the site has been chosen, App Builder determines if the request should be allowed to continue or if a redirect should be issued instead.

  • If the Redirect option is disabled, the request is allowed to proceed.
  • If the Redirect option is enabled and the request URL does not match the site URL, App Builder will abort the request and respond with an HTTP redirect.

At this stage, App Builder performs a "strict" match. A strict match differs from the loose match in that:

  • The path is treated as case-sensitive.
  • The scheme is considered.

For the purposes of a strict match, the following URLs are not considered equivalent:

  • http://example.com/vinyl - HTTP scheme, lowercase path.
  • https://example.com/App Builder - HTTPS scheme, mixed case path.

If the HTTP request URL does not match the site URL, App Builder responds with a redirect.

Reverse proxies and load balancers

App Builder supports reverse proxies and load balancers that terminate the SSL connection prior to the web server. These environments require additional configuration. See Reverse proxies for more information.

Use cases

Require HTTPS

Every instance of App Builder MUST be secured using HTTPS. The secure connection can be terminated at the web server or a reverse proxy. Regardless, once configured, administrators are strongly encouraged to require all clients to connect with HTTPS.

This can be achieved with sites and aliases. Set the site URL to match the secure URL, e.g. https://example.com/App Builder, and enable the Redirect option.

Review information on Reverse Proxies and Load Balancers when using HTTPS

Framing

App Builder relies on HTTP cookies. Web browsers typically block third-party cookies. This can cause problems when rendering App Builder in an HTML frame.

For example, if the framing site is published on the following URL:

https://registration.example.com/

And App Builder is published on a different domain:

https://vinyl.example.net/

The web browser will treat any cookies set by App Builder as third-party cookies and block them accordingly. To work around this problem, publish App Builder on a subdomain of the framing site's domain.

https://vinyl.registration.example.com/

Create a site in App Builder with this URL. Do not make it the Default site. Enable the Redirect option to require HTTPS.