Skip to main content

Session Continuation

Who is this guide for?​

The following guide is intended for readers that are familiar with the following concepts:

What is session-continuation​

Browsers have many ways to store information for a website. Setting cookies is one of them. Our JS API (Surfly's Widget) allows you start a Surfly session transferring most of the website's state information like sessionStorage, localStorage, non-httpOnly cookies, and form fields.

But sometimes that's not enough and you might need to transfer httpOnly cookies. That's when Session continuation comes in.

Session continuation is a mechanism that allows you to start a Surfly session on a website while preserving httpOnly cookies.

Example: Shopping Cart

A user is browsing through a shopping website. While they navigate the user struggles filling in the payment form, and they seek help from a support agent. The agent starts a Surfly session which opens in an iframe on top of the original website. The user doesn't see much of a difference, except for the second cursor on the screen that belongs to the agent.

In this example, all cookies are transferred inside the Surfly session so the user preserves the login and shopping cart information.

Do I need session continuation?​

The first thing you have to determine is if you need session continuation at all.

As previously explained, browsers store website state in different ways. So if you find yourself in the need to start a Surfly session while preserving the state that is stored in session cookies (httpOnly cookies), then you probably need this feature.

But if your website is simple enough, you can try using just our JS API (Surfly's Widget) in your website. Surfly will try to guess the information it can't get using javascript api's (for example, assuming the path for every cookie is '/', etc).

How does it work?​

Session Continuation is intended to solve the problem of transferring cookies that we cannot read using native JavaScript APIs (httpOnly cookies).

To leverage it, you will not only be required to include our JS API in your website but you will also need to implement some endpoints to which our JS API will make some requests.

Those endpoints are what we call "continuation points" and their function is to forward all the requests that they receive to our Surfly servers.

When Surfly's JS API makes a request to your servers the browser will send all the cookies (including httpOnly cookies) because it's a same-site request and that's how browsers work. Then when these requests are forwarded to our Surfly servers we can access all this info so that we are be able to start a session while preserving the website's state (setting all the cookies in the iframe).

To summarize, the difference between State Transfer and Session Continuation is:

FeatureState TransferSession Continuation
Session storage
Local storage
Form fields
Regular cookies
HttpOnly cookies
Cookies with path (other than "/")

Continuation points​

In order to determine what are the continuation points you need to set up, you first need to figure out on which domains of your website are the cookies that you need to transfer.

For example, lets assume you need to transfer cookies from mywebsite.com and app.mywebsite.com domains into a Surfly session.

Then you would need to set up your infrastructure to forward all requests received on the following urls to our Surfly servers.

  • mywebsite.com/surfly_cookie_transfer/
  • mywebsite.com/surfly_cookie_transfer/*
  • app.mywebsite.com/surfly_cookie_transfer/
  • app.mywebsite.com/surfly_cookie_transfer/*

These are the so called continuation points.

How to set this up will vary depending on your particular infrastructure. You might need to configure your load balancers, CDNs or other parts of your system.

If this is correctly done, then the Surfly JS API will make some requests to these continuation points so that Surfly servers can retrieve the cookies information and set these cookies in the session iframe.

Implementing a continuation point​

As previously explained, once you figure out what your continuation points are you'll need to configure your system to forward the requests made to those endpoints to our servers but with some additional headers.

When forwarding the request to our servers you must add the X-Widget-Key and X-Continuation-Origin headers.

  • X-Widget-Key must contain your Surfly widget key
  • X-Continuation-Origin must contain the origin of your website. That is, a protocol scheme followed by domain name and a port (in case it is non-standard). For example, a continuation point at https://mywebsite.com/surfly_cookie_transfer/ should set the X-Continuation-Origin header to "https://mywebsite.com".
Caution

Remember that the protocol scheme matters in this case (”http://example.com" and "https://example.com" are different origins).

Setting the right Host header​

Depending on your infrastruture some systems give you the option to keep or modify the Host header when forwarding the request (like some popular CDNs). In these cases keep the Host header with the value of the origin where the request is going (the surfly servers).

Cookies with Path​

Because the URL of the continuation point has a specific path, it cannot capture cookies that have the Path attribute set to something else than “/” because browsers won't send such cookies.

Multiple continuation points​

There are a number of reasons why you might need to setup multiple continuation points. Some examples are:

  • Your website is served over HTTPS and HTTP
  • Your website stores cookies on multiple domains that share a common public suffix (for example authentication cookies onmywebsite.com, but also keep shopping cart cookies on cart.mywebsite.com)
  • You have implemented Surfly on more than just one domain

All these cases are treated by the browser as different sites so cookies will be isolated in each of them. For that reason you will need to set multiple continuation points and the Surfly script will handle them.

Note that for security reasons, the Surfly widget will ignore continuation urls that don't share a common eTLD+1 suffix with the URL where the session is started on.

Transfering 3rd party cookies​

The session-continuation feature is inteded for transferring first party cookies. It is not able to transfer both first and third party cookies.

It is possible, however, to transfer only third party cookies. Check the following advanced guide for more information.

You can find example configurations for popular load balancers below. Note that there might be slight differences, depending on the versions.

location /surfly_cookie_transfer/ {
    proxy_pass https://surfly.com;
    proxy_redirect off;
    proxy_set_header X-Continuation-Origin https://example.com;
    proxy_set_header X-Widget-Key **Widget key here**;
}

Verifying the continuation point​

Once you've set up the continuation point, you can check its status by typing in your domain and adding /surfly_cookie_transfer/ to the end (for example, https://mywebsite.com/surfly_cookie_transfer/).

If requests are properly forwared to our servers, we will serve a page that will execute a quick check, and report if there are some problems detected. If any of the boxes are red, it means that your continuation point is not set up correctly.

Click the question mark icon (“?”) of the respective box for instructions on how to adjust this. For instance, you might find that the bottom box will light up red. This has to do with the company domain settings.

Updating your surfly settings​

The last thing you need to do is to update the following options in your surfly settings.

  • Add all continuation points urls to the cookie_transfer_urls list
  • Set the cookie_transfer_proxying option to true
  • Set the cookie_transfer_scopes. Within the cookie transfer scopes, you need to specify all the cookies you want to transfer. So this also includes the non-httpOnly cookies.
Tip

If you want to only change the cookie scopes but you don't require a continuation point, you can also only update the cookie_transfer_scopes option. In this case you must not set the cookie_transfer_urls or cookie_transfer_proxying options.

Finally, your session continuation settings might look something like this:

{
    "cookie_transfer_enabled": true,
    "cookie_transfer_proxying": true,
    "cookie_transfer_urls": [
        "https://mywebsite.com/surfly_cookie_transfer/",
        "https://app.mywebsite.com/surfly_cookie_transfer/"
    ],
    "cookie_transfer_scopes": [
      {
          "path": "/",
          "domain": ".mywebsite.com",
          "name": "cookie1",
          "httponly": true
      },
      {
          "path": "/",
          "domain": ".app.mywebsite.com",
          "name": "cookie2",
          "httponly": false
      },
      {
          "path": "/",
          // a host-only cookie, note the domain without a leading dot
          "domain":"mywebsite.com",
          "name": "cookie3",
          "httponly": false
      }
    ]
}
Note

You can also update these settings in the Surfly dashboard

When you check your continuation point status page again, it should look like this: