tessaridb/oauth repository overview

⁠TessariDB OAuth

Sign-in for your own applications, with every piece of its state in TessariDB.

An OAuth 2.1 authorization server and OpenID provider written in Rust. One binary carries the protocol endpoints, the sign-in pages and account portal your users see, and an admin console on a listener of its own. Companies (tenants), users, clients, codes, grants, sealed signing keys and the audit trail are records in a TessariDB store; nothing of the database is inside this image.

• Site: https://oauth.tessaridb.com⁠
• Documentation: https://docs.tessaridb.com/oauth⁠
• Source: https://github.com/tessaridb/tessaridb-oauth⁠

⁠Tags

The configuration and the HTTP surface may still change in a minor release before 1.0. Pin a version tag.

⁠What it needs

• A TessariDB node, 0.38.2 or later, reached over the wire protocol with TLS. The server signs in with the account named by TESSARIDB_OAUTH_STORE_USER.
• Two key files, 32 random bytes each: the key-encryption key that seals signing keys, and the password pepper. The image runs as the user 65532, which must own both files and be the only one able to read them (mode 400 or 600). Neither file is in the store, so neither is in a backup of it.
• Two addresses: PUBLIC_URL, where users and applications reach the issuers, and ADMIN_URL, the admin console, at another origin.

⁠Ports

Without TLS_CERT/TLS_KEY the public listener speaks plain HTTP for a TLS terminator in front of it, which answers at the https PUBLIC_URL. Keep the plain listener reachable from the terminator alone.

⁠Run it

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.2.0

⁠With a TessariDB node, in 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.

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.2.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:

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.

⁠The first operator

A new installation has no operator yet. The emergency path makes one, reading the same environment:

docker exec oauth tessaridb-oauth bootstrap-operator --company acme --email [email protected]

⁠Configuration

The server reads its configuration from the environment when it starts, checks all of it, and refuses to start, naming the variable, when anything is missing or does not fit.

⁠Licence

Business Source License 1.1. Production use is free, including use by and within a commercial company. Providing TessariDB OAuth to third parties as a hosted or managed identity, authentication or authorization service, or selling, reselling, renting or sublicensing it, needs a commercial licence from the Licensor ([email protected]⁠). Each version converts to the Apache License 2.0 four years after its release.