saml

Documentation

Overview

Package saml implements a stateless SAML 2.0 Service Provider on top of github.com/crewjam/saml. After a successful assertion the parsed principal is handed to the consumer via a gosso.OnAuthenticated callback; this package never writes session cookies itself.

Index

• Variables
• func LoadKeyPair(certPath, keyPath string) (*x509.Certificate, *rsa.PrivateKey, error)
• func ParseKeyPair(certPEM, keyPEM []byte) (*x509.Certificate, *rsa.PrivateKey, error)
• type AttributeMap
• type Handlers
• type Option
  • func WithAllowIDPInitiated(allow bool) Option
  • func WithAttributeMap(m AttributeMap) Option
  • func WithBootstrapTimeout(d time.Duration) Option
  • func WithErrorLogger(fn sso.ErrorLogger) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithOnLogout(fn sso.OnLogout) Option
  • func WithPostLogoutRedirectURL(u string) Option
  • func WithSLOHintProvider(fn SLOHintProvider) Option
• type Payload
• type SLOHintProvider
• type SP
  • func New(entityID string, rootURL string, idpMetadataURL string, cert *x509.Certificate, ...) (*SP, error)
  • func (sp *SP) Handlers() Handlers
  • func (sp *SP) Middleware() *anyMiddleware

Variables

var AzureADAttributeMap = AttributeMap{
	ExternalID: "http://schemas.microsoft.com/identity/claims/objectidentifier",
	Email:      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
	Firstname:  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
	Lastname:   "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
	Groups:     "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups",
}

AzureADAttributeMap is the default attribute URI set used by Azure AD (and, conveniently, by Keycloak when configured with the Microsoft attribute mappers).

Functions

func LoadKeyPair

func LoadKeyPair(certPath, keyPath string) (*x509.Certificate, *rsa.PrivateKey, error)

LoadKeyPair reads the SP's x509 cert / RSA key pair from disk. The result is intended for the cert+key arguments of New.

func ParseKeyPair

func ParseKeyPair(certPEM, keyPEM []byte) (*x509.Certificate, *rsa.PrivateKey, error)

ParseKeyPair parses the SP cert / key from in-memory PEM bytes. Useful for tests or when secrets are injected from a vault.

Types

type AttributeMap

type AttributeMap struct {
	ExternalID string
	Email      string
	Firstname  string
	Lastname   string
	Groups     string
}

AttributeMap names the SAML attribute URIs that are read out of the assertion into sso.Subject's common fields. The defaults target Azure AD; consumers that use a different IdP can override individual URIs via WithAttributeMap.

type Handlers

type Handlers struct {
	ACS    http.Handler
	Login  http.Handler
	Logout http.Handler
	SLO    http.Handler
}

Handlers groups the HTTP handlers the consumer mounts on its router. The ACS handler also serves the metadata document on the IdP-configured metadata path. SLO handles the LogoutResponse the IdP posts back after an SP-initiated single-logout round-trip and redirects the browser to the configured post-logout URL (or `/`).

type Option

type Option = options.OptionE[*SP]

Option configures an SP.

func WithAllowIDPInitiated

func WithAllowIDPInitiated(allow bool) Option

WithAllowIDPInitiated permits IdP-initiated login. Disabled by default; enable only if the IdP is trusted and the consumer does not rely on the request tracker to carry a target URL.

func WithAttributeMap

func WithAttributeMap(m AttributeMap) Option

WithAttributeMap overrides the default Azure-AD attribute URIs used when parsing an assertion.

func WithBootstrapTimeout

func WithBootstrapTimeout(d time.Duration) Option

WithBootstrapTimeout bounds the time `New` will spend fetching IdP metadata. Defaults to 30s. Values ≤ 0 are rejected.

func WithErrorLogger

func WithErrorLogger(fn sso.ErrorLogger) Option

WithErrorLogger routes runtime errors encountered by the SAML handlers to the supplied logger. HTTP responses stay generic regardless; the logger sees the underlying cause (e.g. IdP SLO construction failure, OnAuthenticated callback errors).

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient overrides the client used to fetch IdP metadata. The default client has a 15 second Timeout; a client supplied here is used as-is — set your own Timeout if you want one.

func WithOnLogout

func WithOnLogout(fn sso.OnLogout) Option

WithOnLogout registers a callback invoked when the logout handler fires. If not supplied, logout is a no-op before the SLO redirect.

func WithPostLogoutRedirectURL

func WithPostLogoutRedirectURL(u string) Option

WithPostLogoutRedirectURL sets the URL the SLO handler redirects to after the IdP signals it has cleared its session. Defaults to `/`.

func WithSLOHintProvider

func WithSLOHintProvider(fn SLOHintProvider) Option

WithSLOHintProvider registers the callback used by the logout handler to build the IdP-side single-logout request. Without it, /logout is local-only: OnLogout fires and the response is HTTP 200.

type Payload

type Payload struct {
	// Assertion is the full, validated SAML assertion as parsed by
	// crewjam/saml. Most consumers only need the derived Subject fields;
	// it is exposed for the rare cases that need custom claim lookups.
	Assertion *saml.Assertion
	// SessionIndex mirrors the corresponding XML attribute in the first
	// AuthnStatement of the assertion. The IdP requires it as part of a
	// SAML 2.0 LogoutRequest.
	SessionIndex string
}

Payload is the SAML-specific data carried in sso.Subject[Payload].Raw. It gives the consumer everything needed to build its own session and, later, initiate a single-logout round-trip.

type SLOHintProvider

type SLOHintProvider func(*http.Request) (nameID, sessionIndex string)

SLOHintProvider returns the NameID and SessionIndex required to build a SAML LogoutRequest. Typically the consumer extracts them from its own session. Returning an empty NameID skips the IdP-side SLO.

type SP

type SP struct {
	// contains filtered or unexported fields
}

SP is a constructed SAML Service Provider. Obtain one from New and mount the values returned by Handlers onto the consumer's router.

func New

func New(
	entityID string,
	rootURL string,
	idpMetadataURL string,
	cert *x509.Certificate,
	key *rsa.PrivateKey,
	onAuthenticated sso.OnAuthenticated[Payload],
	opts ...Option,
) (*SP, error)

New constructs a SAML Service Provider. It fetches the IdP metadata synchronously, so a slow or unreachable IdP endpoint will surface as an error here (bounded by the bootstrap timeout).

The mandatory parameters are:

• entityID: the SAML Entity ID advertised in SP metadata.
• rootURL: externally reachable base URL of the consuming service (e.g. `https://app.example.com`); metadata, ACS and logout URLs are derived from it.
• idpMetadataURL: the IdP metadata endpoint, fetched during New.
• cert, key: the SP's x509 cert / RSA key pair. Use LoadKeyPair or ParseKeyPair to obtain them.
• onAuthenticated: the callback that receives the parsed Subject after a successful assertion.

func (*SP) Handlers

func (sp *SP) Handlers() Handlers

Handlers returns the SP's HTTP handlers.

func (*SP) Middleware

func (sp *SP) Middleware() *anyMiddleware

Middleware exposes the underlying crewjam middleware for advanced use-cases (e.g. mounting RequireAccount on a subtree). Most consumers should not need this.