Tessera

OIDC Flow Tester with Retro Terminal UI

Tessera (Latin: token, ticket, piece) - In ancient Rome, tesserae were small tokens used for identification, admission to events, or as proof of membership. The original identity tokens.

Overview

Tessera is a sophisticated OIDC (OpenID Connect) flow testing application with a distinctive retro-futuristic green screen aesthetic inspired by COBOL CICS banking terminals. Built for security engineers, developers, and identity architects to test, validate, and debug OIDC integrations.

Features

• Provider Management: Configure and manage multiple OIDC providers
• Flow Testing: Authorization Code (with PKCE), Implicit, Hybrid, Client Credentials
• Token Inspector: JWT decoder, signature validation, claims viewer
• Session History: Track and analyze test results
• Diagnostics: Connectivity tests, TLS inspection, timing analysis

Tech Stack

• Java 25
• Spring Boot 4.0.1
• Spring Security 7
• PostgreSQL 17
• Thymeleaf + htmx
• Docker Compose

Quick Start

Option 1: Docker (Recommended)

Run everything in Docker with a single command. No Java installation required.

./compose-up-standalone.sh -b

Access at https://localhost:8443

See Docker Production for details.

Option 2: Local Development

For development with hot-reload, run the app locally.

Prerequisites:

• Java 25+
• Docker & Docker Compose (for PostgreSQL)
• Gradle 9.2+ (or use wrapper)

Steps:

# 1. Start PostgreSQL
./compose-up.sh

# 2. Generate certificates (first time only)
./generate-certs.sh

# 3. Build and run
./build-and-run.sh

Access at https://localhost:8443 or https://tessera.local:8443

Docker Standalone (Self-Contained)

Run Tessera entirely in Docker with PostgreSQL and auto-generated SSL certificates.

Quick Start

# Build and start everything
./compose-up-standalone.sh -b

# Access the application
open https://localhost:8443 or https://tessera.local:8443

Docker Commands

Script	Description
compose-up-standalone.sh	Start all services
compose-up-standalone.sh -b	Rebuild and start
compose-down-standalone.sh	Stop services (keep data)
compose-down-standalone.sh -v	Stop and remove all data

What's Included

• PostgreSQL 17 - Database with persistent storage
• Tessera App - Built with JDK 25, runs on JDK 25
• Auto SSL - Self-signed certificate generated on first start
• Persistent Volumes - Database, logs, and certificates survive restarts

Access URLs

Protocol	URL
HTTPS	https://localhost:8443
HTTPS	https://tessera.local:8443
HTTP	http://localhost:8080

Custom SSL Certificate Configuration

By default, certificates are generated for localhost and tessera.local. To customize:

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env with your settings:

   # Hostnames for SSL certificate (comma-separated)
   CERT_HOSTS=localhost,tessera.local,myserver.example.com
   
   # IP addresses for SSL certificate
   CERT_IPS=127.0.0.1,0.0.0.0,192.168.1.100
   
   # Certificate password and alias
   CERT_PASSWORD=your-secure-password
   CERT_ALIAS=tessera-local

3. To use custom hostnames, add them to /etc/hosts:

   127.0.0.1  tessera.local
   

4. Rebuild to regenerate certificates:

   ./compose-down-standalone.sh -v    # Remove old certs
   ./compose-up-standalone.sh -b      # Rebuild with new config

Environment Variables

Variable	Default	Description
POSTGRES_PASSWORD	tessera-dev-pass	Database password
TESSERA_ENCRYPTION_KEY	(dev key)	AES-256 key for token encryption
CERT_HOSTS	localhost,tessera.local	SSL certificate hostnames
CERT_IPS	127.0.0.1,0.0.0.0	SSL certificate IP addresses
CERT_PASSWORD	tessera-dev-cert	Keystore password
CERT_ALIAS	tessera-local	Certificate alias

View Logs

# All services
docker compose -f docker-compose.standalone.yml logs -f

# App only
docker compose -f docker-compose.standalone.yml logs -f app

# Database only
docker compose -f docker-compose.standalone.yml logs -f postgres

Security Notes

For secure deployments, update these in .env:

• POSTGRES_PASSWORD - Use a strong database password
• TESSERA_ENCRYPTION_KEY - Generate with openssl rand -base64 32
• CERT_PASSWORD - Use a strong keystore password

---

Local Development

For development with hot-reload, run the app locally with only PostgreSQL in Docker.

Development Scripts

Script	Description
compose-up.sh	Start PostgreSQL container
compose-down.sh	Stop containers (-v to remove volumes)
build-and-run.sh	Build and run application
generate-certs.sh	Generate self-signed certificates

Build Options

./build-and-run.sh -b      # Clean build
./build-and-run.sh -r      # Force rerun tasks
./build-and-run.sh -s      # Skip tests
./build-and-run.sh -br     # Clean build + rerun

Project Structure

tessera/
├── src/main/java/dk/tessera/
│   ├── config/          # Spring configuration
│   ├── domain/          # JPA entities
│   ├── repository/      # Data repositories
│   ├── service/         # Business logic
│   └── web/             # Controllers
├── src/main/resources/
│   ├── static/          # CSS, JS
│   ├── templates/       # Thymeleaf templates
│   └── certs/           # SSL certificates
└── src/test/            # Tests

Configuration

Key configuration in application.properties:

# Server
server.port=8443
server.ssl.enabled=true

# Database
spring.datasource.url=jdbc:postgresql://localhost:5432/tessera

UI Design

Tessera features a COBOL CICS green screen terminal aesthetic:

• Monospace fonts (IBM Plex Mono)
• Green (#00FF41) on black (#0D0208)
• ASCII art borders
• CRT scan line effects
• Keyboard-driven navigation (F-keys)

Documentation

Guide	Description
Usage Guide	Complete setup and usage instructions
Okta Setup	Step-by-step Okta integration guide
Project Spec	Full feature specification

License

MIT

---

Your identity tokens, verified.