bytepeddlerllc/tiny-auth repository overview

⁠Tiny Auth

A self-contained OAuth 2.0 and OpenID Connect (OIDC) authorization server. It supports both machine-to-machine and user login flows, issues RS256-signed JWTs, and manages clients and users entirely in memory with optional seeding on startup. It is designed to be lightweight and easy to run locally or in a container, making it well suited for development and testing.

⁠Features

• OAuth 2.0 Client Credential Flow (machine-to-machine)
• OAuth 2.0 Authorization Code Flow with PKCE
• OpenID Connect (OIDC) with ID token issuance
• JWKS endpoint for public key distribution
• OpenID Connect discovery endpoint
• Web UI for login and administration
• Client and user management via REST API
• Seed file support for pre-populating clients and users on startup
• Actuator endpoints for health checks and metrics

⁠Endpoints

⁠OAuth / OIDC

⁠Client Management

Requires a Bearer token with the client:read or client:write scope as appropriate. Use the admin client credentials to obtain a token with those scopes.

⁠User Management

Requires a Bearer token with the user:read or user:write scope as appropriate.

⁠Actuator

⁠Configuration

The application is configured via CLI flags or environment variables. All flags have a corresponding environment variable name in uppercase with underscores.

A .env file in the working directory is loaded automatically if present.

⁠Admin Client

On startup, an admin client and a corresponding admin user are created automatically using the --admin-client-id and --admin-client-secret values. The admin client is granted the scopes client:read, client:write, user:read, and user:write, and its audience is set to <hostname>/admin. The admin client and user are protected and cannot be deleted via the API.

⁠Seed File

A seed file can be provided to pre-populate clients and users when the application starts. The file must be in YAML format:

clients:
  workflow:
    secret: workflow1
    scope: some:scope
    audience:
      - something
users:
  ben:
    password: ben1
    name: Ben
    email: [email protected]
    picture: https://www.gravatar.com/avatar
    permissions:
      - client:read

⁠Web UI

The application serves a small web interface at the following paths:

⁠JWT Details

RSA key pairs are generated fresh on every startup using a 2048-bit key. All tokens are signed with RS256.

⁠Sample Docker Compose

services:
  tiny-auth:
    container_name: tiny-auth
    image: bytepeddlerllc/tiny-auth:latest
    environment:
      ADMIN_CLIENT_ID: admin
      ADMIN_CLIENT_SECRET: 123
      HOSTNAME: http://localhost:8080
      ISSUER: http://localhost:8080
      LOG_LEVEL: debug
      SEED_FILE: /tmp/seed.yaml
    ports:
      - "8080:8080"
    configs:
      - source: seed_data
        target: /tmp/seed.yaml

configs:
  seed_data:
    content: |
      clients:
        workflow:
          secret: workflow1
          scope: some:scope
          audience:
            - something
      users:
        ben:
          password: ben1
          name: Ben
          email: [email protected]
          picture: https://www.gravatar.com/avatar
          permissions:
            - client:read

⁠AI Disclosure

LLMs were used to aid the development of this project in the following areas:

• Tiny Auth Server - The Tiny Auth server is exclusively human authored. LLMs were used only to provide code reviews.
• Tiny Auth Server tests - Most tests were human written. LLMs authored some additional test cases using human authored tests as a guide.
• UI - Most of the web interface and supporting JS was generated by LLMs. It has been reviewed and structured by a human.
• Docs - LLMs assisted with the generation of documentation but the majority was human authored.