Zooly Auth

Overview

zooly-auth is a self-contained Next.js application that serves as the Single Sign-On (SSO) provider for the entire platform. It handles all authentication and authorization across all apps in the monorepo.

Url: https://auth.zooly.ai

App Details

• App Name: zooly-auth
• Location: apps/zooly-auth
• Framework: Next.js 15
• Port: 3003 (development)

Architecture

The auth app is a special project designed to serve as an SSO for the entire application:

• Cognito Integration: Uses AWS Cognito for SSO authentication
• DynamoDB: Manages user data using DynamoDB (Cognito data is only used for initial values and roles)
• Authentication Flows: Redirect + returnTo flow, and a popup flow for no-redirect login
• Self-contained: Has its own database and doesn't depend on other apps

Key Features

• Single Sign-On (SSO) for all apps
• Cognito-based authentication
• DynamoDB user data management
• Role-based access control

Authentication Flows

The app implements two authentication flows:

1. Redirect flow: apps send unauthenticated users to auth.zooly.ai?returnTo=<original-url> and the auth app redirects them back after login.
2. Popup flow: apps call loginWithPopup() (from the @zooly/auth-client package) to open auth.zooly.ai/popup in a popup window. The popup runs the same email/password and social login flows, then signals success via postMessage and closes itself — the calling window never navigates and re-reads the session from /api/me.

Dependencies

• Next.js 15
• React 19
• AWS SDK for Cognito Identity Provider
• AWS SDK for DynamoDB
• AWS JWT Verify
• Tailwind CSS

Scripts

• dev - Start development server on port 3003
• build - Build for production
• start - Start production server
• lint - Run ESLint

Documentation

For more details on the auth architecture and integration, see:

• Auth Overview
• Authentication Flows
• Client Integration
• Backend Integration