Marvin auth kit

This marvin-auth module provides easy implementation with the backend authention module written bij Stijn Van Looy.

Getting started

Installation

Install marvin-auth-kit:

yarn add marvin-auth-kit

Fetch and configure instance

All authentication methods are available on the auth object. Import and configure the package, if needed!

Default config is to connect to the current domain and /auth-api path

import { auth } from 'marvin-auth-kit';

// configure auth instance
auth.config({
  url: 'authserver.vito.be',
  port: 443,
  secure: true,
  path: '/auth',
});

// validate backend compatiblity
auth.validateCompatibility();

Have fun

Now you can have fun with authentication:

auth.login(‘username’, ‘password’);
const isLoggedIn = await auth.isAuthenticated;
auth.applyInterceptors( { AxiosStatic instance } );
auth.ejectInterceptors( { AxiosStatic instance } );
auth.refresh();
auth.logout();

Available API

Config

Set and read the configuration of the package

import { config } from 'marvin-auth-kit';

//Sets the config of the auth package
config.set({ ConfigObject });
//Gets the parsed config of the auth package
config.get();

//Example config object
{
  port: 443,
  path: '/auth',
  url: 'authentication.server.vito.be',
  secure: true,
}

//get the config of the auth server, only available for root users
config.server();
//Sets the config of the auth server, only available for root users
config.serverSet({ ServerConfigObject });

E-Mail

Use this module to change the e-mail of the current logged in user, this must be done by a request with is validated by sending a token to that e-mail.

import { email } from 'marvin-auth-kit';

//Request an email change of the logged in user
email.request(email);
//Confirms the email change ( Token is send to the email address provided)
email.confirm(token);

Password

Change the password of a user, or the logged in user. Validation occurs by sending an email to the user.

import { password } from 'marvin-auth-kit';

//Change the password of the logged in user
password.change(newPassword);

//Request an password change of the logged in user
password.request(email);
//Confirms the password change ( Token is send to the email address of the user)
password.confirm(token, newPassword);

Register

Request a new user account for the application, this must be allowed on the server side!

import { register } from 'marvin-auth-kit';

//Request a new user account
register.request(email, password);

//Request a new user account, with metadata. This must be an object
register.request(email, password, metadata);

//Confirms the registration ( Token is send to the email address of the user)
register.confirm(token);

Forgot password

Request a new password for a user

import { reset } from 'marvin-auth-kit';

//Request a reset password link, only available for root users
reset.request(id);

//Set a new password ( Token is send to the email address of the user)
reset.confirm(token, newPassword);

User management

Manage the user base, create, update and delete users. Use users.update to assign new roles to a user.

import { users } from 'marvin-auth-kit';

users.create({ UserObject });
users.get({ UserObject } || id);
users.query({ email, role, enabled, offset, limit, sort, metadata });
users.update({ UserObject });
users.delete({ UserObject } || id);

User Query: metadata

optional, by default no metadata filtering is applied

A metadata filter contains 2 parts separated by a ~ sign (path~pattern)
The path part is the json path in the metadata object, field names are separated by a . sign (level1field.level2field.level3field)
The pattern part uses "database" syntax:

• % = 0, 1, or more characters;
• _ = 1 character

Note that the json fields nor the patterns can contain the used separators (. ~), if they do the metadata filtering won't work (as expected)

Metadata management

Manage your metadata: get, update and delete your metadata Allows you to manage the metadata of the authenticated user.

import { metadata } from 'marvin-auth-kit';

metadata.get<MetdataObject>();
metadata.update<MetdataObject>({ MetdataObject });
metadata.delete();

Role management

Manage the roles: create, update and delete roles

import { roles } from 'marvin-auth-kit';

roles.create({ RoleObject });
roles.query({ offset, limit });
roles.update({ RoleObject });
roles.delete({ RoleObject } || id);

Interceptors

The tokens are automatically added to each axios instance after login. Incase you have multiple instances you can attach interceptors to it.

import axios from 'axios';
import { auth } from 'marvin-auth-kit';

const _privateInstance = axios.createInstance();

//apply the tokens
auth.applyInterceptors(_privateInstance);

//Remove the tokens incase clean up is needed!
auth.ejectInterceptors(_privateInstance);

Guards

PrivateGuard

You can use this component to guard your route with login, the component will check if the user is still logged in.
If they are still logged in it will show the component passed,
else it will redirect the user to /login, by default

It's possible that the component will refresh the tokens, in this case it will show the loader.

import { PrivateGuard } from 'marvin-auth-kit';

<Route
  path="/"
  element={
    <PrivateGuard redirectTo="/login" loader={<FullScreenCircularProgress />} />
  }
>
  <Route path="/admin" element={<SomeProtectedPage />} />
</Route>;

LoginGuard

You can use this component inconjunction of the login route, the component will check if the user is still logged in.
If they are still logged in it will redirect to the next page and skip the login process,
else it will show the component passed, this should be a component containing the login form

It's possible that the component will refresh the tokens, in this case it will show the loader.

import { LoginGuard } from 'marvin-auth-kit';

<Route
  path="/login"
  element={
    <LoginGuard redirectTo="/app" loader={<FullScreenCircularProgress />} />
  }
>
  <Route index element={<LoginLayout />}>
    <Route index element={<LoginPage />} />
  </Route>
</Route>;