wai-saml2

A Haskell library which implements SAML2 assertion validation as WAI middleware. This can be used by a Haskell web application (the service provider, SP) to perform identity provider (IdP) initiated authentication, i.e. SAML2-based authentication where the authentication begins at the IdP-end, the IdP authenticates the user, and then gets the user to submit a SAML2 assertion back to the SP (known as "unsolicited SSO" within e.g. the Shibboleth project).
Completeness
There are currently a number of limitations to this library:
-
As mentioned above, while the library implements IdP-initiated authentication, it does not yet implement SP-initiated authentication (where the SP submits a login request to the IdP).
-
The library does not currently support the full SAML2 specification and makes certain assumptions about what the IdP's responses contain. It will most likely fail with any IdPs which do not send responses in the same format. If you wish to use this library and encounter problems with your IdP, please open an issue or a pull request which implements support accordingly.
- The library expects that SAML assertions will be encrypted and will decrypt these. There is currently no support for plain-text assertions.
Security
The library is estimated to be sufficiently robust for use in a production environment. If you wish to implement this middleware, please note the following:
-
You must store IDs of assertions you see. If an assertion is successfully validated by this library, you must check that you have not previous seen the assertion ID in order to prevent replay attacks.
-
You must not expose any errors to a client as that could severely compromise the security of the system as attackers may be able to use the errors to narrow down valid SAML responses. You should log and monitor errors though as they may indicate attacks on your system. Ensure that log files containing errors from the SAML2 middleware are stored securely.
Usage
Preliminaries
You need to have registered your service provider with the identity provider. You need to have access to the IdP's metadata, which will contain the public key used for signature validation.
Configuration
The saml2Config
function may be used to construct SAML2Config
values. It expects at least the SP's private key and the IdP's public key as arguments, but you should almost certainly customise the configuration further. The private and public keys can be loaded with functions from the Data.X509
and Data.X509.File
modules (from the x509
and x509-store
packages, respectively):
(saml2Config spPrivateKey idpPublicKey){
saml2AssertionPath = "/sso/assert",
saml2ExpectedIssuer = Just "https://idp.sp.com/saml2",
saml2ExpectedDestination = Just "https://example.com/sso/assert",
}
The configuration options are documented in the Haddock documentation for the Network.Wai.SAML2.Config
module.
Implementation
Two interfaces to the middleware are provided. See the Haddock documentation for the Network.Wai.SAML2
module for full usage examples. An example using the saml2Callback
variant is shown below, where cfg
is a SAML2Config
value and app
is your existing WAI application:
saml2Callback cfg callback mainApp
where callback (Left err) app req sendResponse = do
callback (Right result) app req sendResponse = do
result <- tryRetrieveAssertion (assertionId (assertion result))
case result of
Just something ->
Nothing -> do
storeAssertion (assertionId (assertion result))
Contributions
Please see CONTRIBUTING.md
References