How ory/fosite works
Project type and purpose
• This is a Go-based, security-first OAuth2 & OpenID Connect framework (library), not a complete application or service.
• It provides composable handlers for every OAuth2 and OpenID Connect flow (authorize code, implicit, hybrid, device code, PKCE, JWT bearer, pushed auth, refresh, revoke, introspect, etc.).
• It’s intended to be embedded into your own HTTP server or an OAuth2 service (e.g., ORY Hydra).
File structure
• Top-level packages:
• compose – convenience functions to wire together config, storage, crypto, and handlers
• handler – flow-specific handlers (oauth2/, openid/, par, pkce, rfc8628, verifiable)
• token – token strategies (HMAC, JWT)
• internal – core implementations, storage interfaces, strategies, helpers
• Core API entrypoints:
• Fosite public API (fosite.go, client.go, handler.go)
• HTTP handler glue (access_request_handler.go, authorize_request_handler.go, token handlers, introspection handlers, revoke handlers)
• Configuration & build: config.go, Makefile, go.mod, CI/CD workflows, tests & examples.
Key insights from the README
• The public API revolves around a provider object created via compose.ComposeAllEnabled(...)
• The provider exposes methods: NewAuthorizeRequest, NewAuthorizeResponse, NewAccessRequest, NewAccessResponse, IntrospectToken, Write…Error/Response.
• You supply: HTTP server endpoints → call Fosite → Fosite calls registered flow handlers → Fosite calls storage interfaces → Fosite generates tokens.
a. Main components:
• Your HTTP Server (external)
• Fosite Provider (compose layer + config + crypto keys)
• OAuth2 & OIDC Handlers (handler/* packages)
• Token Strategies (token/hmac, token/jwt)
• Storage (your implementation or storage/memory)
• Internal core (internal/*: strategies, storage interfaces, request/response models)
b. Interactions:
1. HTTP Server invokes Provider.NewAuthorizeRequest(ctx, req)
2. Provider dispatches to the relevant AuthorizeCode/Implicit/Device/… handler
3. Handler validates client, scopes, redirect URIs, state → calls Storage interfaces to persist codes/tokens
4. On success, Provider.NewAuthorizeResponse bundles tokens/authorization codes via Token Strategies
5. HTTP Server writes response (redirect or JSON) using Provider.WriteAuthorizeResponse
6. Token endpoint flow similarly goes: NewAccessRequest → Token handlers → Storage → Token Strategies → WriteAccessResponse
7. Introspection → Provider.IntrospectToken → Introspector Strategy → Storage check → return active/inactive
c. Architectural patterns & design principles:
• Dependency injection via compose package
• Strategy pattern for token generation and validation (HMAC vs JWT)
• Handler pipeline for each grant type (chain of responsibility)
• Storage abstraction (interfaces in internal/, reference impl in storage/)
• Separation of API (public methods) vs implementation (internal/)
d. Key technologies & libraries:
• Go modules
• Standard library net/http for endpoints
• Crypto (RSA, HMAC) for JWT signing and token strategies
• Config-driven architecture (fosite.Config)
• Testing: extensive unit and integration tests