ERP Auth

Manual Installation

Install the package:

pnpm install @hirameki-erp/auth

Database Setup

ERP Auth uses Kysely for database interactions. You need to set up a connection config for Kysely in your application.

Follow the Kysely CLI configuration guide to set up your database connection: Kysely CLI Configuration.

Then, run the auth migration command to create the necessary tables for ERP Auth:

The -c option is required. It should point to your Kysely configuration file that connects to your database.

pnpm exec hirameki-auth migrate:latest -c .config/kysely.config.ts

Migration should create a table named erp_user, erp_account and erp_session tables along with _erp_auth_migrations table and the lock table dedicated for ERP Auth in your database.

Application Setup

Define AUTH_ENDPOINT environment variable in your .env file:

Make sure your application can load environment variables.

AUTH_ENDPOINT="http://localhost:3000/auth"

Call the setup function in your application entry point:

This is necessary to set the base URL for the auth HTTP client.

import { setup as setupErpAuth } from '@hirameki-erp/auth';
setupErpAuth();

Next, setup the HTTP middleware in your Express application:

Make sure to place the ERP Auth middleware before your route handlers and after any parsing middleware like body-parser, cors, cookie-parser, etc.

import { erpAuth } from '@hirameki-erp/auth';

app.use(bodyParser.json());

app.use(erpAuth());

// Your route handlers go here
app.use(errorHandlerMiddleware());

Endpoints

Once the ERP Auth plugin is set up, it exposes the following endpoints:

• POST /auth/login - Login endpoint
• POST /auth/addUser - Add User endpoint
• GET /auth/getUser - Get User endpoint

In most cases, if you don't want to expose the /addUser endpoint publicly, you can disable it for now by creating a custom middleware that restricts access to it in your Express application.

// Disable Add User Endpoint. Place this before erpAuth middleware
app.use('/auth/addUser', (req, res, next) => {
  res.status(404).send('not found');
});

app.use(erpAuth());

API

Erp Auth exposes some utils and Axios HTTP client for making requests to the auth service if needed.

NOTE: The plugin does not export an ORM or database client to interact with the tables created by the migration. You need to set up your own Database client using any other ORM or query builder of your choice to interact with the erp_user, erp_account and erp_session tables.

Http Client

import { api as erpAuthApi } from '@hirameki-erp/auth';

// Add User Endpoint
erpAuthApi.addUser(data)

// Login Endpoint
erpAuthApi.login(data)

// Axios HTTP Client
erpAuthApi.erpAuthHttpClient

Database Schema

Here is a table summarizing the schema for each table defined in the migration:

erp_user

User table for the consumer application to store user profile information fetched from the auth-server. No passwords or sensitive information is stored here, just metadata.

| Column | Type | Constraints / Notes | |-------------|--------------|-----------------------------------------------------------------------------------------------------| | id | varchar(36) | PK, Unique, Not Null, Comment: ID of user from auth-server | | first_name | text | Not Null | | last_name | text | | | email | varchar(320) | Not Null | | image | LONGTEXT | Comment: store profile image as base64 string (192x192 px, transformed by auth-server) | | image_url | text | Comment: External URL hosted by auth server, may be blocked/slow/CORS issues | | createdAt | datetime | Not Null | | updatedAt | datetime | Not Null |

erp_account

A table that contains provider account information for users (Not accepting oauth providers yet.).

Example: a field providerId always defaults to auth-server meaning the account is from our own auth-server. This has accessToken, refreshToken, accessTokenExpiresAt field.

| Column | Type | Constraints / Notes | |----------------------|--------------|-------------------------------------------------------------| | id | varchar(36) | PK, Not Null | | accountId | text | Not Null, Comment: accountId from external provider | | providerId | text | Not Null, Comment: providerId from external provider | | userId | varchar(36) | Not Null, FK to erp_user.id | | accessToken | text | | | refreshToken | text | | | accessTokenExpiresAt | datetime | | | refreshTokenExpiresAt| datetime | | | scope | text | | | createdAt | datetime | Not Null | | updatedAt | datetime | Not Null | | deletedAt | datetime | |

erp_session

The session table store session info of users logged in from the consuming application to the auth-server. This manages session of the user on the consuming application side, we can safely assume that once the user is on the erp_user table, they are authenticated/registered, even if the accessToken in the erp_account table has expired (only for when providerId is from our own auth-server).

This way this app can have it's own session management.

| Column | Type | Constraints / Notes | |------------|--------------|----------------------------| | id | varchar(36) | PK, Not Null | | userId | varchar(36) | Not Null, FK to erp_user.id| | expiresAt | datetime | Not Null | | createdAt | datetime | Not Null |