Ingress Links¶

Developers may need to link to Vinyl from external sources such as:

Other applications
Email messages
Portals
iframes

Such links may direct the user to the default application or to a specific application. They may allow the user to choose how to authenticate or initiate the sign-in process with a specific security provider. The developer can control these behaviors by constructing the links appropriately.

Top-level Links¶

Typically, when linking to Vinyl, developers will construct a URL to the Vinyl root directory. The URL might look something like this:

https://example.com/Vinyl/

This link assumes that Vinyl is hosted in a Vinyl directory beneath the web site root directory. In many cases, Vinyl will be hosted at the web site root.

When a user follows such a link, Vinyl will redirect the browser to the login form. However, if an external authentication provider has been configured as the Default Authentication Provider, Vinyl will bypass the login form, redirecting the browser to the external authentication provider instead.

Regardless, once the user has successfully signed in, Vinyl will determine the appropriate default application based on the user's privileges. Vinyl will then redirect browser to the application's home page.

Deep Links¶

A "deep link" is a URL that points to a specific application or page. An example of a deep link might look something like this:

https://example.com/Vinyl/app/Sales/Leads

In this example, Sales corresponds to the application name; Leads, the page name. Note that these are URL encoded as per RFC 3986, section 2 (https://tools.ietf.org/html/rfc3986#section-2).

Vinyl supports deep linking. Specifically, developers can construct links that point to a specific application or page within Vinyl. As with top-level links that point to the web site root, Vinyl will automatically determine whether the user needs to authenticate, redirecting the browser to the login form or external authentication provider. Once the user has successfully signed in, Vinyl will redirect the browser to the deep link URL.

The simplest way to construct a deep link is to surf to the target page. The browser's address bar will contain a URL that looks something like this:

https://example.com/Vinyl/app/Sales/Leads?$activepanel=Leads&Leads.LeadId=123456

The portion of the URL starting with the question mark (?) is the query string. Vinyl uses the query string to track selected panels and rows, filter and search criteria, etc. Remove the query string to construct the canonical URL to the page.

Query String used in URL¶

In building the exact page URL, Vinyl does what it needs to maintain the entire context of your session. In general, there are different components of a given Vinyl page that may end up included as part of the query string URL. Components ending up in the URL may include: Primary Keys, Page Name, Panel Name, and Control Name.

Tips to Shorten URL¶

There are instances where Vinyl generates a very long URL for Pages. In this section we will provide some general tips to consider to help shorten the URL.

Define your Primary Keys. Vinyl will use in the URL what it sees as PKs to keep track of selected records, and sometimes Vinyl will use all or most of the columns if left implicit in the rule. For this reason, always make sure you find the actual unique columns needed to identify your record.
- If you decide to use a longer string as your Primary Key, know that will take up more space in the URL
Keep your Names short for Page, Panels, and Controls. If you require them to display as longer name values, use the Label field (which will not be included as part of the query URL)

In addition to the tips listed, IIS settings may be worth reviewing by your System Administrator. IIS places some limitations on URL length by default, and some settings are configurable to allow for longer URLs. Settings to review include:

maxAllowedContentLength - Maximum file upload size. Defaults to 30000000
maxUrl - Maximum URL length. Defaults to 4096
maxQueryString - Maximum URL query string length. Defaults to 2048

See the Microsoft article on Request Limits <requestLimits> for more information.

Warning

Changing an application or page name will break existing deep links.

Authentication¶

As noted above, Vinyl will automatically redirect anonymous users to either the login form or an external authentication provider. In most scenarios, this is the desired behavior. However, there may be situations which require the user to sign in with a specific security provider. Examples include:

The deep link points to a page that requires a specific authorization. For instance, the target page may display data retrieved from Salesforce. In which case, the user will need to authenticate with Salesforce before accessing the page.
The user has already authenticated with a single sign-on (SSO) provider. For instance, the user may follow a link within a portal. To access the portal, the user signed in with Active Directory Federation Services (ADFS). Assuming Vinyl is also configured to authenticate users via ADFS, the user may effectively bypass the login form when following the link.

Challenge URLs¶

To force users to authenticate with a specific security provider, the link must be constructed in such a way as to trigger a challenge. The following example demonstrates a challenge for a specific authentication provider:

We'll refer to this as the challenge-url. The challenge-url is constructed of:

<vinyl-root>/service/authentication/external?provider=<provider-name>&returnUrl=<response-url>

Where:

<vinyl-root> - This is the absolute URL to the Vinyl web application root directory. It does not include the trailing slash. In this example, vinyl-root is https://example.com/Vinyl.
<provider-name> - This is the security provider name as defined within Vinyl. In the example above, provider-name is SAML. Note that provider-name must be URL encoded.
<response-url> - This is the Vinyl web application's callback URL. It's not the deep link. The response-url needs to be URL encoded.

In the example above, decoding the response-url produces:

https://example.com/Vinyl/auth/authenticated?returnUrl=%2Fapp%2FSales%2FLeads

The response-url is composed of:

<vinyl-root>/auth/authenticated/?returnUrl=<relative-link>

Where:

<vinyl-root> - Absolute URL of the Vinyl web application root. See above.
<relative-link> - This is the Vinyl web application root-relative portion of the deep link. It is URL encoded.

In the example above, the relative-link is:

%2Fapp%2FSales%2FLeads

Decoding the relative-link gives us:

/app/Sales/Leads

As noted above, this is relative to the the Vinyl web application root directory (i.e. vinyl-root).

Constructing a challenge URL¶

To construct a challenge URL, we need to reverse the process.

Step 1) Start with the deep link and remove vinyl-root to get relative-link. It should begin with /app. URL encoded the relative-link.

Step 2) Construct the response-url from:

<vinyl-root>/auth/authenticated/?returnUrl=<relative-link>

URL encode response-url.

Step 3) Construct the challenge-url from:

<vinyl-root>/service/authentication/external?provider=<provider-name>&returnUrl=<response-url>

Fiddle for generating the challenge URL¶

The following JSFiddle can be used to generate a challenge URL:

https://jsfiddle.net/8s8gkufh/1/

HTML

Link:<br>
<input data-bind="value: link"><br>
Provider<br>
<input data-bind="value: provider"><br>
Challenge URL:
<input data-bind="value: challenge" readonly>

JavaScript

function ViewModel() {
  this.link = ko.observable("http://example.com/Vinyl/app/Northwind");
  this.provider = ko.observable("SAML");

  var startOfRelativeLink = ko.computed(function() {
    return this.link().indexOf("/app");
  }, this);

  var root = ko.computed(function() {
    return this.link().substr(0, startOfRelativeLink());
  }, this);

  var relativeLink = ko.computed(function() {
    return this.link().substr(startOfRelativeLink());
  }, this);

  var response = ko.computed(function() {
    return root() + "/auth/authenticated?returnUrl=" + encodeURIComponent(relativeLink());
  }, this);

  this.challenge = ko.computed(function() {
    return root() + "/service/authentication/external?provider=" + encodeURIComponent(this.provider()) + "&returnUrl=" + encodeURIComponent(response());
  }, this);
}

ko.applyBindings(new ViewModel());