Holibob Docs

Auth Service

Holibob's centralised authentication service — handling sign-in, sign-up, MFA, SSO, passkeys, and token management.

Overview

The Auth service is a standalone Next.js application deployed on AWS Amplify. It provides a unified authentication layer for all Holibob consumer-facing and internal applications.

Key capabilities:

  • Email/password sign-in with AWS Cognito
  • Magic link (passwordless) authentication
  • Social sign-in via Google, Facebook (SSO through Cognito)
  • FIDO2/WebAuthn passkey registration and authentication
  • Multi-factor authentication (TOTP)
  • JWT access tokens with HttpOnly refresh token cookies

Architecture

The Auth service consists of:

  • Frontend pages — Server-rendered React pages for sign-in, sign-up, password reset, passkey setup, and MFA verification.
  • API routes — Next.js API handlers that communicate with AWS Cognito, the Holibob database, and Redis for session management.
  • Token service — Mints short-lived JWT access tokens and manages long-lived refresh tokens via HttpOnly cookies.

All secrets (JWT signing key, database credentials, Cognito client secret) are stored in AWS Secrets Manager and loaded at runtime — never inlined at build time.

Authentication Flows

The standard flow for consuming applications:

  1. The consuming app redirects the user to https://auth.holibob.tech/signin?returnUrl=...&origin=...
  2. The user authenticates using their preferred method.
  3. Auth validates credentials against Cognito and the local database.
  4. Auth mints a JWT access token (15-min expiry) and sets a refresh token cookie (30-day expiry).
  5. Auth redirects back to returnUrl?token={JWT}
  6. The consuming app extracts the token and uses it for subsequent API calls.

Token Management

Access tokens are JWTs signed with HS256. They contain the user's ID, email, roles, and organisation context. Tokens expire after 15 minutes.

To refresh an expired token, the consuming app makes a POST /api/refresh request. The refresh token cookie is sent automatically by the browser. If valid, a new access token is returned.