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.
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:
Feature | State Transfer | Session 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 keyX-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 athttps://mywebsite.com/surfly_cookie_transfer/
should set theX-Continuation-Origin
header to"https://mywebsite.com"
.
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 on
mywebsite.com
, but also keep shopping cart cookies oncart.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.
Continuation points in popular load balancers
You can find example configurations for popular load balancers below. Note that there might be slight differences, depending on the versions.
- Nginx
- HAProxy
- Apache
- F5
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**;
}
frontend example-com-https
acl surfly_session_continuation hdr(host) -i example.com path_beg /surfly_cookie_transfer/
use_backend surfly_continuation_point_https if surfly_session_continuation
...your custom configuration here...
backend surfly_continuation_point_https
https://example.com
http-request set-header X-Widget-Key **Widget key here**
http-request set-header Host surfly.com
server surfly surfly.com:443 ssl
SSLProxyEngine On
<Location "/surfly_cookie_transfer/">
RequestHeader set X-Continuation-Origin "https://example.com"
RequestHeader set X-Widget-Key "**Widget key here**"
ProxyPass "https://surfly.com/surfly_cookie_transfer/"
</Location>
when HTTP_REQUEST
{
if { [HTTP::uri] contains "surfly_cookie_transfer/" and [HTTP::host] contains "mywebsite.com" }
{
HTTP::header insert X-Continuation-Origin "https://mywebsite.com"
HTTP::header insert X-Widget-Key "<YOUR_WIDGET_KEY>"
HTTP::header replace Host "surfly.com"
}
}
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.
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
}
]
}
You can also update these settings in the Surfly dashboard
When you check your continuation point status page again, it should look like this: