MrWho

MrWhoOidc Public Repository

This repository is the public-facing companion to the MrWhoOidc product line.

It exists to publish:

What Is In This Repo

Area Purpose
docs deployment guides, configuration reference, admin and developer docs, operational guides
demos working example applications in .NET, React, Go, Kotlin, plus an OBO demo API
src/MrWhoOidc.Client .NET client package for discovery, auth flows, token exchange, logout helpers, and JWKS caching
src/MrWhoOidc.Security .NET security helpers including DPoP support
docker-compose.yml base container deployment
docker-compose.dev.yml local development overlay with MailHog
docker-compose.redis.yml Redis performance overlay
docker-compose.production.yml hardened production overlay
website static GitHub Pages site for the project overview

Current Platform Scope

MrWhoOidc currently focuses on a standards-based OIDC and OAuth 2.0 identity service with current product capabilities including:

Quick Start

Prerequisites

The examples below use docker compose. If your environment still exposes the legacy docker-compose binary, replace the command name accordingly. First run is typically 3-5 minutes, depending on image pulls and container startup time.

The base docker-compose.yml path is production-oriented. On an empty database it does not auto-seed a tenant or admin user; the first usable local instance requires an explicit bootstrap.

This is the default published-image path. Do not clone MrWhoOidc and do not use docker compose -f docker-compose.yml up -d --build for this flow.

Local Container Startup

mkdir -p "$HOME/src"
cd "$HOME/src"

git clone https://github.com/popicka70/MrWho.git
cd MrWho

bash ./scripts/generate-cert.sh localhost changeit
chmod 644 ./certs/aspnetapp.pfx
test -f ./certs/aspnetapp.pfx && echo "certificate ready"

cp .env.example .env
# for the stock local path, edit at minimum:
# POSTGRES_PASSWORD
# BOOTSTRAP_TOKEN on a fresh local database
# CERT_PASSWORD=changeit and OIDC_PUBLIC_BASE_URL=https://localhost:8443 already match the generated certificate and default local ports
# leave MAIL_* empty unless you plan to enable SMTP
# if you are reusing an existing local Docker volume and changed POSTGRES_PASSWORD,
# either keep the original password or reset the local database state first:
# docker compose down -v --remove-orphans

grep -q 'ghcr.io/popicka70/mrwhooidc:latest' docker-compose.yml && echo "published image compose file confirmed"

docker compose config | grep ghcr.io/popicka70/mrwhooidc:latest

docker compose up -d

# if the first bootstrap curl fails with a TLS or socket error,
# wait 5-10 seconds for HTTPS startup and retry the same request

# bootstrap the first tenant and admin user on an empty database
curl -k -X POST https://localhost:8443/bootstrap \
	-H 'Content-Type: application/json' \
	-H 'X-Bootstrap-Token: your-temporary-bootstrap-token' \
	-d '{
		"tenantSlug": "default",
		"tenantName": "Default Tenant",
		"adminEmail": "admin@example.com",
		"adminPassword": "ChangeMeNow123!",
		"adminName": "Administrator"
	}'

# remove BOOTSTRAP_TOKEN from .env after the bootstrap succeeds,
# then re-apply the containers
docker compose up -d

# post-bootstrap smoke tests
curl -k https://localhost:8443/t/default/.well-known/openid-configuration
curl -k -I https://localhost:8443/admin/clients
curl -k https://localhost:8443/t/default/jwks
bash ./scripts/health-check.sh https://localhost:8443 default

If either verification command above does not print ghcr.io/popicka70/mrwhooidc:latest, stop because you are no longer following the published Docker image path.

Expected discovery output includes fields such as issuer, authorization_endpoint, token_endpoint, and jwks_uri.

Expected first-run behavior:

Optional overlays:

# Development logging + MailHog
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

# Add Redis caching
docker compose -f docker-compose.yml -f docker-compose.redis.yml up -d

# Hardened production-style setup
docker compose -f docker-compose.yml -f docker-compose.production.yml up -d

Default endpoints:

Use the tenant-scoped discovery document for first-run smoke tests. Root discovery depends on a default tenant already existing.

For fresh production-style databases, set BOOTSTRAP_TOKEN and follow docs/deployment-guide.md.

Documentation Map

Start here depending on what you need:

Example Applications

See demos/README.md for the full matrix. Highlights:

.NET Packages

The public client packages currently published from this repo are:

Package Current Line Targets
MrWhoOidc.Client 2.0.1 net8.0, net10.0
MrWhoOidc.Security 2.0.1 net8.0, net10.0

These packages are intended to make client integration, discovery, token handling, DPoP, and logout processing easier for .NET applications.

Multi-Tenancy Notes

Current public documentation reflects the product’s current behavior:

See docs/multitenancy-quick-reference.md for the operational model.

GitHub Pages

This repo ships a small static site in website intended for GitHub Pages deployment. The Pages workflow lives in .github/workflows/deploy-pages.yml.

Contact

This site is open source. Improve this page.