saml

saml is a partial implementation of the SAML 2.0 standard in Go, covering the Web SSO profile most commonly used for enterprise single sign-on. It supports both roles in a SAML exchange: the core saml package provides the low-level primitives (metadata parsing, request/response construction, signature validation, assertion encryption/decryption) while samlsp layers net/http middleware on top so a Go web application can act as a Service Provider, and samlidp provides a minimal Identity Provider implementation useful for testing or as a starting point for a custom IDP.

The library supports the HTTP Redirect and HTTP POST bindings for requests flowing from the service provider to the identity provider, and the HTTP POST binding for responses flowing back, along with the interoperable SAML profile most enterprise IDPs (Okta, OneLogin, Azure AD, samltest.id) expect. It can produce signed authentication requests and validate both signed and encrypted assertions, handling the X.509 certificate and XML-DSig plumbing that SAML requires under the hood.

What You Get

• Core saml package with metadata parsing/generation, AuthnRequest and Response construction, and assertion validation
• samlsp middleware that wraps any http.Handler to require SAML authentication, handling the metadata and ACS endpoints automatically
• Support for HTTP Redirect and HTTP POST bindings for outgoing requests, and POST/Artifact bindings for incoming responses
• Signed and encrypted assertion handling, including X.509 certificate parsing and fingerprint-based signature validation
• samlidp package providing a working Identity Provider implementation for testing or as a starting point for a custom IDP
• Pluggable RequestTracker and SessionProvider interfaces (cookie- or JWT-based) so applications can customize how pending requests and sessions are tracked

Common Use Cases

• Adding enterprise single sign-on (SSO) to a Go web app so employees can log in with their company’s identity provider
• Standing up a lightweight SAML Identity Provider for internal tools or integration testing against samlidp
• Consuming SAML assertions to populate request context with authenticated user attributes (e.g. displayName, group membership)
• Integrating with common enterprise IDPs (Okta, OneLogin, Azure AD, ADFS) that speak the interoperable SAML profile
• Validating signed/encrypted SAML responses in a custom auth gateway or API proxy written in Go

Under The Hood

Architecture The library is organized as three cooperating packages: the root saml package (service_provider.go, identity_provider.go, metadata.go, schema.go) implements the protocol primitives — building and parsing AuthnRequest/Response/Assertion elements via beevik/etree, validating XML signatures, and handling certificate-based encryption/decryption. samlsp builds an http.Handler-based Middleware on top of ServiceProvider, wiring in pluggable RequestTracker (tracks pending auth requests via signed cookies or JWTs) and SessionProvider (issues session cookies) interfaces so applications aren’t locked into one session strategy. samlidp composes the same core primitives from the IDP side, exposing ServeSSO/ServeIDPInitiated handlers and a pluggable user/session Store. The design cleanly separates protocol mechanics from HTTP wiring, so the core package could be reused outside net/http if needed.

Tech Stack Pure Go (module targets Go 1.22+) with a small, deliberate dependency set: beevik/etree for XML element manipulation, russellhaering/goxmldsig for XML digital signature creation/validation, golang-jwt/jwt/v5 for the JWT-based session and request-tracking cookies, golang.org/x/crypto for supporting cryptographic primitives, and mattermost/xml-roundtrip-validator to guard against XML parsing ambiguity attacks. No web framework dependency — samlsp.Middleware is a plain http.Handler, so it composes with any Go HTTP stack (stdlib, chi, gorilla/mux, etc.).

Code Quality The repository ships 21 _test.go files alongside their corresponding implementation files, including large table-driven suites for service_provider.go and identity_provider.go covering both success and adversarial (malformed/unsigned/expired) SAML responses. CI runs go test ./... across three Go versions (1.22-1.24) and a separate golangci-lint job enabling a wide linter set (gosec, staticcheck, gocritic, bodyclose, revive, unparam, and more) with only a handful of checks explicitly deferred. Errors are returned as typed/wrapped Go errors (fmt.Errorf with %w) rather than swallowed, and custom error types (InvalidResponseError, ErrBadStatus) carry structured context for callers.

What Makes It Unique Rather than exposing a single opinionated “login with SAML” helper, the library exposes both the low-level protocol implementation and a composable middleware layer, letting consumers pick which parts they need — from raw assertion parsing up to a full drop-in http.Handler. Its explicit support for both the interoperable SAML profile and the historically awkward SAML corners (artifact binding, RelayState size limits, encrypted assertions) reflects that it’s one of the few actively used pure-Go SAML implementations rather than a thin wrapper around another language’s library.