Get started

Run it beside a TessariDB node

The image tessaridb/oauth carries the server alone, for linux/amd64 and linux/arm64. It needs a TessariDB node, 0.38.2 or later, two key files and two addresses, and it refuses to start, naming the variable, when anything is missing.

Status

0.1.0, the first release, in alpha

Everything listed on this site is served by the binary and covered by its tests. The configuration and the HTTP surface may still change in a minor release before 1.0, so pin the image tag.

In a container

The image

It listens on 8443 (the issuers, sign-in pages and account portal) and 9443 (the admin console) and runs as the user 65532, which must own the two key files and be the only one able to read them.

shellshwrap

head -c 32 /dev/urandom > kek && head -c 32 /dev/urandom > pepper
chmod 400 kek pepper && sudo chown 65532:65532 kek pepper
docker run -d --name oauth -p 8443:8443 -p 127.0.0.1:9443:9443 \
  -v "$PWD/kek:/keys/kek:ro" -v "$PWD/pepper:/keys/pepper:ro" \
  -e TESSARIDB_OAUTH_KEK=/keys/kek -e TESSARIDB_OAUTH_PEPPER=/keys/pepper \
  -e TESSARIDB_OAUTH_PUBLIC_URL=https://id.example.com -e TESSARIDB_OAUTH_ADMIN_URL=https://admin.example.com \
  -e TESSARIDB_OAUTH_STORE=db.example.com:9080 -e TESSARIDB_OAUTH_STORE_USER=oauth \
  -e TESSARIDB_OAUTH_STORE_PASSWORD -e TESSARIDB_OAUTH_STORE_AUTHORITY=/keys/store-ca.pem \
  -v "$PWD/store-ca.pem:/keys/store-ca.pem:ro" \
  -e TESSARIDB_OAUTH_REGION=eu -e TESSARIDB_OAUTH_TENANTS=acme tessaridb/oauth:0.1.0

With a TessariDB node

Compose

The node gets a certificate for the name tessaridb (its key owned by 10001, mode 600) and declares the server's account as its first user; the server trusts the node through ca.pem. Put the certificate, its key, the authority and the two key files in ./keys, set STORE_PASSWORD, and run docker compose up -d. Discovery then answers at http://127.0.0.1:8443/acme/.well-known/openid-configuration with the issuer https://id.example.com/acme; in production a TLS terminator serves that URL.

compose.yamlyamlwrap

services:
  tessaridb:
    image: tessaridb/tessaridb:0.38.2
    restart: unless-stopped
    volumes:
      - tessaridb-data:/var/lib/tessaridb
      - ./keys/store.pem:/keys/store.pem:ro
      - ./keys/store.key:/keys/store.key:ro
    environment:
      TESSARIDB_INITIAL_USER: oauth
      TESSARIDB_INITIAL_PASSWORD: ${STORE_PASSWORD:?set it}
      TESSARIDB_TLS_CERT: /keys/store.pem
      TESSARIDB_TLS_KEY: /keys/store.key

  oauth:
    image: tessaridb/oauth:0.1.0
    restart: unless-stopped
    depends_on: [tessaridb]
    ports:
      - "8443:8443"             # issuers, sign-in pages, account portal
      - "127.0.0.1:9443:9443"   # admin console, this host only
    volumes:
      - ./keys/kek:/keys/kek:ro
      - ./keys/pepper:/keys/pepper:ro
      - ./keys/ca.pem:/keys/ca.pem:ro
    environment:
      TESSARIDB_OAUTH_PUBLIC_URL: https://id.example.com
      TESSARIDB_OAUTH_ADMIN_URL: http://127.0.0.1:9443
      TESSARIDB_OAUTH_KEK: /keys/kek
      TESSARIDB_OAUTH_PEPPER: /keys/pepper
      TESSARIDB_OAUTH_STORE: tessaridb:9080
      TESSARIDB_OAUTH_STORE_USER: oauth
      TESSARIDB_OAUTH_STORE_PASSWORD: ${STORE_PASSWORD:?set it}
      TESSARIDB_OAUTH_STORE_AUTHORITY: /keys/ca.pem
      TESSARIDB_OAUTH_REGION: eu
      TESSARIDB_OAUTH_TENANTS: acme

volumes:
  tessaridb-data:

The first operator

The emergency path

A new installation has no operator yet. The emergency path makes one and prints an enrolment code; the operator sets a password with it, then opens the console at <ADMIN_URL>/admin/acme/.

shellshwrap

docker exec oauth tessaridb-oauth bootstrap-operator --company acme --email root@example.com

From source

Building it

Rust 1.98 or newer. The sign-in, account and console pages are committed build output, so no Node is needed to build the server.

shellshwrap

git clone https://github.com/tessaridb/tessaridb-oauth
cd tessaridb-oauth && git checkout v0.1.0
cargo build --release -p tessari-oauth-node   # target/release/tessaridb-oauth

NextEvery variable, in the docs →