Changing browser library from utf-8 string encode/decode to b64Url encode/decode of user Id is not well described

[bschick]

Topic

While the shift to automatically create random user ids and transport them as a b64Url makes sense, and I'm sure is easier for new systems, the impact to existing systems was not well described. Perhaps the changelog could be updated to describe how to make old v9 and new v10+ browser clients co-exist.

Background

My system already created user ids as random 32 byte Uint8Array values and then converted to b64Url strings. While updating SimpleWebAuthn, I will have a v10+ server and both v9 and v10+ browser clients in the wild that will have SimpleWebAuthn versions encoding/decoding user ids differently, requiring workarounds.

It is a given that v9 clients will have stored the user id by encoding with TextEncoder().encode(), and this will at some point be read by an upgraded v10+ client decoding with bufferToBase64(). Its also possible that v9 clients will read an user stored by a v10+ client given that we do progressive client updates. And browsers that started with v10+ clients will read their own stored values and never those of v9.

Workaround

For me, to update the server to v10+ and have both v9 and v10+ browser clients running in the wild, the best solution seems to be to always transport base64Url encoded user ids on the wire (as I'd done with v9 browser and server). Then to maintain compatibility, v10+ browser clients will do the following:

• To maintain consisted user id representation sent to navigator.create(), v10+ clients will do something like the following before calling startRegistration() so that the b64ToBuffer() call within startRegistration produces a Uint8Array of b64URL strings (as occured under v9)

      const idBytes = new TextEncoder().encode(optionsJson.user.id);
      optionsJson.user.id = bytesToBase64(idBytes);

• To maintain consisted user id representation coming out of navigator.get(), V10+ browser clients will do something like the following after calling startAuthentication() to convert the result of the bufferToB64() within startAuthentication to an actual b64Url string of the original user id.

      const handleBytes = base64ToBytes(startAuth.response.userHandle!);
      startAuth.response.userHandle = new TextDecoder("utf-8").decode(handleBytes);

In the end, not too difficult, but it took more time and effort to upgrade than it should have. A better approach may have been to leave the browser library with UTF8 encode/decode. That would have preserved compatible with v9 and worked fine the v10+ server's automatic user ids sent as base64url. Small cost of a few extra bytes to store the b64Url string as encoded UTF8.