samlsp

Documentation

Overview

Package samlsp provides helpers that can be used to protect web services using SAML.

Index

• func RequireAttribute(name, value string) func(http.Handler) http.Handler
• type Middleware
  • func New(opts Options) (*Middleware, error)
  • func (m *Middleware) Authorize(w http.ResponseWriter, r *http.Request, assertion *saml.Assertion)
  • func (m *Middleware) IsAuthorized(r *http.Request) bool
  • func (m *Middleware) RequireAccount(handler http.Handler) http.Handler
  • func (m *Middleware) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Options
• type TokenClaims

Functions

func RequireAttribute

func RequireAttribute(name, value string) func(http.Handler) http.Handler

RequireAttribute returns a middleware function that requires that the SAML attribute `name` be set to `value`. This can be used to require that a remote user be a member of a group. It relies on the X-Saml-* headers that RequireAccount adds to the request.

For example:

goji.Use(m.RequireAccount)
goji.Use(RequireAttributeMiddleware("eduPersonAffiliation", "Staff"))

Types

type Middleware

type Middleware struct {
	ServiceProvider   saml.ServiceProvider
	AllowIDPInitiated bool
	CookieName        string
	CookieMaxAge      time.Duration
}

Middleware implements middleware than allows a web application to support SAML.

It implements http.Handler so that it can provide the metadata and ACS endpoints, typically /saml/metadata and /saml/acs, respectively.

It also provides middleware, RequireAccount which redirects users to the auth process if they do not have session credentials.

When redirecting the user through the SAML auth flow, the middlware assigns a temporary cookie with a random name beginning with "saml_". The value of the cookie is a signed JSON Web Token containing the original URL requested and the SAML request ID. The random part of the name corresponds to the RelayState parameter passed through the SAML flow.

When validating the SAML response, the RelayState is used to look up the correct cookie, validate that the SAML request ID, and redirect the user back to their original URL.

Sessions are established by issuing a JSON Web Token (JWT) as a session cookie once the SAML flow has succeeded. The JWT token contains the authenticated attributes from the SAML assertion.

When the middlware receives a request with a valid session JWT it extracts the SAML attributes and modifies the http.Request object adding headers corresponding to the specified attributes. For example, if the attribute "cn" were present in the initial assertion with a value of "Alice Smith", then a corresponding header "X-Saml-Cn" will be added to the request with a value of "Alice Smith". For safety, the middleware strips out any existing headers that begin with "X-Saml-".

When issuing JSON Web Tokens, a signing key is required. Because the SAML service provider already has a private key, we borrow that key to sign the JWTs as well.

func New

func New(opts Options) (*Middleware, error)

New creates a new Middleware

func (*Middleware) Authorize

func (m *Middleware) Authorize(w http.ResponseWriter, r *http.Request, assertion *saml.Assertion)

Authorize is invoked by ServeHTTP when we have a new, valid SAML assertion. It sets a cookie that contains a signed JWT containing the assertion attributes. It then redirects the user's browser to the original URL contained in RelayState.

func (*Middleware) IsAuthorized

func (m *Middleware) IsAuthorized(r *http.Request) bool

IsAuthorized is invoked by RequireAccount to determine if the request is already authorized or if the user's browser should be redirected to the SAML login flow. If the request is authorized, then the request headers starting with X-Saml- for each SAML assertion attribute are set. For example, if an attribute "uid" has the value "alice@example.com", then the following header would be added to the request:

X-Saml-Uid: alice@example.com

It is an error for this function to be invoked with a request containing any headers starting with X-Saml. This function will panic if you do.

func (*Middleware) RequireAccount

func (m *Middleware) RequireAccount(handler http.Handler) http.Handler

RequireAccount is HTTP middleware that requires that each request be associated with a valid session. If the request is not associated with a valid session, then rather than serve the request, the middlware redirects the user to start the SAML auth flow.

func (*Middleware) ServeHTTP

func (m *Middleware) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler and serves the SAML-specific HTTP endpoints on the URIs specified by m.ServiceProvider.MetadataURL and m.ServiceProvider.AcsURL.

type Options

type Options struct {
	URL               string
	Key               string
	Certificate       string
	AllowIDPInitiated bool
	IDPMetadata       *saml.Metadata
	IDPMetadataURL    string
}

Options represents the parameters for creating a new middleware

type TokenClaims

type TokenClaims struct {
	jwt.StandardClaims
	Attributes map[string][]string `json:"attr"`
}