Skip to Content

Sites and Aliases

Overview

On a default install, Vinyl 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. /Vinyl. 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/Vinyl/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, Vinyl 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 a Vinyl 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 Vinyl instance.

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

Configuration

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

  1. Switch to the Vinyl 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/Vinyl.
  • 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 Vinyl 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, Vinyl matches the HTTP request to a site. Then, Vinyl redirects the client web browser to the canonical URL if necessary.

Matching

When Vinyl receives an HTTP request, it attempts to match the URL to a site or alias. Vinyl 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: /Vinyl.

Note that Vinyl 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/Vinyl - HTTPS scheme, mixed case path.

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

  • https://example.com/Vinyl
  • https://example.com/Vinyl/Vinyl2

Vinyl 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, Vinyl 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, Vinyl will abort the request and respond with an HTTP redirect.

At this stage, Vinyl 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/Vinyl - HTTPS scheme, mixed case path.

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

Reverse Proxies and Load Balancers

Vinyl 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 Vinyl 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/Vinyl, and enable the Redirect option.

Review information on Reverse Proxies and Load Balancers when using HTTPS

Framing

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

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

https://registration.example.com/

And Vinyl is published on a different domain:

https://vinyl.example.net/

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

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

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