saml

README

SAML claim validation library

The SAML authentication protocol [1] allow users to authenticate on another server than the one running the desired service, and provide a claim of identity to the service provider.

This library provides a simple Check mechanism to ensure that the claim provided by a user is indeed valid (cryptographically signed by the certificate). Stricter validation mechanisms can be added.

Goals (and non-goals)

SAML is an, shall we say, enterprise protocol (for example, the core specification clocks at 80+ pages, but actually refers to other specifications such as XML digital signature, which itself refers to XPath, …); it is therefore very hard to provide a small, solid trusted code base that would cover the full specification.

This package therefore does NOT try to match the specification, but instead to accept implementations seen “in the wild”. Instead, the focus is to provide a safe library with correct cryptography, safety against XML vulnerability (we do not expand XML directives, or understand the full XPath syntax) and sanity for side-channels exploits (although those are very, very, very hard to avoid when using XML digital signatures).

Contributing

We welcome patches adressing security vulnerabilities, increasing the robustness of the test suite or adding support for a “common enough” identity provider — keeping the package tidy and small for auditability is paramount, and don’t take it personally if we are a bit conservative.

[1] https://developer.okta.com/docs/concepts/saml/

Documentation

Index

• Constants
• type Checker
  • func AcceptableCertificate(jar interface{ ... }) Checker
  • func InResponseTo(id string) Checker
  • func ValidTimestamp(leeway time.Duration) Checker
• type JarFunc
  • func (jf JarFunc) Find(issuer string) *x509.CertPool
• type Principal
  • func Check(from io.Reader, checkers ...Checker) (Principal, error)
• type Subject

Constants

const StrictTime = 0

Types

type Checker

type Checker func(Principal) error

A Checker is a predicate against a signed element. The element can be a response or an assertion, but bear in mind that all not data might be signed. Checkers in this package will mention when they operate on the assertion only (in which case they require signed values).

func AcceptableCertificate

func AcceptableCertificate(jar interface {
	Find(issuer string) *x509.CertPool
}) Checker

AcceptableCertificate checks that the certificate used to sign the assertion is valid for a given issuer. The pool is used as a root of trust.

func InResponseTo

func InResponseTo(id string) Checker

InResponseTo rejects unsolicited responses

func ValidTimestamp

func ValidTimestamp(leeway time.Duration) Checker

ValidTimestamp accepts only assertion still currently valid. Leeway parameter allows to accept SAML providers which are known to be too slow, and where a strict validation would result in rejecting too many legitimate login attempts.

type JarFunc

type JarFunc func(string) *x509.CertPool

func (JarFunc) Find

func (jf JarFunc) Find(issuer string) *x509.CertPool

type Principal

type Principal struct {
	// Elements in response or assertion (spec § 2.3.3), if in the response, the response must
	// be signed. Clients can rely on this being signed by the certificate.
	Attributes map[string]string
	Conditions map[string]string

	Subject string
	Issuer  string

	Cert *x509.Certificate

	// Element in response (spec § 3.2.2), might not be signed
	InResponseTo string
	Destination  string
}

Principal is the person identified by SAML. Only signed information is returned.

var UnAuth Principal

func Check

func Check(from io.Reader, checkers ...Checker) (Principal, error)

Check validates the SAML response received from the remote part. Additional checkers can be given to provide a stricter acceptance.

https://www.w3.org/TR/2013/REC-xmldsig-core1-20130411/#sec-CoreValidation

type Subject

type Subject string