User authentication
In order to use the collab service, users must be signed in and authenticated with the server.
The server supports three methods of authentication: token based authentication, email and password authentication, and anonymous authentication.
In most cases, you will want to use token based authentication, as it is the most flexible.
Read both authentication methods below and choose what one works best for you.
Note
Email and password authentication requires the COLLAB_KEY
environment variable to be set. Read more here
#
Token based authenticationToken based authentication uses an authentication token that is passed between the server and client. The token is used to validate the users session.
In this flow, you must provide us with a function that accepts an authentication token, and returns a user id. This leaves the token generation and validation totally up to you, making this the most flexible option.
#
How it worksYou must pass a getUserFromToken function to the server constructor. This function will accept a token, context, and the cookies from the request (as an object), and must return either an object with the users id if the token is valid, or null otherwise.
On the client, call the loginWithToken function, and pass in the authentication token that your application is using. This token will be passed into the getUserFromToken
token for decoding.
#
ExampleThis example shows one possible way you could handle this flow using JWT. Keep in mind you do not have to use JWT, this is just one possible case.
Server
Client
#
Email and password authenticationEmail an password authentication is similar to token authentication, except the collab server handles the token generation, and instead you just verify a email and password.
Once a persons email and password is verified, we generate a JWT and set it as a cookie. This cookie is used to authenticate the user in future requests.
To use this method, an environment variable called COLLAB_KEY
must be set to a string. This will be the secret key we use to encode the JWT. Make sure to not share this string with anyone. Treat it like a password!
#
How it worksTo use email and password authentication, you must pass a verifyPassword function to the constructor. The function accepts an email, password, and context and must return a promise that resolves to a boolean indicating if the email and password are valid.
Now on the client, you call the loginWithPassword function with the users email and password. This gets passed in to your verifyPassword
function on the server, and if returns true, the user is logged in!
#
ExampleServer
Client
#
Anonymous authenticationThe Collaboration system allows you to sign in users anonymously (no username or password). There is no additional server config required for this feature.
To log in a user anonymously on the client, see this guide.
#
ContextBoth types of authentication functions accept context
as a parameter.
See this guide for more information on context.
#
TroubleshootingIf you are experiencing issues setting up user authentication, we recommend enabling authentication specific debug logs on both the server and client:
Once enabled, logs related to authentication can be seen in both your server and client consoles. These logs can provide insight into what might be going wrong.