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
• func UnmarshalIDPMetadata(data []byte) (*saml.EntityDescriptor, error)
• func WithToken(ctx context.Context, token *AuthorizationToken) context.Context
• type Attributes
  • func (a Attributes) Get(key string) string
• type AuthorizationToken
  • func Token(ctx context.Context) *AuthorizationToken
• type ClientCookies
  • func (c ClientCookies) DeleteState(w http.ResponseWriter, r *http.Request, id string) error
  • func (c ClientCookies) GetState(r *http.Request, id string) string
  • func (c ClientCookies) GetStates(r *http.Request) map[string]string
  • func (c ClientCookies) GetToken(r *http.Request) string
  • func (c ClientCookies) SetState(w http.ResponseWriter, r *http.Request, id string, value string)
  • func (c ClientCookies) SetToken(w http.ResponseWriter, r *http.Request, value string, maxAge time.Duration)
• type ClientState
• type ClientToken
• type Middleware
  • func New(opts Options) (*Middleware, error)
  • func (m *Middleware) Authorize(w http.ResponseWriter, r *http.Request, assertion *saml.Assertion)
  • func (m *Middleware) CreateGetSAMLInitiatorHandlerFunc(relayStateURI string) func(w http.ResponseWriter, r *http.Request)
  • func (m *Middleware) DeleteRelayStateCookie(w http.ResponseWriter, r *http.Request)
  • func (m *Middleware) GetAssertion(r *http.Request) (*saml.Assertion, error)
  • func (m *Middleware) GetAuthorizationToken(r *http.Request) *AuthorizationToken
  • func (m *Middleware) GetRedirectURI(r *http.Request, assertion *saml.Assertion) (string, error)
  • 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)
  • func (m *Middleware) ServeMetadata(w http.ResponseWriter, r *http.Request)
• type Options

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 Claims assigned to to the context in RequireAccount.

For example:

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

func UnmarshalIDPMetadata

func UnmarshalIDPMetadata(data []byte) (*saml.EntityDescriptor, error)

func WithToken

func WithToken(ctx context.Context, token *AuthorizationToken) context.Context

WithToken returns a new context with token associated

Types

type Attributes

type Attributes map[string][]string

Attributes is a map of attributes provided in the SAML assertion

func (Attributes) Get

func (a Attributes) Get(key string) string

Get returns the first attribute named `key` or an empty string if no such attributes is present.

type AuthorizationToken

type AuthorizationToken struct {
	jwt.StandardClaims
	Attributes Attributes `json:"attr"`
}

AuthorizationToken represents the data stored in the authorization cookie.

func Token

func Token(ctx context.Context) *AuthorizationToken

Token returns the token associated with ctx, or nil if no token are associated

type ClientCookies

type ClientCookies struct {
	ServiceProvider *saml.ServiceProvider
	Name            string
	Domain          string
	Secure          bool
}

ClientCookies implements ClientState and ClientToken using cookies.

func (ClientCookies) DeleteState

func (c ClientCookies) DeleteState(w http.ResponseWriter, r *http.Request, id string) error

DeleteState removes the named stored state by clearing the corresponding cookie.

func (ClientCookies) GetState

func (c ClientCookies) GetState(r *http.Request, id string) string

GetState returns a single stored state by reading the cookies

func (ClientCookies) GetStates

func (c ClientCookies) GetStates(r *http.Request) map[string]string

GetStates returns the currently stored states by reading cookies.

func (ClientCookies) GetToken

func (c ClientCookies) GetToken(r *http.Request) string

GetToken returns the token by reading the cookie.

func (ClientCookies) SetState

func (c ClientCookies) SetState(w http.ResponseWriter, r *http.Request, id string, value string)

SetState stores the named state value by setting a cookie.

func (ClientCookies) SetToken

func (c ClientCookies) SetToken(w http.ResponseWriter, r *http.Request, value string, maxAge time.Duration)

SetToken assigns the specified token by setting a cookie.

type ClientState

type ClientState interface {
	SetState(w http.ResponseWriter, r *http.Request, id string, value string)
	GetStates(r *http.Request) map[string]string
	GetState(r *http.Request, id string) string
	DeleteState(w http.ResponseWriter, r *http.Request, id string) error
}

ClientState implements client side storage for state.

type ClientToken

type ClientToken interface {
	GetToken(r *http.Request) string
	SetToken(w http.ResponseWriter, r *http.Request, value string, maxAge time.Duration)
}

ClientToken implements client side storage for signed authorization tokens.

type Middleware

type Middleware struct {
	ServiceProvider   saml.ServiceProvider
	AllowIDPInitiated bool
	TokenMaxAge       time.Duration
	ClientState       ClientState
	ClientToken       ClientToken
	Binding           string
}

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 a Context object to the request context that contains attributes from the initial SAML assertion.

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) CreateGetSAMLInitiatorHandlerFunc

func (m *Middleware) CreateGetSAMLInitiatorHandlerFunc(relayStateURI string) func(w http.ResponseWriter, r *http.Request)

func (*Middleware) DeleteRelayStateCookie

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

func (*Middleware) GetAssertion

func (m *Middleware) GetAssertion(r *http.Request) (*saml.Assertion, error)

func (*Middleware) GetAuthorizationToken

func (m *Middleware) GetAuthorizationToken(r *http.Request) *AuthorizationToken

GetAuthorizationToken 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 context is ammended with a Context object.

func (*Middleware) GetRedirectURI

func (m *Middleware) GetRedirectURI(r *http.Request, assertion *saml.Assertion) (string, error)

func (*Middleware) IsAuthorized

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

IsAuthorized returns true if the request has already been authorized.

Note: This function is retained for compatability. Use GetAuthorizationToken in new code instead.

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 middleware 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.

func (*Middleware) ServeMetadata

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

type Options

type Options struct {
	URL               url.URL
	Key               *rsa.PrivateKey
	Logger            logger.Interface
	Certificate       *x509.Certificate
	AllowIDPInitiated bool
	IDPMetadata       *saml.EntityDescriptor
	IDPMetadataURL    *url.URL
	HTTPClient        *http.Client
	CookieMaxAge      time.Duration
	CookieName        string
	CookieDomain      string
	CookieSecure      bool
	ForceAuthn        bool
	MetadataPath      string
	ACSPath           string
}

Options represents the parameters for creating a new middleware