Looks like it's easy to add custom HTTP headers to your websocket client with any HTTP header client which supports this, but I can't find how to do it with the web platform's WebSocket API.
Anyone has a clue on how to achieve it?
var ws = new WebSocket("ws://example.com/service");
Specifically, I need to be able to send an HTTP Authorization header.
Updated 2x
Short answer: No, only the path and protocol field can be specified.
Longer answer:
There is no method in the JavaScript WebSockets API for specifying additional headers for the client/browser to send. The HTTP path ("GET /xyz") and protocol header ("Sec-WebSocket-Protocol") can be specified in the WebSocket constructor.
The Sec-WebSocket-Protocol header (which is sometimes extended to be used in websocket specific authentication) is generated from the optional second argument to the WebSocket constructor:
var ws = new WebSocket("ws://example.com/path", "protocol");
var ws = new WebSocket("ws://example.com/path", ["protocol1", "protocol2"]);
The above results in the following headers:
Sec-WebSocket-Protocol: protocol
and
Sec-WebSocket-Protocol: protocol1, protocol2
A common pattern for achieving WebSocket authentication/authorization is to implement a ticketing system where the page hosting the WebSocket client requests a ticket from the server and then passes this ticket during WebSocket connection setup either in the URL/query string, in the protocol field, or required as the first message after the connection is established. The server then only allows the connection to continue if the ticket is valid (exists, has not been already used, client IP encoded in ticket matches, timestamp in ticket is recent, etc). Here is a summary of WebSocket security information: https://devcenter.heroku.com/articles/websocket-security
Basic authentication was formerly an option but this has been deprecated and modern browsers don't send the header even if it is specified.
Basic Auth Info (Deprecated - No longer functional):
NOTE: the following information is no longer accurate in any modern browsers.
The Authorization header is generated from the username and password (or just username) field of the WebSocket URI:
var ws = new WebSocket("ws://username:[email protected]")
The above results in the following header with the string "username:password" base64 encoded:
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
I have tested basic auth in Chrome 55 and Firefox 50 and verified that the basic auth info is indeed negotiated with the server (this may not work in Safari).
Thanks to Dmitry Frank's for the basic auth answer
ws://username:[email protected] this pattern doesn't work in Safari, but works in chrome, ff –
Malamute WebSocket: Error during WebSocket handshake: Sent non-empty 'Sec-WebSocket-Protocol' header but no response was received error. –
Enmesh Authentication: Bearer TOKEN... just a different header to observe on before allowing the the WS to open up... if anyone needs details on this approach, I can paste my solution as a new answer –
Underthecounter More of an alternate solution, but all modern browsers send the domain cookies along with the connection, so using:
var authToken = 'R3YKZFKBVi';
document.cookie = 'X-Authorization=' + authToken + '; path=/';
var ws = new WebSocket(
'wss://localhost:9000/wss/'
);
End up with the request connection headers:
Cookie: X-Authorization=R3YKZFKBVi
https://example.com/login, and have the response set a cookie on /wss then new WebSocket("wss://example.com/wss") will start its handshake request with the relevant cookie. Note that the devtools might not show the cookie, but it should still be sent. –
Elliellicott ws = new WebSocket("wss://example.com/wss?csrftoken=<token>") –
Atone example.com/login return a Set-Cookie: Session=xyz123. Once example.com has a session cookie associated with it, new WebSocket("wss://example.com/wss/") will send the Session cookie along with the handshake. As Declan points out, though, this can lead to hijacking. If you control the backend, it'd be better to send credentials over the socket connection. –
Elliellicott Note that the devtools might not show the cookie, but it should still be sent. I've confirmed that the dev-tools do not show these cookies on websocket requests/connections! Annoying as this caused a lot of time lost thinking I was doing something wrong. –
Tyre Here's a quick summary of the situation for the weary traveller stumbling upon this in 2024, and probably for a very long time after that.
Nothing has changed in the 12(!) years since this question was opened. The JavaScript WebSocket API is abandoned by all browser vendors (although the implementations do occasionally get updates), and the new specs (WebSocket Stream and WebTransport) are nowhere close to materialization. What this all means is that WebSockets are still widely used, no replacement for the broken API exists despite it being called "legacy" 7 years ago, and the problems outlined in the question are as annoying as ever, if not more.
The options for dealing with the situation (spoiler, #5 or #6 is what you want):
Described in https://devcenter.heroku.com/articles/websocket-security. The client is expected to make an authenticated request to a dedicated end point that will generate and persist a short-lived token that will also be sent to the client. The client then returns this token as a URL param when opening a WebSocket. The server can validate it and accept/reject the protocol upgrade. This requires the server to implement a completely custom and stateful authentication mechanism specifically for WebSockets, which is a bridge too far in many scenarios.
You open a WebSocket without authenticating, then you send your auth information over WebSocket prior to doing anything else. This in theory sounds logical (and is advised by the browser vendors), but falls apart given just a cursory thought. The server is made to implement an awkward, highly stateful and entirely custom authentication mechanism that doesn't play well with anything else, on top of either having to maintain a persistent connection with a client who refuses to authenticate, leaving a door wide open for denial of service attacks, or getting into a whole new rabbit whole of enforcing rigorous time outs to prevent malicious behavior.
Not as terrible as it sounds, as long as SSL is enforced (wss:// not ws://) because WebSocket URLs are special and don't get saved in browser history or similar. On top of that, access tokens are normally short lived, so that also mitigates the danger. But. The server will very likely log the URL anyway at some point. Even if your server application doesn't, the framework or the (cloud) host probably will. Additionally, if you have to pass ID tokens around (like Firebase is wont to do), you might trip up on various URL length limitations as ID tokens get huge.
Don't. WebSockets are not subject to same-origin policy (because apparently every little thing about WebSockets has to be awful) and allowing cookies would leave you wide open to CSRF attacks. Fixing this using CSRF tokens is described e.g. here but it is more difficult than taking any other approach from this list, so it is simply not even worth considering.
Sec-WebSocket-ProtocolSince the only header a browser will let you control is Sec-WebSocket-Protocol, you can abuse it to emulate any other header. Interestingly (or rather comically), this is what Kubernetes is doing. In short, you append whatever you need for authentication as an extra supported subprotocol inside Sec-WebSocket-Protocol:
var ws = new WebSocket("ws://example.com/path", ["realProtocol", "yourAccessTokenOrSimilar"]);
Then, on the server, you add some sort of middleware that transforms the request back to its saner form before passing it further into the system. Terrible, yes, but so far the best solution. No tokens in the URL, no custom authentication save for the little middleware, no extra state on the server needed. Do not forget to include the real subprotocol, as various tools will reject a connection without one.
For a good number of cases, SSE might be a decent replacement. The browser EventSource API is as horribly broken as WebSocket (it can't send anything but GET requests, can't send headers either despite being regular HTTP), but! it can be easily replaced by fetch which is, for a change, a saner API. This approach works well as an alternative to WebSocket in e.g. GraphQL subscriptions, or really anywhere where full duplex isn't mandatory. And that likely covers most scenarios. RSocket could theoretically also be an option, but seeing how it's implemented via WebSockets in the browser, I don't think it actually resolves anything, but I didn't look into it deep enough to say with absolute certainty.
map directive and add_header (or proxy_set_header). Something like: map $http_sec_websocket_protocol $extracted_token { "~realProtocol(?<t>.*)" $t; } to get the token out of the subprotocol header, and then add_header Authorization "Bearer $extracted_token"; to recreate the usual auth header. I've never tried any of this, so take it as a guideline more than a definitive answer. Not sure if there's anything Kubernetes specific to worry about. –
Lacasse Sending Authorization header is not possible.
Attaching a token query parameter is an option. However, in some circumstances, it may be undesirable to send your main login token in plain text as a query parameter because it is more opaque than using a header and will end up being logged whoknowswhere. If this raises security concerns for you, an alternative is to use a secondary JWT token just for the web socket stuff.
Create a REST endpoint for generating this JWT, which can of course only be accessed by users authenticated with your primary login token (transmitted via header). The web socket JWT can be configured differently than your login token, e.g. with a shorter timeout, so it's safer to send around as query param of your upgrade request.
Create a separate JwtAuthHandler for the same route you register the SockJS eventbusHandler on. Make sure your auth handler is registered first, so you can check the web socket token against your database (the JWT should be somehow linked to your user in the backend).
HTTP Authorization header problem can be addressed with the following:
var ws = new WebSocket("ws://username:[email protected]/service");
Then, a proper Basic Authorization HTTP header will be set with the provided username and password. If you need Basic Authorization, then you're all set.
I want to use Bearer however, and I resorted to the following trick: I connect to the server as follows:
var ws = new WebSocket("ws://[email protected]/service");
And when my code at the server side receives Basic Authorization header with non-empty username and empty password, then it interprets the username as a token.
wss://user:[email protected]/ws) and got no Authorization header on the server side (using Chrome version 60) –
Beshore wss://user:pass@host format. Is this not supported by browsers, or is something going wrong with the handshake? –
Panicstricken http://username:[email protected] is depreciated. developer.mozilla.org/en-US/docs/Web/HTTP/Authentication. Maybe thats the reason it does not work with websockets either! –
Deathwatch You can not send custom header when you want to establish WebSockets connection using JavaScript WebSockets API.
You can use Subprotocols headers by using the second WebSocket class constructor:
var ws = new WebSocket("ws://example.com/service", "soap");
and then you can get the Subprotocols headers using Sec-WebSocket-Protocol key on the server.
There is also a limitation, your Subprotocols headers values can not contain a comma (,) !
Sec-WebSocket-Protocol header as alternate to the Authorization header? –
Biotin You cannot add headers but, if you just need to pass values to the server at the moment of the connection, you can specify a query string part on the url:
var ws = new WebSocket("ws://example.com/service?key1=value1&key2=value2");
That URL is valid but - of course - you'll need to modify your server code to parse it.
For those still struggling in 2021, Node JS global web sockets class has an additional options field in the constructor. if you go to the implementation of the the WebSockets class, you will find this variable declaration. You can see it accepts three params url, which is required, protocols(optional), which is either a string, an array of strings or null. Then a third param which is options. our interest, an object and (still optional). see ...
declare var WebSocket: {
prototype: WebSocket;
new (
uri: string,
protocols?: string | string[] | null,
options?: {
headers: { [headerName: string]: string };
[optionName: string]: any;
} | null,
): WebSocket;
readonly CLOSED: number;
readonly CLOSING: number;
readonly CONNECTING: number;
readonly OPEN: number;
};
If you are using a Node Js library like react , react-native. here is an example of how you can do it.
const ws = new WebSocket(WEB_SOCKETS_URL, null, {
headers: {
['Set-Cookie']: cookie,
},
});
Notice for the protocols I have passed null. If you are using jwt, you can pass the Authorisation header with Bearer + token
Disclaimer, this might not be supported by all browsers outside the box, from the MDN web docs you can see only two params are documented. see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#syntax
Totally hacked it like this, thanks to kanaka's answer.
Client:
var ws = new WebSocket(
'ws://localhost:8080/connect/' + this.state.room.id,
store('token') || cookie('token')
);
Server (using Koa2 in this example, but should be similar wherever):
var url = ctx.websocket.upgradeReq.url; // can use to get url/query params
var authToken = ctx.websocket.upgradeReq.headers['sec-websocket-protocol'];
// Can then decode the auth token and do any session/user stuff...
The recommended way to do this is through URL query parameters
// authorization: Basic abc123
// content-type: application/json
let ws = new WebSocket(
"ws://example.com/service?authorization=basic%20abc123&content-type=application%2Fjson"
);
This is considered a safe best-practice because:
In my situation (Azure Time Series Insights wss://)
Using the ReconnectingWebsocket wrapper and was able to achieve adding headers with a simple solution:
socket.onopen = function(e) {
socket.send(payload);
};
Where payload in this case is:
{
"headers": {
"Authorization": "Bearer TOKEN",
"x-ms-client-request-id": "CLIENT_ID"
},
"content": {
"searchSpan": {
"from": "UTCDATETIME",
"to": "UTCDATETIME"
},
"top": {
"sort": [
{
"input": {"builtInProperty": "$ts"},
"order": "Asc"
}],
"count": 1000
}}}
to all future debugger - until today i.e 15-07-21
Browser also don't support sending customer headers to the server, so any such code
import * as sock from 'websocket'
const headers = {
Authorization: "bearer " + token
};
console.log(headers);
const wsclient = new sock.w3cwebsocket(
'wss://' + 'myserver.com' + '/api/ws',
'',
'',
headers,
null
);
This is not going to work in browser. The reason behind that is browser native Websocket constructor does not accept headers.
You can easily get misguided because w3cwebsocket contractor accepts headers as i have shown above. This works in node.js however.
I've tried these two approaches and neither worked, hopefully this will save you time:
What I have found works best is to send your jwt to the server just like a regular message. Have the server listening for this message and verify at that point. If valid add it to your stored list of connections. Otherwise send back a message saying it was invalid and close the connection. Here is the client side code. For context the backend is a nestjs server using Websockets.
socket.send(
JSON.stringify({
event: 'auth',
data: jwt
})
);
Client Side: No
Server Side: Yes
All you need to do is attach the header to the websocket after auth on the server. All future communication with that websocket will have that auth token.
Server Environment: Bun JS / Elysia
Example:
const app = new Elysia({
websocket: {
idleTimeout: 180
}
});
app.ws("/ws", {
message: async (ws, message) => {
// message = { action: 'LOGIN', payload: { username: 'bob', password: 'iAmB0B' }}
if(message.action === 'LOGIN') {
// Do auth stuff
const token = await callAuth(message.payload);
if(token) {
ws.data.headers['authorization'] = `Bearer ${token}`;
}
} else {
// Verify Auth - All future calls with this socket will have this auth.
const auth = ws.data.headers['authorization']; // `Bearer ${token}`
}
}
});
References:
Bun JS Websockets: https://bun.sh/docs/api/websockets
Elysia JS Websockets: https://elysiajs.com/patterns/websocket.html
My case:
www.mycompany.com/api/ws...localhost:8000). Setting document.cookie = "sessionid=foobar;path=/" won't help as domains don't match.
The solution:
Add 127.0.0.1 wsdev.company.com to /etc/hosts.
This way your browser will use cookies from mycompany.com when connecting to www.mycompany.com/api/ws as you are connecting from a valid subdomain wsdev.company.com.
You can pass the headers as a key-value in the third parameter (options) inside an object. Example with Authorization token. Left the protocol (second parameter) as null
ws = new WebSocket(‘ws://localhost’, null, { headers: { Authorization: token }})
Edit: Seems that this approach only works with nodejs library not with standard browser implementation. Leaving it because it might be useful to some people.
Technically, you will be sending these headers through the connect function before the protocol upgrade phase. This worked for me in a nodejs project:
var WebSocketClient = require('websocket').client;
var ws = new WebSocketClient();
ws.connect(url, '', headers);
headers should be either null or an object specifying additional arbitrary HTTP request headers to send along with the request." from WebSocketClient.md; therefore, the headers here is HTTP layer. –
Julee connect method, described as connect(requestUrl, requestedProtocols, [[[origin], headers], requestOptions]), i.e. the headers should be provided along with requestOptions, for example, ws.connect(url, '', headers, null). Only the origin string can be ignored in this case. –
Julee ws nodejs client –
Ingraham © 2022 - 2024 — McMap. All rights reserved.
connectrequest. I'm using Django channels on the back end and I've designed it to accept the connection onconnectevent. it then sets an "is_auth" flag in thereceiveevent (if it sees a valid auth message). if the is_auth flag isn't set and it's not an auth message then it closes the connection. – Juieta