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.
npm install @unologin/node-sdk
or
yarn add @unologin/node-sdk
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.
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,
},
);
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.
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);
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()
We 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
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());
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);
localhostIn 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
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);
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!`);
},
);
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 requireLoginUse 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);
Decide what happens when an authentication error is thrown. This happens if
requireLogin is active and no login token is sentparseLogin is active and an invalid token is sentThe 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'
);
});
Generated using TypeDoc