Wt  4.7.2
Public Member Functions | Protected Member Functions | List of all members
Wt::Auth::Saml::Service Class Referenceabstract

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< ProcesscreateProcess () 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 AuthServicebaseAuth () 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:

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:

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)
{ }
{
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:

References

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

{
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

◆ 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
WExceptionif 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 detauls 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()

Generated on Thu May 12 2022 for the C++ Web Toolkit (Wt) by doxygen 1.8.13