sso

README

gosso

Stateless SAML + OIDC adapters for Go. You own the session.

import (
    sso "github.com/foomo/gosso"
    "github.com/foomo/gosso/oidc"
)

rp, err := oidc.New(
    "https://login.example.com/realms/my-realm",
    "my-client",
    os.Getenv("CLIENT_SECRET"),
    "https://app.example.com/oidc/callback",
    []byte(os.Getenv("TRANSIT_KEY")),
    func(ctx context.Context, w http.ResponseWriter, r *http.Request, s sso.Subject[oidc.Payload]) error {
        // You own the session. Do whatever you want with s here.
        return writeCookie(w, s)
    },
)
if err != nil { log.Fatal(err) }

h := rp.Handlers()
http.Handle("/oidc/login", h.Login)
http.Handle("/oidc/callback", h.Callback)
http.Handle("/oidc/logout", h.Logout)

SAML has the exact same shape. Both protocols produce an sso.Subject[T] so your session-construction code can be shared.

Full docs

https://foomo.github.io/gosso/

Sandbox

make sandbox.up   # Keycloak on :8081 with realm preloaded
make sandbox.run  # demo app on :8080, both protocols mounted

# log in as alice / password (admins) or bob / password (users)

See examples/sandbox/README.md.

Contributing

See docs/CONTRIBUTING.md.

License

MIT, see LICENSE.

Made with ♥ foomo by bestbytes

Documentation

Overview

Package sso provides the shared contract used by protocol-specific authentication adapters (SAML, OIDC) in this module.

A consumer of this library plugs in one or more adapters (see the saml and oidc subpackages) and receives a Subject through the OnAuthenticated callback once authentication succeeds. The consumer is responsible for translating that Subject into its own session representation; this package stores nothing.

Index

• type ErrorLogger
• type GroupMapper
  • func (m GroupMapper[R]) Map(groups []string) []R
• type OnAuthenticated
• type OnLogout
• type Subject

Types

type ErrorLogger

type ErrorLogger func(r *http.Request, msg string, err error)

ErrorLogger receives runtime errors encountered while processing an SSO HTTP request. The msg argument is a short stable identifier for the failing stage (e.g. "token-exchange", "verify-id-token", "on-authenticated"). HTTP responses from the adapters stay generic; this callback exists so consumers can route the underlying cause to their own structured logger without exposing internals to the browser.

type GroupMapper

type GroupMapper[R comparable] map[string]R

GroupMapper translates raw IdP group identifiers into the consumer's application-specific role type. It is a convenience helper; consumers with different translation needs should skip it and roll their own.

func (GroupMapper[R]) Map

func (m GroupMapper[R]) Map(groups []string) []R

Map returns the roles for every known group, preserving input order and deduplicating results. Unknown groups are silently skipped.

type OnAuthenticated

type OnAuthenticated[T any] func(
	ctx context.Context,
	w http.ResponseWriter,
	r *http.Request,
	sub Subject[T],
) error

OnAuthenticated fires after a successful authentication round-trip. The consumer is responsible for persisting whatever session representation (cookie, JWT, server-side record, ...) it needs.

Returning a non-nil error aborts the login flow: the adapter will not perform its post-authentication redirect and will surface the error as HTTP 500 to the caller.

type OnLogout

type OnLogout func(ctx context.Context, w http.ResponseWriter, r *http.Request) error

OnLogout fires when the logout handler is invoked. The consumer should destroy its session. Returning a non-nil error aborts logout with HTTP 500 and skips any IdP-side single-logout redirect.

type Subject

type Subject[T any] struct {
	// ExternalID is the stable IdP-side user identifier
	// (Azure AD objectidentifier, OIDC `sub`).
	ExternalID string
	Email      string
	Firstname  string
	Lastname   string
	// Groups holds the raw group identifiers as returned by the IdP.
	// Use GroupMapper to translate them into application roles.
	Groups []string
	// NameID is the SAML NameID; empty for OIDC and other non-SAML flows.
	NameID string
	// Raw carries the protocol-specific payload.
	Raw T
}

Subject is the authenticated principal handed to the consumer after a successful authentication round-trip. The T type parameter carries the protocol-specific raw payload (e.g. saml.Payload, oidc.Payload); the other fields are common across protocols so consumers can share session construction logic.