Authentication documentation: `authCallback` and Auth Token tutorial for javascript

[ben-xD]

I couldn’t find any documentation or example code on using authCallback properly (existing solutions use authUrl), but finally figured it out (after juggling it over 2 days while battling with other issues cors, webworkers/ cloudflare workers), it turns out to be quite simple, though there are many ways to get it wrong, leading to unhelpful error messages. I found that the docs explain the high level overview, and the first part of the code required, but I wish there were more code examples.

I think it would be nice to add something like this (though you may choose to improve it) to the auth docs (2.1 Ably TokenRequest is created by your servers and passed to clients). The code lives in this file https://github.com/ben-xD/Club/blob/fdf5dd336b197ac43c70c87cb58e7afc49f3f7d2/web/public/ts/Messaging.ts#L52

            this.ablyClient = new Realtime({
                authCallback: async (data, callback) => {
                    try {
                        const tokenRequest = // Get your token request from your backend via a http request
                        callback(null, tokenRequest)
                    } catch (e) {
                        callback(e, null)
                    }
                }
            })

TLDR:

• I propose adding more detail to using authCallback docs to https://ably.com/documentation/core-features/authentication#token-request-process
• Add authCallback as an option for javascript clients under each programming language that has js clients: https://ably.com/tutorials/token-authentication
• Extra suggestion: I found references to testing-only code quite confusing": e.g. The last of those (providing a literal token or tokenDetails) is mostly only used for testing. and just having the happy production path documentation working perfectly would be great.

┆Issue is synchronized with this Jira Task by Unito

[lmars]

Just to add an extra data point, an example of using authCallback can be found in the Serverless Auth Example I wrote recently, specifically in lambda/web/app.js

[paddybyers]

Can you also say what the unhelpful error messages were?

[tbedford]

@ben-xD Thanks for this. I also did some initial playing around with auth callback here. We haven't had time to write this up yet, but it's on the todo list. Thanks for raising!

[ben-xD]

Can you also say what the unhelpful error messages were?

Yep, here is 1 warning I've just reproduced:

• When I added a TokenRequest (as according to the docs) as the AuthOptions.token parameter, I got an error message about token being undefined. Now it turns out me overriding the typescript warnings for that was wrong, because ably-js simply didn't implement passing TokenRequest as a token: https://github.com/ably/ably-js/issues/607 It would have been good to be warned that TokenRequest is not implemented in ably-js. I was confused because I thought constructing Ably.Rest or Ably.Realtime requires authentication (a token) passed as an AuthOption, even if authUrl and authCallback was being used. It turns out, using just authCallback is enough.

• In another case, when I passed authCallback in the options, I got an error, roughly saying: key, authUrl or authCallback was not defined. I can't reproduce this now though.

@owenpearson and I had a video call trying to fix this after the NTK, and he suggested using authUrl, but that got me thinking we should document how to use authCallback, since "in case of non-web clients, authCallback is the recommended strategy." source: docs