Cookie Tracking¶
Cookie tracking identifies and tracks WAMP-over-WebSocket client connections using HTTP cookies.
Cookie tracking can be enabled on WebSocket-Transport and Web-Transport Services . It is not available on other transport types such as RawSocket.
While enabling cookie tracking is a prerequisite for cookie-based WAMP authentication, it can be used without authentication.
How it works¶
Cookie tracking is backed by a configurable cookie store. Currently we have two types of store:
memory-backed
file-backed
In the future, we’ll have an LMDB backed cookie store as well.
The stored information for a cookie includes the cookie ID as well as authentication information (see Cookie Authentication).
With a memory-backed cookie store, cookies are stored in in-memory objects, and, obviously, those cookies will be gone after stopping Crossbar.io
With a file-backed cookie store, cookies are stored in an append-only, on-disk file.
Cookie Tracking without Authentication¶
Cookie tracking can be enabled without using cookie-based authentication as well.
This is the case when
no authentication is configured at all
only anonymous authentication is configured
only non-cookie based authentication is configured
With 1) and 2) and cookie tracking enabled, Crossbar.io will
automatically use the cookie ID as the authentication ID (authid
)
for the client.
This way, you still can identify clients across reconnects using
WAMP authid
. Without cookies, in case of 1) and 2), a WAMP client
will get a random authid
each time it connects.
On the other hand, with 3), the authentication ID (authid
) still
comes from the respective authentication method used.
Cookie Tracking with Authentication¶
Please see Cookie Authentication.
Configuration¶
The following parameters are all optional and shared between different backing stores:
option |
description |
---|---|
name |
The field name where Crossbar.io will store its (random) tracking ID within the Cookie set. The default is “cbtid”. Must match the regular expression “^[a-z][a - z 0 - 9 _]+$” . |
length |
The length of the value for the tracking ID. The default is 24 (which amounts to 144 bits of randomness). The default should be large enough to reduce the collision probability to essentially zero. Must be between 6 and 64. |
max_age |
The maximum Cookie lifetime in seconds. The default is 1 day. Must be between 1 second and 10 years. |
store |
A dictionary with cookie store configuration (see below). |
The store
is a dictionary with the following attributes for a memory-backed cookie store:
attribute |
description |
---|---|
type |
Must be “memory”. |
and for a file-backed cookie store:
attribute |
description |
---|---|
type |
Must be ”file” . |
file name |
Either an absolute path or a relative path (relative to the node directory) |
Examples¶
To configure a memory-backed cookie store:
{
"transports": [
{
"type": "web",
"endpoint": {
"type": "tcp",
"port": 8080
},
"paths": {
"/": {
"type": "static",
"directory": "../web"
},
"ws": {
"type": "websocket",
"cookie": {
"name": "cbtid",
"length": 24,
"max_age": 864000,
"store": {
"type": "memory"
}
}
}
}
}
]
}
To configure a file-backed cookie store:
{
"transports": [
{
"type": "web",
"endpoint": {
"type": "tcp",
"port": 8080
},
"paths": {
"/": {
"type": "static",
"directory": "../web"
},
"ws": {
"type": "websocket",
"cookie": {
"name": "cbtid",
"length": 24,
"max_age": 864000,
"store": {
"type": "file",
"filename": "cookies.dat"
}
}
}
}
}
]
}
In above example, the cookie store would reside in
.crossbar/cookies.dat
for a default node directory.
Note that the cookie file is “growing forever”. There is no purging whatsoever, as the file is written append-only. The LMDB cookie store will provide a more advanced store.