In order to use the collab service, users must be signed in and authenticated with the server.
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 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.
You must pass a getUserFromToken function to the server constructor. This function will accept a token, and must return either an object with the users id if the token is valid, or null otherwise.
When the user signs in with your application, an authentication token is set by your server (usually in a cookie). This is the token you will use to sign in. The default cookie name is
wv-collab-token, you can also overwrite this cookie name by passing
jwtCookieName to the server constructor:
Once the user is logged in to your system and has a token, use the you call the loginWithToken function from the client module, and pass in the token your server generated.
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 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!
To use email and password authentication, you must pass a verifyPassword function to the constructor. The function accepts a email and password, 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!