Auth Service

The Auth Service is responsible for user authentication and the management of user sessions as well as user information assigned to the user account.

Overview

The Auth Service is based on Express.js and TypeScript. The authentication logic was implemented using the Better-Auth library. This allows the service to be connected to other OAuth2 and OpenID Connect compatible identity providers with little effort. Additionally, there is the possibility to install plugins to use further features such as Two-Factor Authentication. Currently, users can log in and authenticate using an Email/Password combination or via a Github or Google account.

Features

Login and Registration of users using Email/Password combination
Login and Registration of users via OAuth2 (Google, Github)
Management of user sessions (as well as creating sessions on multiple devices)
Password reset via Email
Email verification after registration

Architecture

Technologies

Framework: Express.js
Language: TypeScript
Database: PostgreSQL
Cache: Redis
Authentication Library: Better-Auth
ORM: Drizzle Kit

Structure

src/
├── db/        # Contains database models and adapters to access the database
├── lib/        # Contains library functions and initializations
├── middleware/        # Contains Express middleware functions
├── models/        # Providing classes and interfaces
├── types/        # Providing types and
├── utils/        # Contains helper functions and utility modules
├── auth.ts        # Instantiation and configuration of the Better-Auth library
├── config.ts        # Configuration file for the service
├── server.ts        # Main entry point of the application

API Documentation

The documentation of Better-Auth can be viewed here.

Method	Path	Description
GET	`/health`	Health Check Endpoint

Development

Start service locally

# Install dependencies
npm install
 
# Copy environment variables
cp .env.example .env
 
# Start in development mode
npm run dev

Linting & Formatting

# Check linter
npm run check
 
# Automatically fix linter errors
npm run check:write
 
# Format code
npm run format

Configuration

Environment Variables

Variable	Description	Default Value
`DATABASE_URL`	Connection string to the database	-
`REDIS_URL`	Connection string for Redis cache	-
`TRUSTED_ORIGINS`	Comma-separated list of trusted origins for CORS	-
`AUTH_SECRET`	Random string to secure authentication	-
`BASE_URL`	Host URL of the service to e.g. generate links in emails correctly	-
`BACKEND_HOST_URL`	Host URL under which the backend is reachable	-
`RESEND_API_KEY`	Resend API to send emails via Resend	-
`LOG_LEVEL`	Log level for the application	`info`
`LOG_HIDE_META`	Whether to hide metadata in logs	`false`
`GITHUB_CLIENT_ID`	GitHub OAuth Client ID	-
`GITHUB_CLIENT_SECRET`	GitHub OAuth Client Secret	-
`GOOGLE_CLIENT_ID`	Google OAuth Client ID	-
`GOOGLE_CLIENT_SECRET`	Google OAuth Client Secret	-
`PORT`	Port on which the service runs	`8080`
`LOKI_URL`	URL for the Loki logging service	`http://loki:3100`
`TEMPO_URL`	Ingest URL for the Tempo tracing service	`http://tempo:4318`

Logs & Traces

The environment variable TEMPO_URL is only required if the server is started with tracing functionality (via instrumentation.js or npm run start:instrumentation) and logs are to be transmitted. If the environment variable LOKI_URL is not set, logs will be output "locally" to the console.

OAuth

The callback URLs for the OAuth providers must be configured as follows:

Local

http://localhost:8080/api/auth/callback/<PROVIDER> # e.g. google, github

Production Environment

https://auth.service/api/auth/callback/<PROVIDER> # e.g. google, github

Database Migrations

The environment variable DATABASE_URL must be set for migrations to be executed.

Database migrations are managed using Drizzle Kit. To create a new migration (for the database), the following command can be used:

npm run db:generate

Using the following command, the migrations can be applied to the database:

npm run db:migrate

Deployment

The service is automatically deployed via a Railway CI/CD pipeline on every push to the main branch. Additionally, there is a Concourse Workflow, which tests the service on every push and builds and publishes a Docker image.

Docker

The service can be containerized and deployed using the Dockerfile in the repository. The following command can be used for this:

docker pull ghcr.io/budgetbuddyde/backend:latest
docker run -d -p 9000:9000 --env-file ./path/to/env/file ghcr.io/budgetbuddyde/backend:latest

Additionally, a docker-compose.yml file is available in the repository, which can be used to start the service locally together with a PostgreSQL and Redis instance.

Railway

BudgetBuddyDE is designed to be easily deployable on Railway.

Dependencies

The Auth Service uses the following internal packages:

Auth Service

On this page