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:
ErrorCallback: called whenever an error occurs during the auth flow. The callback is expected to send a response to the requestLoginCallback: called when a user successfully authenticates. The callback should create a session based on the passed in assertion.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
- 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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultErrorCallback ¶
func DefaultErrorCallback(w http.ResponseWriter, r *http.Request, err Error)
func DefaultLoginCallback ¶
Types ¶
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 ¶
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 ¶
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 WithCertificateFromFile ¶
func WithEncryptedAssertions ¶
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 WithEntityFromURL ¶
func WithEntityID ¶ added in v0.4.1
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 ¶ added in v0.2.4
func WithForceTLS ¶
func WithIDStore ¶
func WithKeyFromBytes ¶
func WithKeyFromFile ¶
func WithLoginCallback ¶
func WithLoginCallback(lcb LoginCallback) Param
func WithLogoutPath ¶
WithLogoutPath sets the path where the single logout handler for the service provider is registered. The path is included in generated metadata.
func WithMetadataPath ¶
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
Source Files