marvin-auth-kit
v5.2.10
Published
Javscript authentication kit
Downloads
467
Readme
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 });
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>;