saml

README

This package provides basic integration for baseapp with a SAML IDP. The package handles the auth flow with the IDP (ACS and redirect). It does not implement any session tracking/memory so users must implement their own.

There are 3 main integration points users should be aware of:

1. ErrorCallback: called whenever an error occurs during the auth flow. The callback is expected to send a response to the request
2. LoginCallback: called when a user successfully authenticates. The callback should create a session based on the passed in assertion.
3. IDStore: used to store SAML requestID's to prevent assertion spoofing.

Example

A simple example of how to integrate the saml package into baseapp

logger := baseapp.NewLogger(baseapp.LoggingConfig{
    Level:  "debug",
    Pretty: true,
})

p := baseapp.DefaultParams(logger, "")
s, err := baseapp.NewServer(baseapp.HTTPConfig{
    Address: "127.0.0.1",
    Port:    8000,
}, p...)

if err != nil {
    panic(err)
}

spParam := []saml.Param{
    saml.WithCertificateFromFile("./cert.pem"),
    saml.WithKeyFromFile("./key"),
    saml.WithEntityFromURL("http://localhost:8080/simplesaml/saml2/idp/metadata.php"),
    saml.WithACSPath("/saml/acs"),
    saml.WithMetadataPath("/saml/metadata"),
}

sp, err := saml.NewServiceProvider(spParam...)
if err != nil {
    panic(err)
}

s.Mux().Handle(pat.Post("/saml/acs"), sp.ACSHandler())
s.Mux().Handle(pat.Get("/saml/metadata"), sp.MetadataHandler())
s.Mux().HandleFunc(pat.Get("/auth"), sp.DoAuth)

_ = s.Start()

Documentation

Overview

Package saml provides the necessary handlers to implement a SAML authentication workflow. It relies on the IDP's metadata file being accessible via HTTP.

Index

• func DefaultErrorCallback(w http.ResponseWriter, r *http.Request, err Error)
• func DefaultLoginCallback(w http.ResponseWriter, r *http.Request, resp *saml.Assertion)
• type Error
  • func (s Error) Error() string
• type ErrorCallback
• type IDStore
• type LoginCallback
• type Param
  • func WithACSPath(path string) Param
  • func WithCertificateFromBytes(certBytes []byte) Param
  • func WithCertificateFromFile(path string) Param
  • func WithEncryptedAssertions(encrypt bool) Param
  • func WithEntityFromBytes(metadata []byte) Param
  • func WithEntityFromURL(url string) Param
  • func WithEntityID(value string) Param
  • func WithErrorCallback(ecb ErrorCallback) Param
  • func WithForceAuthn(force bool) Param
  • func WithForceTLS(force bool) Param
  • func WithIDStore(store IDStore) Param
  • func WithKeyFromBytes(keyBytes []byte) Param
  • func WithKeyFromFile(path string) Param
  • func WithLoginCallback(lcb LoginCallback) Param
  • func WithLogoutPath(path string) Param
  • func WithMetadataPath(path string) Param
  • func WithNameIDFormat(n saml.NameIDFormat) Param
  • func WithServiceProvider(s *saml.ServiceProvider) Param
• type ServiceProvider
  • func NewServiceProvider(params ...Param) (*ServiceProvider, error)
  • func (s *ServiceProvider) ACSHandler() http.Handler
  • func (s *ServiceProvider) DoAuth(w http.ResponseWriter, r *http.Request)
  • func (s *ServiceProvider) MetadataHandler() http.Handler

Functions

func DefaultErrorCallback

func DefaultErrorCallback(w http.ResponseWriter, r *http.Request, err Error)

func DefaultLoginCallback

func DefaultLoginCallback(w http.ResponseWriter, r *http.Request, resp *saml.Assertion)

Types

type Error

type Error struct {
	Err error

	// The suggested HTTP response code for this error
	ResponseCode int
}

func (Error) Error

func (s Error) Error() string

type ErrorCallback

type ErrorCallback func(http.ResponseWriter, *http.Request, Error)

ErrorCallback is called whenever an error occurs in the saml package. The callback is expected to send a response to the request. The http.ResponseWriter will not have been written to, allowing the callback to send headers if desired.

type IDStore

type IDStore interface {
	// StoreID stores a request ID in such a way that it can be
	// retreived later using GetIDs
	StoreID(w http.ResponseWriter, r *http.Request, id string) error

	// GetIDs returns the currently valid request ID for SAML authentication
	// If no ID is found an empty string should be returned without an error
	GetID(r *http.Request) (string, error)
}

IDStore stores the request id for SAML auth flows

type LoginCallback

type LoginCallback func(http.ResponseWriter, *http.Request, *saml.Assertion)

LoginCallback is called whenever an auth flow is successfully completed. The callback is responsible preserving the login state.

type Param

type Param func(sp *ServiceProvider) error

func WithACSPath

func WithACSPath(path string) Param

WithACSPath sets the path where the assertion consumer handler for the service provider is registered. The path is included in generated metadata. This is a required parameter.

func WithCertificateFromBytes

func WithCertificateFromBytes(certBytes []byte) Param

func WithCertificateFromFile

func WithCertificateFromFile(path string) Param

func WithEncryptedAssertions

func WithEncryptedAssertions(encrypt bool) Param

WithEncryptedAssertions enables or disables assertion encryption. By default, encryption is enabled. When set to false, the encryption key is not included in generated metadata.

func WithEntityFromBytes

func WithEntityFromBytes(metadata []byte) Param

func WithEntityFromURL

func WithEntityFromURL(url string) Param

func WithEntityID

func WithEntityID(value string) Param

WithEntityID is optional. When set it will define the EntityID within the EntityDescriptor. If left unset it will default to your metadata url.

func WithErrorCallback

func WithErrorCallback(ecb ErrorCallback) Param

func WithForceAuthn

func WithForceAuthn(force bool) Param

func WithForceTLS

func WithForceTLS(force bool) Param

func WithIDStore

func WithIDStore(store IDStore) Param

func WithKeyFromBytes

func WithKeyFromBytes(keyBytes []byte) Param

func WithKeyFromFile

func WithKeyFromFile(path string) Param

func WithLoginCallback

func WithLoginCallback(lcb LoginCallback) Param

func WithLogoutPath

func WithLogoutPath(path string) Param

WithLogoutPath sets the path where the single logout handler for the service provider is registered. The path is included in generated metadata.

func WithMetadataPath

func WithMetadataPath(path string) Param

WithMetadataPath sets the path where the metadata handler for the service provider is registered. The path is included in generated metadata. This is a required parameter.

func WithNameIDFormat

func WithNameIDFormat(n saml.NameIDFormat) Param

func WithServiceProvider

func WithServiceProvider(s *saml.ServiceProvider) Param

type ServiceProvider

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

ServiceProvider is capable of handling a SAML login. It provides an http.Handler (via ACSHandler) which can process the http POST from the SAML IDP. It accepts callbacks for both error and success conditions so that clients can take action after the auth flow is complete. It also provides a handler for serving the service provider metadata XML.

func NewServiceProvider

func NewServiceProvider(params ...Param) (*ServiceProvider, error)

NewServiceProvider returns a ServiceProvider. The configuration of the ServiceProvider is a result of combinging settings provided to this method and values parsed from the IDP's metadata.

func (*ServiceProvider) ACSHandler

func (s *ServiceProvider) ACSHandler() http.Handler

ACSHandler returns an http.Handler which is capable of validating and processing SAML Responses.

func (*ServiceProvider) DoAuth

func (s *ServiceProvider) DoAuth(w http.ResponseWriter, r *http.Request)

DoAuth takes an http.ResponseWriter that has not been written to yet, and conducts and SP initiated login If the flow proceeds correctly the user should be redirected to the handler provided by ACSHandler().

func (*ServiceProvider) MetadataHandler

func (s *ServiceProvider) MetadataHandler() http.Handler

MetadataHandler returns an http.Handler which sends the generated metadata XML in response to a request