Node.js library for interfacing with unolog·in.
The full documentation for this package can be found here.
This package also includes express-handlers and lower-level HTTP-handlers for other frameworks.
Bindings for Next.js are provided by the @unologin/next package.
This package only provides server-side code and therefore requires a separate front end.
See @unologin/web-sdk for web-based frontend implementations.
Visit our documentation page for more docs & guides.
Installation
npm install @unologin/node-sdk
or
yarn add @unologin/node-sdk
Typescript
The package includes built-in type declarations. There is no need to install any additional packages.
The below examples will use plain javascript for generality.
Setup
Before using the library, make sure to set up your credentials.
const unologin = require('@unologin/node-sdk');
unologin.setup(
{
// your unolog·in api key goes here
apiKey: process.env.UNOLOGIN_API_KEY,
// domain(s) on which to set cookies
cookiesDomain: process.env.UNOLOGIN_COOKIES_DOMAIN,
},
);
REST API
The library includes bindings for the unolog·in REST API through the exported rest
object.
More elaborate working examples can be found in example/main.js
in this repository.
Getting details for a single user
const unologin = require('@unologin/node-sdk');
// user token may be retrieved using
// userToken = unologin.express.getUserToken(res) in express handlers
// returns Promise<UserDocument> (see types)
// which includes all information the user
// has shared with your app
const user = unologin.rest.getUser(userToken);
Querying users
You can query you app's users using this query schema. Omitting the query will return a cursor for all users.
const unologin = require('@unologin/node-sdk');
// pass an optional query (object or URLSearchParams)
// returns a GetCursor instance which can be used to iterate over users
const cursor = unologin.rest.getUsers(query)
// returns Promise<GetCursorBatch>
// which represents a subset of all users matching the query
// see example/main.js for an example on iterating this way
cursor.nextBatch()
// returns Promise<UserDocument | null>
cursor.next()
// runs the callback function for every
// user matching the query
// returns Promise<void>
cursor.forEach((user) => console.log(user))
// turns the cursor into an array
// this is not recommended for larger queries
// returns Promise<UserDocument[]>
cursor.toArray()
express.js
Usage withWe have built some handlers for you to set up unolog·in on your server with only a few lines of code.
A full working example can be seen in the ./example
directory. Run using
npm run example
yarn run example
Express setup
The next steps are going to assume that you have an express application or router to attach the provided handlers to.
IMPORTANT: Add a cookie-parser before adding any unolog·in handler!
const cookieParser = require('cookie-parser');
app.use(cookieParser());
Testing locally
When working on your local server, you likely won't connect through https
but http
. To be able to still use login cookies, disable the use of secure cookies. The library will refuse to perform this action if process.env.NODE_ENV
is anything but 'development'
.
// IMPORTANT: only do this when testing on your local server!
unologin.express.debug_useSecureCookies(false);
localhost
Important note on In order to make the cookies behave correctly, it is recommended that you use a subdomain of localhost
to access your front- and backend implementations. Most browsers will be able to resolve arbitrary subdomains of localhost
.
Cookies may be rejected by your browser otherwise!
For example:
Server: my-app.localhost:8080
Frontend: my-app.localhost:8081
# then in your .env
UNOLOGIN_COOKIES_DOMAIN=my-app.localhost
Handling the login event
After going through the login/registration steps, your users will be redirected to your login handler. Be sure to register your login handler in the developer dashboard. To handle the login event, add the loginEventHandler
middleware.
app.use('/unologin/login', unologin.express.loginEventHandler);
Custom logic after the login event
Use onLoginSuccess
to add custom synchronous or asynchronous logic to be executed after any successful login.
unologin.express.onLoginSuccess(
function (req, res, user)
{
console.log(`User ${user.asuId} just logged in!`);
},
);
Logout
To log out the user, use the logoutHandler
middleware. Note that the middleware won't emit a response. It is up to you to do that.
app.post(
'/logout',
unologin.express.logoutHandler,
function(req, res)
{
// send a response to terminate the request
res.send('We hope to have you back soon!');
}
);
Alternatively, call logoutHandler
as a function:
app.post('/logout', function(req, res)
{
// same effect as above
unologin.express.logoutHandler(req, res);
// send a response to terminate the request
res.send('We hope to have you back soon!');
});
parseLogin
and requireLogin
Using Use the parseLogin
middleware to parse the login token sent by the user and validate it.
IMPORTANT: parseLogin
does not require a login token to be present!
Use requireLogin
to make sure the user is logged in!
// parsing login token everywhere
app.use('*', unologin.express.parseLogin);
// example of accessing the user data
app.get('/me', function(req, res) =>
{
// keep in mind that `getUserToken` may return null if not logged in
res.send(unologin.express.getUserToken(res))
});
Use the requireLogin
middleware where it is absolutely required for users to be logged in.
IMPORTANT: requireLogin
must be preceeded by parseLogin
!
app.use('/my-personal-photos', unologin.express.parseLogin);
// require your users to be logged in to access this route
app.use('/my-personal-photos', unologin.express.requireLogin);
Error handling (optional)
Decide what happens when an authentication error is thrown. This happens if
-
requireLogin
is active and no login token is sent -
parseLogin
is active and an invalid token is sent
The below implementation is actually the default behavior. If you are fine with the default behavior, you may skip this step.
onAuthError(function(req, res)
{
unologin.express.logoutHandler(req, res);
res.status(401);
res.send(
'Auth error: ' + res.locals.unologin?.msg ||
'unknown error'
);
});