riley_auth

OAuth 2.0 + OpenID Connect identity provider. Delegates authentication to upstream OAuth providers (Google, GitHub, or any OIDC/OAuth2 provider), then issues its own tokens so your apps authenticate against you, not against Google. One instance, one user database, single sign-on across all your apps.

Why riley_auth?

Most auth solutions ask you to choose: a managed service you pay per-seat for, a sprawling Java server you need a team to operate, or a library that only handles half the problem.

riley_auth is different:

• Zero password footprint — all authentication is delegated upstream. There are no passwords to store, hash, rotate, or breach. Your attack surface is smaller by design.
• Easy to self-host — single Rust binary, one config file, one PostgreSQL database. Deploy on a $5/month VPS, in a Docker container, or anywhere you can run a binary. No JVM, no Node runtime, no microservice fleet.
• Free and open source — MIT licensed, no per-seat pricing, no usage tiers, no vendor lock-in. You own your identity infrastructure.
• Full OIDC provider — not just a login library. riley_auth implements the complete OAuth 2.0 / OpenID Connect provider spec: authorization code flow with PKCE, token introspection, revocation, discovery, JWKS, and UserInfo. Your downstream apps authenticate against your issuer using standard protocols.
• Token reuse detection — refresh tokens rotate on every use. If a consumed token is replayed (credential theft, session hijack), the entire token family is revoked automatically.
• Reliable webhook delivery — user lifecycle events are written to a transactional outbox, not fired inline. HMAC-signed, retried with backoff, and queryable for debugging.
• Multi-key JWKS rotation — add and remove signing keys with zero downtime. Supports ES256 and RS256 concurrently.

Features

• Authorization Code Flow with PKCE — full OIDC-compliant provider
• Multi-provider OAuth — built-in Google and GitHub presets, OIDC auto-discovery for any provider, manual OAuth2 for non-OIDC providers
• Token rotation with reuse detection — refresh tokens rotate on every use; reuse of a consumed token revokes the entire family
• Multi-key JWKS with rotation — ES256 and RS256 signing, add/remove keys with zero downtime
• Custom scopes — define application-specific scopes, assign per-client, propagate through consent and token issuance
• Webhook events — subscribe to user lifecycle events (created, deleted, role changed, etc.) with HMAC-signed delivery and retry
• Prometheus metrics — request counts, latencies, and error rates at /metrics
• Rate limiting — tiered (auth/standard/public), in-memory or Redis-backed
• CLI administration — manage users, clients, webhooks, and keys from the command line
• OpenAPI spec — machine-readable API documentation at /openapi.json

Quick Start

1. Start PostgreSQL

Any PostgreSQL 14+ instance works. For local development:

docker run -d --name riley-auth-db \
  -e POSTGRES_USER=riley_auth \
  -e POSTGRES_PASSWORD=changeme \
  -e POSTGRES_DB=riley_auth \
  -p 5432:5432 postgres:17

2. Generate signing keys

cargo run -- generate-keys --algorithm es256 --output ./keys

This creates private.pem and public.pem in the ./keys directory.

3. Write a config file

Copy riley_auth.example.toml to riley_auth.toml and fill in:

• [jwt] → issuer (required, e.g. "https://auth.example.com")
• [[jwt.keys]] → paths to your generated keys
• [database] → url (e.g. "postgres://riley_auth:changeme@localhost/riley_auth")
• [[oauth.providers]] → at least one OAuth provider with credentials

4. Run migrations

cargo run -- migrate

5. Start the server

cargo run -- serve

The server starts on http://0.0.0.0:8081 by default.

6. First login and admin promotion

Log in through your OAuth provider, then promote yourself:

cargo run -- promote your-username

Configuration

See riley_auth.example.toml for a fully documented example config.

Key sections:

All secret values support "env:VAR_NAME" syntax to read from environment variables.

CLI Reference

riley-auth <command> [options]

Global option: --config <path> to specify config file location.

API

The full API specification is available at /openapi.json when the server is running. Point any OpenAPI viewer (Swagger UI, Redoc, etc.) at this endpoint for interactive documentation.

Endpoint Groups

Authentication (/auth/*) — OAuth login flows, session management, profile updates. Cookie-based auth.

OAuth/OIDC Provider (/oauth/*) — Standard OAuth 2.0 / OIDC endpoints for downstream apps. Bearer token auth.

Admin (/admin/*) — User and client management. Requires admin role.

Discovery — Public endpoints, no auth required.

Deployment

See docs/deployment.md for Docker, Docker Compose, VPS deployment, key rotation, and backup instructions.

License

MIT