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.
Email and password authentication requires the
COLLAB_KEY environment variable to be set. Read more here
#Token based authentication
Token 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 works
You 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.
This 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.
#Email and password authentication
Email 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 works
To 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!
The 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.
Both types of authentication functions accept
context as a parameter.
See this guide for more information on context.
If 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.