A minimal implementation of a SAML service provider. More...

#include <Wt/Auth/Saml/Service.h>

Public Member Functions
	Service (const AuthService &baseAuth)
	Constructor.

virtual	~Service ()
	Destructor. More...

void	initialize ()
	Initializes the Service so it is ready for use. More...

void	setPopupEnabled (bool enable)
	Configure if a popup should be used for the login. More...

bool	popupEnabled () const
	Returns if a popup is used for the login. More...

std::unique_ptr< Process >	createProcess () const
	Creates a new authorization process. More...

std::string	encodeState (const std::string &url) const
	Derives a state value from the session ID. More...

std::string	decodeState (const std::string &state) const
	Validates and decodes a state parameter. More...

const AuthService &	baseAuth () const
	Returns the basic authentication service.

std::string	metadata () const
	Returns the SPs metadata as XML. More...

virtual Identity	assertionToIdentity (const Assertion &assertion) const =0
	Creates an entity from the given Assertion. More...

Configuration properties
void	setSecret (const std::string &secret)
	Sets the secret used when encoding the RelayState. More...

void	setRedirectTimeout (std::chrono::seconds timeout)
	Sets the timeout to login when there is no popup. More...

void	setName (const std::string &name)
	Sets the provider name. More...

const std::string &	name () const
	Returns the provider name. More...

void	setDescription (const std::string &description)
	Sets the provider description. More...

const std::string &	description () const
	Returns the provider description. More...

void	setPopupWidth (int popupWidth)
	Sets the desired width for the popup window. More...

int	popupWidth () const
	Returns the desired width for the popup window. More...

void	setPopupHeight (int popupHeight)
	Sets the desired height for the popup window. More...

int	popupHeight () const
	Returns the desire height for the popup window. More...

void	setIdpEntityId (const std::string &entityID)
	Sets the entity ID of the IdP.

const std::string &	idpEntityId () const
	Gets the entity ID of the IdP. More...

void	setNameIdPolicyFormat (const std::string &format)
	Sets the format for the name id policy in the authentication request. More...

const std::string &	nameIdPolicyFormat () const
	Gets the format for the name id policy in the authentication request. More...

void	setNameIdPolicyAllowCreate (bool allowCreate)
	Sets the AllowCreate parameter for the name id policy in the authentication request. More...

bool	nameIdPolicyAllowCreate () const
	Gets the AllowCreate parameter for the name id policy in the authentication request. More...

void	setAuthnContextClassRef (const std::string &authnContextClassRef)
	Sets the authentication context class to use in the authentication request. More...

const std::string &	authnContextClassRef () const
	Gets the authentication context class to use in the authentication request. More...

void	setAuthnContextComparison (AuthnContextComparison comparison)
	Sets the comparison to use in the authentication context of the authentication request. More...

AuthnContextComparison	authnContextComparison () const
	Gets the comparison to use in the authentication context of the application request. More...

void	setSPEntityId (const std::string &entityID)
	Sets the entity ID of this SP.

const std::string &	spEntityId () const
	Gets the entity ID of this SP. More...

void	setAcsUrl (const std::string &url)
	Sets the Assertion Consumer Service URL. More...

const std::string &	acsUrl () const
	Gets the Assertion Consumer Service URL. More...

std::string	acsPath () const
	Gets the Assertion Consumer Service path. More...

void	setMetadataPath (const std::string &path)
	Sets the path at which the metadata of this SP will be made available. More...

const std::string &	metadataPath () const
	Returns the path at which the metadata of this SP will be made available. More...

void	setMetadataProviderPath (const std::string &path)
	Sets the path to the XML file that describes the metadata provider. More...

const std::string &	metadataProviderPath () const
	Returns the path to the XML file that describes the metadata provider. More...

void	setCredentialResolverPath (const std::string &path)
	Sets the path to the XML that describes the credential resolver. More...

const std::string &	credentialResolverPath () const
	Returns the path to the XML file that describes the credential resolver. More...

void	setXmlValidationEnabled (bool enabled)
	Sets whether responses should be validated against the XML schema. More...

bool	xmlValidationEnabled () const
	Retursn whether responses should be validated against the XML schema. More...

void	setXmlToolingCatalogPath (const std::string &path)
	Sets the path of XMLTooling's `catalog.xml` file. More...

const std::string &	xmlToolingCatalogPath () const
	Returns the path of XMLTooling's `catalog.xml` file. More...

void	setSamlCatalogPath (const std::string &path)
	Sets the path of OpenSAML's `saml20-catalog.xml` file. More...

const std::string &	samlCatalogPath () const
	Returns the path of OpenSAML's `saml20-catalog.xml` file. More...

void	setSignaturePolicy (SignaturePolicy policy)
	Sets the signature policy. More...

SignaturePolicy	signaturePolicy () const
	Returns the current signature policy. More...

Protected Member Functions
virtual void	configureLogging ()
	Sets up logging. More...

virtual void	configureXmlSecurity ()
	Configures the algorithm whitelist. More...

Detailed Description

A minimal implementation of a SAML service provider.

This class implements a minimal SAML 2.0 service provider for single sign on based on the C++ version of OpenSAML 3, part of Shibboleth.

Part of the Web Browser SSO Profile (saml-profiles-2.0-os, section 4.1) is implemented, including:

AuthnRequest (saml-core-2.0-os, section 3.4.1) using HTTP Redirect binding (saml-bindings-2.0-os, section 3.4)
An Assertion Consumer Service receiving Response (saml-core-2.0-os, section 3.3.3) using HTTP POST binding (saml-bindings-2.0-os, section 3.5)

Only SP-initiated login is supported.

Metadata

It's possible to get the SP's metadata in XML format through the metadata() function, and it's possible to set a metadata endpoint with setMetadataPath(). This may be useful when adding this SP's information to the IdP.

Tested IdPs

Single sign on was tested with:

SimpleSAMLphp
Microsoft Azure AD
Google
samltest.id (based on Shibboleth)
Auth0

Thread safety

Once configured and initialized, the service may safely be used from multiple threads: it is stateless or locks are acquired where necessary, so a const Service is thread safe.

Usage

This Service is an abstract base class, assertionToIdentity() needs to be specialized in order to retrieve an Identity from the Assertion, for example:

class MySamlService : public Wt::Auth::Saml::Service {
public:
  explicit MySamlService(const Wt::Auth::AuthService &baseAuth)
    : Wt::Auth::Saml::Service(baseAuth)
  { }
 
  Wt::Auth::Identity assertionToIdentity(const Wt::Auth::Saml::Assertion &assertion) const override
  {
    auto name = assertion.attributeValue("name");
    auto email = assertion.attributeValue("email");
    if (!email || !name) {
      return {};
    }
    return Wt::Auth::Identity("saml", *email, *name, *email, true);
  }
};

The Service must first be configured and then initialized. We recommend that you do this once at application startup.

Note: The Service's destructor should run before main() exits. Otherwise the cleanup may cause a crash.

Example configuration:

// baseAuth is a const AuthService&
MySamlService service(baseAuth);
// It's common for the SP entityId to be the same as the metadata endpoint URL, but this
// could be anything
service.setSPEntityId("https://sp.example.com/metadata.xml");
service.setAcsUrl("https://sp.example.com/acs");
service.setMetadataPath("/metadata.xml");
service.setIdpEntityId("https://idp.example.com/sso");
service.setMetadataProviderPath("metadata_provider.xml");
service.setAuthnRequestSigningEnabled(true);
service.setCredentialResolverPath("credential_resolver.xml");
service.initialize();

Standards compliance notes

The RelayState used by Wt exceeds the limit of 80 bytes mandated by the standard (saml-bindings-2.0-os, section 3.4.3). However, most implementations allow this limit to be exceeded.

The SP in Wt does not implement the full SP Lite operational mode (saml-conformance-2.0-os, section 3.1). Missing are:

HTTP Artifact binding
Artifact resolution (over SOAP)
Single logout (SLO)
Enhanced Client/Proxy SSO, PAOS

References

saml-core-2.0-os: Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0
saml-bindings-2.0-os: Bindings for the OASIS Security Security Assertion Markup Language (SAML) V2.0
saml-conformance-2.0-os: Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0
saml-profiles-2.0-os: Profiles for the OASIS Security Markup Language (SAML) V2.0
saml-metadata-2.0-os: Metadata for the OASIS Security Markup Language (SAML) V2.0

Constructor & Destructor Documentation

◆ ~Service()

Wt::Auth::Saml::Service::~Service ( )

virtual

Destructor.

Note: The destructor should be run before the main() function exits.

Member Function Documentation

◆ acsPath()

std::string Wt::Auth::Saml::Service::acsPath ( ) const

Gets the Assertion Consumer Service path.

This strips the domain name from the acsUrl(), e.g. if the acsUrl() is https://sp.example.com/acs then this will return /acs. This is the path at which the WResource for the Assertion Consumer Service will be deployed.

◆ acsUrl()

const std::string& Wt::Auth::Saml::Service::acsUrl ( ) const

Gets the Assertion Consumer Service URL.

See also: setAcsUrl()

◆ assertionToIdentity()

virtual Identity Wt::Auth::Saml::Service::assertionToIdentity ( const Assertion & assertion ) const

pure virtual

Creates an entity from the given Assertion.

This function should be specialized to return an Identity based on the given Assertion, e.g.:

Wt::Auth::Identity assertionToIdentity(const Wt::Auth::Saml::Assertion &assertion) const override
{
  auto name = assertion.attributeValue("name");
  auto email = assertion.attributeValue("email");
  if (!email || !name) {
    return {};
  }
  return Wt::Auth::Identity("saml", *email, *name, *email, true);
}

◆ authnContextClassRef()

const std::string& Wt::Auth::Saml::Service::authnContextClassRef ( ) const

Gets the authentication context class to use in the authentication request.

See also: setAuthnContextClassRef(); authnContextComparison()

◆ authnContextComparison()

AuthnContextComparison Wt::Auth::Saml::Service::authnContextComparison ( ) const

Gets the comparison to use in the authentication context of the application request.

See also: setAuthnContextComparison(); authnContextClassRef()

◆ configureLogging()

void Wt::Auth::Saml::Service::configureLogging ( )

protectedvirtual

Sets up logging.

By default, this makes all log4shib logging redirect to Wt's logger.

You can configure log4shib differently, or not set up logging altogether by overriding this function.

◆ configureXmlSecurity()

void Wt::Auth::Saml::Service::configureXmlSecurity ( )

protectedvirtual

Configures the algorithm whitelist.

You can configure the whitelist differently, or not set up the whitelist altogether by overriding this function.

By default, the following algorithms are supported:

◆ createProcess()

std::unique_ptr< Process > Wt::Auth::Saml::Service::createProcess ( ) const

Creates a new authorization process.

The service needs to be correctly configured and initialized before being able to call this function.

Exceptions

WException if the Service was not initialized

See also: initialize()

◆ credentialResolverPath()

const std::string& Wt::Auth::Saml::Service::credentialResolverPath ( ) const

Returns the path to the XML file that describes the credential resolver.

See also: setCredentialResolverPath()

◆ decodeState()

std::string Wt::Auth::Saml::Service::decodeState ( const std::string & state ) const

Validates and decodes a state parameter.

This function returns the sessionId that is encoded in the state, if the signature validates that it is an authentic state generated by encodeState().

◆ description()

const std::string& Wt::Auth::Saml::Service::description ( ) const

Returns the provider description.

This returns a description useful for e.g. tooltips on a login icon.

See also: name(); setDescription()

◆ encodeState()

std::string Wt::Auth::Saml::Service::encodeState ( const std::string & url ) const

Derives a state value from the session ID.

The state value protects the authorization protocol against misuse, and is used to connect an authorization code response with a particular request.

In the default implementation the state is the sessionId, cryptographically signed. This signature is verified in decodeState().

◆ idpEntityId()

const std::string& Wt::Auth::Saml::Service::idpEntityId ( ) const

Gets the entity ID of the IdP.

See also: setIdpEntityId()

◆ initialize()

void Wt::Auth::Saml::Service::initialize ( )

Initializes the Service so it is ready for use.

This function should be called after the Service is configured and before the service can be used (i.e. before metadata() or createProcess() are called).

No settings should be changed after the Service has been initialized.

Note: This will call configureLogging() and configureXmlSecurity() in order to set up the global logging configuration of log4shib and algorithm whitelists or blacklist. If you do not want the Saml Service to configure these, or configure them differently, you can override configureLogging() and configureXmlSecurity().

See also: configureLogging(); configureXmlSecurity()

◆ metadata()

std::string Wt::Auth::Saml::Service::metadata ( ) const

Returns the SPs metadata as XML.

The result is an XML string with an <EntityDescriptor> containing one <SPSSODescriptor> describing this SP.

See saml-metadata-2.0-os, sections 2.3.2 and 2.4.4

◆ metadataPath()

const std::string& Wt::Auth::Saml::Service::metadataPath ( ) const

Returns the path at which the metadata of this SP will be made available.

See also: setMetadataPath()

◆ metadataProviderPath()

const std::string& Wt::Auth::Saml::Service::metadataProviderPath ( ) const

Returns the path to the XML file that describes the metadata provider.

See also: setMatadataProviderPath()

◆ name()

const std::string& Wt::Auth::Saml::Service::name ( ) const

Returns the provider name.

This is a short identifier.

See also: Identity::provider(); description(); setName()

◆ nameIdPolicyAllowCreate()

bool Wt::Auth::Saml::Service::nameIdPolicyAllowCreate ( ) const

Gets the AllowCreate parameter for the name id policy in the authentication request.

See also: setNameIdPolicyAllowCreate(); nameIdPolicyFormat()

◆ nameIdPolicyFormat()

const std::string& Wt::Auth::Saml::Service::nameIdPolicyFormat ( ) const

Gets the format for the name id policy in the authentication request.

See also: setNameIdPolicyFormat(); nameIdPolicyAllowCreate()

◆ popupEnabled()

bool Wt::Auth::Saml::Service::popupEnabled ( ) const

Returns if a popup is used for the login.

See also: setPopupEnabled()

◆ popupHeight()

int Wt::Auth::Saml::Service::popupHeight ( ) const

Returns the desire height for the popup window.

Defaults to 400 pixels.

See also: setPopupHeight(); popupWidth()

◆ popupWidth()

int Wt::Auth::Saml::Service::popupWidth ( ) const

Returns the desired width for the popup window.

Defaults to 670 pixels.

See also: setPopupWidth(); popupHeight()

◆ samlCatalogPath()

const std::string& Wt::Auth::Saml::Service::samlCatalogPath ( ) const

Returns the path of OpenSAML's saml20-catalog.xml file.

See also: setSamlCatalogPath()

◆ setAcsUrl()

void Wt::Auth::Saml::Service::setAcsUrl ( const std::string & url )

Sets the Assertion Consumer Service URL.

This should be an absolute URL. E.g. if your application is deployed on https://sp.example.com, then your ACS URL could be https://sp.example.com/acs. This is the URL that responses will be sent to.

◆ setAuthnContextClassRef()

void Wt::Auth::Saml::Service::setAuthnContextClassRef ( const std::string & authnContextClassRef )

Sets the authentication context class to use in the authentication request.

This defaults to urn:oasis:names:tc:SAML:2.0:ac:classes:Password.

Set to empty to omit the authentication context class altogether.

See also: setAuthnContextComparison

◆ setAuthnContextComparison()

void Wt::Auth::Saml::Service::setAuthnContextComparison ( AuthnContextComparison comparison )

Sets the comparison to use in the authentication context of the authentication request.

This defaults to AuthnContextComparison::Exact.

See also: setAuthnContextClassRef()

◆ setCredentialResolverPath()

void Wt::Auth::Saml::Service::setCredentialResolverPath ( const std::string & path )

Sets the path to the XML that describes the credential resolver.

This is used to resolve signing (and encryption) credentials for this SP, used to sign authentication requests and decrypt encrypted assertions, subject ids, or attributes.

Example XML file:

<?xml version="1.0" encoding="UTF-8"?>
<CredentialResolver type="Chaining"
  <CredentialResolver type="File" use="signing">
    <Key>
      <Path>/path/to/signing.pem</Path>
    </Key>
    <Certificate>
      <Path>/path/to/signing.crt</Path>
    </Certificate>
  </CredentialResolver>
  <CredentialResolver type="File" use="encryption">
    <Key>
      <Path>/path/to/encryption.pem</Path>
    </Key>
    <Certificate>
      <Path>/path/to/encryption.crt</Path>
    </Certificate>
  </CredentialResolver>
</CredentialResolver>

See the Shibboleth SP documentation on CredentialResolvers for more info.

◆ setDescription()

void Wt::Auth::Saml::Service::setDescription ( const std::string & description )

Sets the provider description.

This sets a description useful for e.g. tooltips on a login icon.

See also: setName()

◆ setMetadataPath()

void Wt::Auth::Saml::Service::setMetadataPath ( const std::string & path )

Sets the path at which the metadata of this SP will be made available.

For example, if your application is deployed at https://sp.example.com, and the path is set to /metadata.xml, then the metadata XML will be made available at https://sp.example.com/metadata.xml.

This is left empty by default. If left empty, no metadata endpoint will be created.

◆ setMetadataProviderPath()

void Wt::Auth::Saml::Service::setMetadataProviderPath ( const std::string & path )

Sets the path to the XML file that describes the metadata provider.

This is used to get the metadata of the IdP, like the signing key and Single Sign On endpoint.

Example XML file:

<?xml version="1.0" encoding="UTF-8"?>
<MetadataProvider type="XML" path="/path/to/metadata.xml" validate="0">
  <KeyInfoResolver type="Inline" keyInfoReferences="true" />
</MetadataProvider>

See the Shibboleth SP documentation on MetadataProviders for more info.

◆ setName()

void Wt::Auth::Saml::Service::setName ( const std::string & name )

Sets the provider name.

This is a short identifier.

See also: Identity::provider(); setDescription()

◆ setNameIdPolicyAllowCreate()

void Wt::Auth::Saml::Service::setNameIdPolicyAllowCreate ( bool allowCreate )

Sets the AllowCreate parameter for the name id policy in the authentication request.

This defaults to true.

See also: setNameIdPolicyFormat()

◆ setNameIdPolicyFormat()

void Wt::Auth::Saml::Service::setNameIdPolicyFormat ( const std::string & format )

Sets the format for the name id policy in the authentication request.

This defaults to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified (see saml-core-2.0-os, section 8.3).

Set to empty to omit the name id policy altogether.

See also: setNameIdPolicyAllowCreate()

◆ setPopupEnabled()

void Wt::Auth::Saml::Service::setPopupEnabled ( bool enable )

Configure if a popup should be used for the login.

When JavaScript is available and this is set to true, a popup will open for the authentication. By default, this is disabled, the session will be suspended and a redirect is used instead.

A timeout can be configured in wt_config.xml (see saml-redirect-timeout), or with setRedirectTimeout().

See also: popupEnabled()

◆ setPopupHeight()

void Wt::Auth::Saml::Service::setPopupHeight ( int popupHeight )

Sets the desired height for the popup window.

Defaults to 400 pixels.

See also: setPopupWidth()

◆ setPopupWidth()

void Wt::Auth::Saml::Service::setPopupWidth ( int popupWidth )

Sets the desired width for the popup window.

Defaults to 670 pixels.

See also: setPopupHeight()

◆ setRedirectTimeout()

void Wt::Auth::Saml::Service::setRedirectTimeout ( std::chrono::seconds timeout )

Sets the timeout to login when there is no popup.

If the user does not return to the application in time, then the session is destroyed.

By default the timeout is retrieved from the "saml-redirect-timeout" configuration property, or if that property is not present, the default timeout is equal to 10 minutes.

◆ setSamlCatalogPath()

void Wt::Auth::Saml::Service::setSamlCatalogPath ( const std::string & path )

Sets the path of OpenSAML's saml20-catalog.xml file.

This path is used to validate XML responses from the IdP. The schemas from OpenSAML are used to validate the XML of things like responses, assertions,...

On non-Windows, this defaults to /usr/share/xml/opensaml/saml20-catalog.xml. On Windows, this defaults to C:\ProgramData\Shibboleth\SP\xml\opensaml\saml20-catalog.xml.

This file is mandatory if XML validation is enabled (the default). Disabling XML validation is not recommended.

See also: setX

◆ setSecret()

void Wt::Auth::Saml::Service::setSecret ( const std::string & secret )

Sets the secret used when encoding the RelayState.

This RelayState is used so that responses can be routed to the right WApplication.

By default the secret is retrieved from the "saml-secret" configuration property, or if that property is not present, the secret generated automatically.

Note that when dedicated session processes are used, a fixed secret has to be set.

See also: encodeState(); decodeState()

◆ setSignaturePolicy()

void Wt::Auth::Saml::Service::setSignaturePolicy ( SignaturePolicy policy )

Sets the signature policy.

The SignaturePolicy determines which signatures should be present in the response of the identity provider (IdP).

This defaults to the most strict value of SignaturePolicy::SignedResponseAndAssertion.

Note: SignaturePolicy::Unsafe is not recommended for production use. As the name suggests is not secure and makes exploits trivial.

◆ setXmlToolingCatalogPath()

void Wt::Auth::Saml::Service::setXmlToolingCatalogPath ( const std::string & path )

Sets the path of XMLTooling's catalog.xml file.

This path is used to validate XML responses from the IdP. The schemas from XMLTooling are used to validate the XML of things like XML signatures.

On non-Windows, this defaults to /usr/share/xml/xmltooling/catalog.xml. On Windows, this defaults to C:\ProgramData\Shibboleth\SP\xml\xmltooling\catalog.xml.

This file is mandatory if XML validation is enabled (the default). Disabling XML validation is not recommended.

See also: setXmlValidationEnabled()

◆ setXmlValidationEnabled()

void Wt::Auth::Saml::Service::setXmlValidationEnabled ( bool enabled )

Sets whether responses should be validated against the XML schema.

This is enabled by default, and should preferably not be disabled.

◆ signaturePolicy()

SignaturePolicy Wt::Auth::Saml::Service::signaturePolicy ( ) const

Returns the current signature policy.

See also: setSignaturePolicy()

◆ spEntityId()

const std::string& Wt::Auth::Saml::Service::spEntityId ( ) const

Gets the entity ID of this SP.

See also: setSPEntityId()

◆ xmlToolingCatalogPath()

const std::string& Wt::Auth::Saml::Service::xmlToolingCatalogPath ( ) const

Returns the path of XMLTooling's catalog.xml file.

See also: setXMLToolingCatalogPath()

◆ xmlValidationEnabled()

bool Wt::Auth::Saml::Service::xmlValidationEnabled ( ) const

Retursn whether responses should be validated against the XML schema.

See also: setXmlValidationEnabled()

Public Member Functions

Protected Member Functions

Detailed Description

Metadata

Tested IdPs

Thread safety

Usage

Standards compliance notes

References

Constructor & Destructor Documentation

◆ ~Service()

Member Function Documentation

◆ acsPath()

◆ acsUrl()

◆ assertionToIdentity()

◆ authnContextClassRef()

◆ authnContextComparison()

◆ configureLogging()

◆ configureXmlSecurity()

◆ createProcess()

◆ credentialResolverPath()

◆ decodeState()

◆ description()

◆ encodeState()

◆ idpEntityId()

◆ initialize()

◆ metadata()

◆ metadataPath()

◆ metadataProviderPath()

◆ name()

◆ nameIdPolicyAllowCreate()

◆ nameIdPolicyFormat()

◆ popupEnabled()

◆ popupHeight()

◆ popupWidth()

◆ samlCatalogPath()

◆ setAcsUrl()

◆ setAuthnContextClassRef()

◆ setAuthnContextComparison()

◆ setCredentialResolverPath()

◆ setDescription()

◆ setMetadataPath()

◆ setMetadataProviderPath()

◆ setName()

◆ setNameIdPolicyAllowCreate()

◆ setNameIdPolicyFormat()

◆ setPopupEnabled()

◆ setPopupHeight()

◆ setPopupWidth()

◆ setRedirectTimeout()

◆ setSamlCatalogPath()

◆ setSecret()

◆ setSignaturePolicy()

◆ setXmlToolingCatalogPath()

◆ setXmlValidationEnabled()

◆ signaturePolicy()

◆ spEntityId()

◆ xmlToolingCatalogPath()

◆ xmlValidationEnabled()