oneauth

package module
v0.1.35 Latest Latest
Warning

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

 Go to latest Published: Jul 3, 2026 License: Apache-2.0 Imports: 0 Imported by: 3

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