Documentation
¶
Overview ¶
Package authflow implements the browser-facing OIDC auth-code flow for kombify backend services. It is intentionally small and side-effect free: provider metadata comes from an oidcclient.Registry, code exchange is abstracted behind oidcclient.CodeExchanger for testing, and successful callbacks mint a authsession cookie consumed by the session middleware.
Donor: kombify-Techstack/pkg/v2/auth/flow (lifted 2026-05-03 and rebound to the shared oidcclient + authsession packages).
Index ¶
Constants ¶
const CallbackPath = "/api/v1/auth/callback"
CallbackPath is the path appended to the request scheme+host to derive the `redirect_uri` sent to identity providers. It MUST match the path registered with the IdP. Override via Config.CallbackPath.
Variables ¶
var ( ErrInvalidConfig = errors.New("authflow: invalid configuration") ErrInvalidState = errors.New("authflow: invalid state") ErrMissingTenant = errors.New("authflow: tenant_id is required") )
Errors returned by the flow service.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Providers is the registry of configured OIDC providers. Required.
Providers *oidcclient.Registry
// Sessions mints HS256 session JWTs after a successful callback. Required.
Sessions *authsession.Manager
// StateSecret signs the short-lived state token (CSRF + redirect carrier).
// Must be at least 32 bytes.
StateSecret []byte
// DefaultProviderID is used when /login is called without an explicit
// `provider` query parameter and the registry has more than one entry.
DefaultProviderID string
// DefaultTenantID is stamped into session claims when neither the
// `tenant_id` query parameter nor the [TenantResolver] supplies one.
DefaultTenantID string
// DefaultReturnTo is the post-login redirect path. Defaults to "/".
DefaultReturnTo string
// LoginErrorPath is where the callback redirects on failure. Defaults to
// "/login".
LoginErrorPath string
// CallbackPath overrides the default OIDC callback path. Defaults to
// [CallbackPath].
CallbackPath string
// SessionCookieName is the cookie minted on successful login. Defaults
// to [authsession.DefaultSessionCookieName].
SessionCookieName string
// SessionCookieSecure controls the cookie's Secure flag. Set true in
// production.
SessionCookieSecure bool
// Exchanger overrides the default RFC-6749 code exchanger. Tests inject
// a fake; production uses [oidcclient.NewHTTPCodeExchanger].
Exchanger oidcclient.CodeExchanger
// TenantResolver maps verified OIDC claims to the session tenant id.
// Optional; when nil the request `tenant_id` (or DefaultTenantID) is used.
TenantResolver TenantResolver
// UserUpsert is an optional post-verification hook for user provisioning.
UserUpsert UserUpsert
// Now is injectable for tests.
Now func() time.Time
}
Config configures a Service.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service serves the OIDC auth-code endpoints.
func NewService ¶
NewService validates Config and returns a new auth-code flow service.
func (*Service) CallbackHandler ¶
CallbackHandler completes the auth-code flow, mints a session cookie, and redirects the browser to the requested return path.
func (*Service) LoginHandler ¶
LoginHandler starts the auth-code redirect flow.
func (*Service) LogoutHandler ¶
LogoutHandler clears the session cookie and redirects to the login page (or a caller-provided next path).
func (*Service) ProvidersHandler ¶
ProvidersHandler exposes the configured providers for frontend bootstrap.
type TenantResolver ¶
type TenantResolver func(ctx context.Context, claims *oidcclient.Claims, providerID, requestedTenant string) (string, error)
TenantResolver maps verified OIDC claims to the tenant id stamped into the session cookie. Returning an empty string or non-nil error redirects the browser to the login error page with reason `tenant_resolve_failed`.
Defaults to a function that returns the explicit tenant_id query parameter (or DefaultTenantID) when nil — see [Service.handleLogin].
type UserUpsert ¶
type UserUpsert func(ctx context.Context, claims *oidcclient.Claims, tenantID, providerID string) error
UserUpsert is an optional hook called after successful claim verification and before the session cookie is minted. It lets the consumer create or update its user record (e.g. into PocketBase / Postgres). Returning an error redirects to the login error page with reason `user_upsert_failed`.
Source Files