proposal: add subprotocol for token-authenticated websockets

[minrk]

follows kubernetes' example of smuggling the token in the subprotocol itself. Maybe not great, but solves our problem and is simple and appears to work.

To authenticate websockets via new mechanism, clients should:

ws = new WebSocket(wss://..., ['v1.token.websocket.jupyter.org', `v1.token.websocket.jupyter.org.${token}`, ...])

which sets the header:

Sec-WebSocket-Protocol: v1.token.websocket.jupyter.org, v1.token.websocket.jupyter.org.abc123

The response will have the header:

Sec-WebSocket-Protocol: v1.token.websocket.jupyter.org

This is transparently ignored if unrecognized, so fully backward compatible for both clients and servers, and fully compatible with specifying other subprotocols, etc.

This is transparently ignored if unrecognized by servers and most clients, but at least Chrome checks that the server's response includes one of the requested subprotocols if any are specified. For backward-compatibility, a client must try with subprotocols, then retry without them. This is the reason for the v1.token.websocket.juptyer.org subprotocol in addition to the protocol including the token itself.

This seems like the simplest path to not sending the token in URL parameters. The alternative of using a handshake message is more complex and protocol-breaking, and further allows clients that never authenticate to hold open connections indefinitely.

Notable difference: kubernetes base64-encodes the token on the end. I haven't done that because negotiating url-safe-base64-without-padding seems like a pain because:

• neither Python nor Javascript actually implement the required unpadded urlsafe-base64 in the standard library
• base64 encoding only makes an already-valid string longer
• While we don't technically specify that tokens must be safe strings in header fields like this, it is always true in practice, so we could without any practical loss. There's a good chance we already have this requirement elsewhere by accident (e.g. we don't escape tokens when passed in URL params).

I think the only question that remains is whether and how servers advertise support for this.

via