examples/

OneAuth Examples

Progressive examples demonstrating OneAuth's authentication and authorization capabilities. Start at 01 and work your way up — each builds on concepts from the previous.

Cast of Characters

Every example involves the same cast. To make them concrete, imagine you're building Slack — a messaging app with channels, bots, and third-party integrations.

The players

How they connect

Developer builds the App (GitHub bot)
         │
         ▼
   ┌──────────┐     registers      ┌───────────┐
   │   App    │ ──────────────────▶│  Auth     │
   │ (GitHub  │     gets tokens    │  Server   │
   │   bot)   │ ◀──────────────────│  (AS)     │
   └────┬─────┘                    └──────┬────┘
        │                                 │
        │  Bearer token                   │  serves JWKS
        ▼                                 ▼
   ┌──────────┐    validates token  ┌──────────┐
   │ Resource │  ◀─ ─ ─ ─ ─ ─ ─ ─   │  JWKS    │
   │  Server  │    (using pub key)  │ endpoint │
   │ (Slack   │                     └──────────┘
   │   API)   │
   └──────────┘

How does an App get registered?

Before an App can get tokens, it must register with the Auth Server and receive credentials (client_id + client_secret). But who is allowed to register?

In these examples, registration is open (NewNoAuth()) for simplicity. In production, always gate registration with authentication — see admin.NewAPIKeyAuth() or protect the endpoint at the network level.

Important: The client_secret is a backend credential. It lives in your server, not in a browser or mobile app. Frontend apps use PKCE (public clients) instead of secrets.

When is a user involved?

CLI first

If you only need a token — not embedded SDK behavior — reach for the oneauth binary first:

go install github.com/panyam/oneauth/cmd/oneauth@latest
oneauth token client-credentials https://auth.example.com --client-id … --client-secret-stdin <<<"$SECRET"
oneauth introspect https://auth.example.com --token "$ACCESS" --client-id rs --client-secret-stdin <<<"$RS_SECRET"
oneauth dcr register https://auth.example.com --client-name ci --grant-types client_credentials
oneauth jwks https://auth.example.com --format table

The examples below show the SDK embedded inside a Go program — useful when you need caching, auto-refresh, custom hooks, or other behavior the CLI doesn't expose. See docs/USER_GUIDE.md → Use the CLI for the full subcommand reference.

Examples

Keycloak column: Examples marked "Optional" have an extra step that runs against Keycloak if it's available, showing the same code working against a real-world IdP. Start KC with cd examples && make upkcl. All examples work without KC — the KC steps skip gracefully.

Run examples

# Interactive walkthrough (TUI renderer — default)
cd examples/01-client-credentials && make demo

# Plain stdout renderer (good for piping)
cd examples/01-client-credentials && make demo-plain

# Non-interactive — fire every step without pausing (CI smoke)
cd examples/01-client-credentials && make demo-ci

# Run just the auth + resource servers and let an external client drive them
cd examples/01-client-credentials && make serve
# (then use curl, your own app, an MCP host, etc.)

# Regenerate every WALKTHROUGH.md from the demo definitions
cd examples && make walkthroughs

How the examples work

Each example splits into two files:

• main.go — boots a real auth server (and resource server, where applicable). With --serve, it binds the servers on real ports and blocks so any OAuth client can drive them.
• walkthrough.go — the demokit demo. It spins up the same servers in-process via httptest and runs as a scripted client. The two share the server builders (newAuthServer, newResourceServer), so the wire bytes are identical between the two modes.

Each directory has a slim README.md (how to run it) and a generated WALKTHROUGH.md (the full step-by-step with mermaid sequence diagram, copy-paste curl reproductions for every wire-level call, and reference links). WALKTHROUGH.md is regenerated from the demo definitions via make walkthrough — the demo source is the single source of truth.

The TUI renderer (make demo, the default) shows colored boxes per step with countdown bars between them. The plain renderer (make demo-plain) writes flat stdout for piping. Use make demo-ci to run every step back-to-back without pauses — useful for CI smoke or for scripted comparisons.