oneauth

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2026 License: Apache-2.0 Imports: 0 Imported by: 5

README

OneAuth

An embeddable Go authentication library for apps and resource servers. Local auth (signup, login, email verification, password reset), OAuth2 / OIDC client flows, multi-tenant JWT issuance and validation, federated app registration, and a small reference server you can deploy as-is or treat as a worked example.

OneAuth is not trying to be a full identity provider — it interoperates with real IdPs (Keycloak interop is in CI) and focuses on making Go services easy to secure with standards-compliant pieces. See docs/ROADMAP.md for vision and what's deliberately out of scope.

Why OneAuth?

  • Library, not a sidecar. Embed in your Go service. No extra process, no auth-server-as-product to operate.
  • Composed interfaces, no god objects. Every transport-agnostic surface follows Method(ctx, *XRequest) (*XResponse, error) — TokenIssuer / TokenValidator / TokenIntrospector / TokenRevoker / ClientAuthenticator / ClientRegistrationManager / ClientRegistrar. HTTP handlers are thin wrappers.
  • Storage-agnostic. Three backends ship for every store interface — file (dev), GORM (Postgres / MySQL / SQLite), GAE/Datastore. Bring your own by implementing the interfaces.
  • Lightweight core. Top-level module pulls ~6 deps (jwt, scs, x/crypto, x/oauth2, …). Heavy backends (GORM, GAE, SAML, gRPC) are separate Go sub-modules so consumers only download what they use. See docs/MIGRATION.md for the sub-module layout.
  • Real interop. Keycloak conformance suite runs against a live container in tests/keycloak/. Gap analyses vs Auth0 and Authlete live in docs/gaps/.

Standards

Endpoint / Feature RFC
Token endpoint — password, refresh, client_credentials, jwt-bearer, token-exchange RFC 6749, 7523, 8693
Token Introspection (/oauth/introspect) RFC 7662
Token Revocation (/oauth/revoke) RFC 7009
Authorization Server Metadata + OIDC Discovery RFC 8414
JWKS (/.well-known/jwks.json) RFC 7517, 7638
Protected Resource Metadata RFC 9728
Dynamic Client Registration RFC 7591
DCR Management (GET / PUT / DELETE on /apps/dcr/{client_id}) RFC 7592
Rich Authorization Requests (authorization_details) RFC 9396
iss on authorize redirect RFC 9207
PKCE on OAuth2 social login + headless CLI login RFC 7636, 8252
Private Key JWT client auth (private_key_jwt) RFC 7521, 7523

A full Authlete-superset gap analysis lives at docs/gaps/AUTHLETE_GAP_ANALYSIS.md.

Install

go get github.com/panyam/oneauth@latest

Sub-modules (only pull what you need):

go get github.com/panyam/oneauth/stores/gorm@latest
go get github.com/panyam/oneauth/stores/gae@latest
go get github.com/panyam/oneauth/grpc@latest
go get github.com/panyam/oneauth/saml@latest

Where to start

You want to… Go here
Wire up local signup/login in a Go service docs/GETTING_STARTED.md
Walk through OAuth concepts hands-on, one RFC at a time examples/ — 10 progressive runnable examples
Protect API endpoints with JWT (multi-tenant, JWKS-aware) docs/API_AUTH.md
Run an authorization server today cmd/oneauth-server/ — config-driven, deployable to GAE / Docker / K8s
See the whole federated flow (auth + apps + resource servers) locally demo/ — 6-service Docker Compose
Use the client SDK from a CLI tool docs/CLIENT_SDK.md
Just grab a bearer token from any RFC 8414 / OIDC AS cmd/oneauth/ — oneauth token {browser,client-credentials,password,refresh}
Understand the design decisions and rationale docs/ARCHITECTURE.md

Architecture

Three-layer data model for end-user accounts. Lives in accounts/:

User: alice@example.com
├── Identity: alice@example.com (verified)
├── Channel: local    (password hash)
├── Channel: google   (OAuth tokens)
└── Channel: github   (OAuth tokens)
  • User — your application account.
  • Identity — a contact handle (email, phone) with verification status, shared across channels.
  • Channel — one authentication mechanism (local, google, github, …) carrying provider-specific credentials.

Verifying an identity through any channel verifies it everywhere. New channels can be linked onto an existing user by matching identity.

For the token lifecycle, federated-auth flow, and the rest of the data model, see docs/ARCHITECTURE.md.

Package map

Every package has a DESIGN.md (rich) and SUMMARY.md (LLM-friendly index). The top-level tour is MAP.md.

Package Role
accounts/ User / Identity / Channel model + store interfaces
core/ Tokens, scopes, RFC 9396 authorization_details, rate-limit/blacklist primitives
keys/ Signing-key storage, kid lookup, encryption-at-rest, JWKS, rotation grace
localauth/ Local signup, login, verification, password reset, credential linking
federatedauth/ OAuth/SAML callback orchestration, channel linking onto existing users
httpauth/ Session/JWT-aware login mux, CSRF, body-limit, security-header middleware
apiauth/ Token issuance, JWT middleware, introspection, revocation, discovery
admin/ App registration (DCR + RFC 7592 + admin CRUD), resource-token minting
oauth2/ Google / GitHub social-login providers with PKCE
saml/ SAML 2.0 SP adapter (POC)
client/ Client SDK — discovery, browser/CLI/M2M login, token cache, auto-refresh
grpc/ Auth context propagation across HTTP↔gRPC boundary
stores/fs · stores/gorm · stores/gae Backend implementations of every store interface
testutil/ In-process RS256 AS + JWKS + DCR fixture for downstream tests

Documentation

Document What it covers
GETTING_STARTED Install, store setup, first auth flow
ARCHITECTURE Design decisions, data model, token lifecycle, federated auth
API_AUTH JWT middleware, custom claims, multi-tenant validation
BROWSER_AUTH OAuth flows, channel linking, session management
FEDERATED_AUTH App registration, MintResourceToken, AdminAuth
JWT_SIGNING HS256 / RS256 / ES256 keys, JWKS, rotation
CLIENT_SDK CLI / programmatic clients, browser-login, refresh
STORES Store interfaces and implementations
GRPC gRPC context utilities + interceptors
AUTH_FLOWS Login/signup decision trees, edge cases
TESTING Test patterns, security references
MIGRATION Sub-module layout, consumer migration guide
CONFORMANCE Conformance / load / adversarial test strategy
RELEASE_NOTES Version history
godoc Generated API reference

Build & test

make test          # Unit tests
make e2e           # In-process e2e (~2s)
make testkcl       # Keycloak interop + RAR conformance (Docker)
make testall       # 9-stage matrix + report

Reference deployment lives in cmd/oneauth-server/. The 6-service federated demo (auth + 2 apps + 2 resource servers + Postgres) lives in demo/ — see docs/DEMOS.md.

License

See LICENSE.

Documentation

Overview

Package oneauth provides a unified authentication framework for Go applications.

OneAuth is organized into subpackages:

  • core/ — Foundation types: User, Identity, Channel, store interfaces, tokens, credentials, scopes
  • keys/ — Key storage, KID tracking, JWKS serving/fetching, encrypted key storage
  • admin/ — Admin auth, app registration API, resource token minting
  • apiauth/ — API token auth (JWT + API keys), validation middleware
  • localauth/ — Local username/password auth: signup, login, email verify, password reset
  • httpauth/ — HTTP middleware, CSRF protection, session-based auth mux
  • stores/ — Storage backends: fs/, gorm/, gae/
  • utils/ — Crypto helpers (PEM, JWK, key generation)
  • client/ — Client SDK
  • oauth2/ — OAuth2 provider implementations
  • grpc/ — gRPC auth interceptors

See each subpackage's SUMMARY.md for details.

Source Files

View all Source files

Directories

Path Synopsis
Package accounts owns the federated end-user account model — the data shape shared by both username/password (localauth) and provider-mediated (federatedauth) authentication flows.
 Package accounts owns the federated end-user account model — the data shape shared by both username/password (localauth) and provider-mediated (federatedauth) authentication flows.
Package appstoretest provides a shared contract test suite for all AppRegistrationStore implementations.
 Package appstoretest provides a shared contract test suite for all AppRegistrationStore implementations.
Package authcodetest provides a shared contract test suite for all core.AuthorizationCodeStore implementations (RFC 6749 §4.1).
 Package authcodetest provides a shared contract test suite for all core.AuthorizationCodeStore implementations (RFC 6749 §4.1).
stores/fs
cmd
oneauth module
Package deviceauthtest provides a shared contract test suite for all core.DeviceAuthorizationStore implementations (RFC 8628).
 Package deviceauthtest provides a shared contract test suite for all core.DeviceAuthorizationStore implementations (RFC 8628).
examples
01-client-credentials command
Example 01: OAuth 2.0 Client Credentials Flow.
 Example 01: OAuth 2.0 Client Credentials Flow.
02-resource-token-hs256 command
Example 02: Resource Token with HS256 (Federated Auth).
 Example 02: Resource Token with HS256 (Federated Auth).
03-resource-token-rs256-jwks command
Example 03: Resource Token with RS256 + JWKS Discovery.
 Example 03: Resource Token with RS256 + JWKS Discovery.
04-discovery command
Example 04: AS Metadata Discovery (RFC 8414).
 Example 04: AS Metadata Discovery (RFC 8414).
05-introspection command
Example 05: Token Introspection (RFC 7662).
 Example 05: Token Introspection (RFC 7662).
06-dynamic-client-registration command
Example 06: Dynamic Client Registration (RFC 7591).
 Example 06: Dynamic Client Registration (RFC 7591).
07-client-sdk command
Example 07: Client SDK — Production Patterns.
 Example 07: Client SDK — Production Patterns.
08-rich-authorization-requests command
Example 08: Rich Authorization Requests (RFC 9396).
 Example 08: Rich Authorization Requests (RFC 9396).
09-key-rotation command
Example 09: Key Rotation with Grace Periods.
 Example 09: Key Rotation with Grace Periods.
10-security command
Example 10: Security — Attack Prevention.
 Example 10: Security — Attack Prevention.
common
Package common holds helpers shared across oneauth examples — the seam where "every example needs this now" updates land in one place instead of N copy-paste edits.
 Package common holds helpers shared across oneauth examples — the seam where "every example needs this now" updates land in one place instead of N copy-paste edits.
refs
Package refs provides pre-defined reference constants for OneAuth examples.
 Package refs provides pre-defined reference constants for OneAuth examples.
Package federatedauth owns provider-mediated authentication orchestration — OAuth and SAML callback handlers plus account-linking helpers — that build on the account model in accounts/ and the session/middleware machinery in httpauth/.
 Package federatedauth owns provider-mediated authentication orchestration — OAuth and SAML callback handlers plus account-linking helpers — that build on the account model in accounts/ and the session/middleware machinery in httpauth/.
grpc module
Package keystoretest provides shared test suites for all KeyStore implementations.
 Package keystoretest provides shared test suites for all KeyStore implementations.
oauth2 module
Package partest provides a shared contract test suite for every core.PushedAuthorizationRequestStore implementation (RFC 9126).
 Package partest provides a shared contract test suite for every core.PushedAuthorizationRequestStore implementation (RFC 9126).
saml module
sshkeys module
stores
fs
gae module
gorm module
Package tracing wires oneauth's HTTP-handling code into OpenTelemetry trace context propagation (W3C Trace Context, https://www.w3.org/TR/trace-context/).
 Package tracing wires oneauth's HTTP-handling code into OpenTelemetry trace context propagation (W3C Trace Context, https://www.w3.org/TR/trace-context/).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.