shibboleth-3.4.1
shibsp::AssertionConsumerService Class Referenceabstract

Base class for handlers that create sessions by consuming SSO protocol responses. More...

#include <shibsp/handler/AssertionConsumerService.h>

Inheritance diagram for shibsp::AssertionConsumerService:
shibsp::AbstractHandler shibsp::RemotedHandler shibsp::Handler shibsp::DOMPropertySet shibsp::Handler shibsp::Remoted shibsp::PropertySet shibsp::PropertySet shibsp::PropertySet

Public Member Functions

std::pair< bool, long > run (SPRequest &request, bool isHandler=true) const
 Executes handler functionality as an incoming request. More...
 
void receive (DDF &in, std::ostream &out)
 Remoted classes implement this method to process incoming messages. More...
 
const char * getType () const
 Returns the "type" of the Handler plugin. More...
 
const XMLCh * getProtocolFamily () const
 Returns an identifier for the protocol family associated with the handler, if any. More...
 
const char * getEventType () const
 Get the type of event, as input to error handling in response to errors raised by this handler. More...
 
- Public Member Functions inherited from shibsp::DOMPropertySet
const PropertySetgetParent () const
 Returns parent of this PropertySet, if any. More...
 
void setParent (const PropertySet *parent)
 Establishes a "parent" PropertySet to supply inherited settings. More...
 
std::pair< bool, bool > getBool (const char *name, const char *ns=nullptr) const
 Returns a boolean-valued property. More...
 
std::pair< bool, const char * > getString (const char *name, const char *ns=nullptr) const
 Returns a string-valued property. More...
 
std::pair< bool, const XMLCh * > getXMLString (const char *name, const char *ns=nullptr) const
 Returns a Unicode string-valued property. More...
 
std::pair< bool, unsigned int > getUnsignedInt (const char *name, const char *ns=nullptr) const
 Returns an unsigned integer-valued property. More...
 
std::pair< bool, int > getInt (const char *name, const char *ns=nullptr) const
 Returns an integer-valued property. More...
 
const PropertySetgetPropertySet (const char *name, const char *ns=shibspconstants::ASCII_SHIBSPCONFIG_NS) const
 Returns a nested property set. More...
 
const xercesc::DOMElement * getElement () const
 Returns a DOM element representing the property container, if any. More...
 
void load (const xercesc::DOMElement *e, xmltooling::logging::Category *log=nullptr, xercesc::DOMNodeFilter *filter=nullptr, const Remapper *remapper=nullptr, const xmltooling::QName *unsetter=nullptr)
 Loads the property set from a DOM element. More...
 

Protected Member Functions

 AssertionConsumerService (const xercesc::DOMElement *e, const char *appId, xmltooling::logging::Category &log, xercesc::DOMNodeFilter *filter=nullptr, const Remapper *remapper=nullptr, bool deprecationSupport=true)
 Constructor. More...
 
void checkAddress (const Application &application, const xmltooling::HTTPRequest &httpRequest, const char *issuedTo) const
 Enforce address checking requirements. More...
 
virtual std::pair< bool, long > finalizeResponse (const Application &application, const xmltooling::HTTPRequest &httpRequest, xmltooling::HTTPResponse &httpResponse, std::string &relayState) const
 Complete the client's transition back to the expected resource. More...
 
void generateMetadata (opensaml::saml2md::SPSSODescriptor &role, const char *handlerURL) const
 Generates and/or modifies metadata reflecting the Handler. More...
 
virtual const char * getProfile () const
 Returns a profile identifier to inject into the SecurityPolicy created by the base class. More...
 
virtual void implementProtocol (const Application &application, const xmltooling::HTTPRequest &httpRequest, xmltooling::HTTPResponse &httpResponse, opensaml::SecurityPolicy &policy, const PropertySet *reserved, const xmltooling::XMLObject &xmlObject) const =0
 Implement protocol-specific handling of the incoming decoded message. More...
 
virtual void extractMessageDetails (const opensaml::Assertion &assertion, const XMLCh *protocol, opensaml::SecurityPolicy &policy) const
 Extracts policy-relevant assertion details. More...
 
ResolutionContextresolveAttributes (const Application &application, const xmltooling::GenericRequest *request=nullptr, const opensaml::saml2md::RoleDescriptor *issuer=nullptr, const XMLCh *protocol=nullptr, const xmltooling::XMLObject *protmsg=nullptr, const opensaml::saml1::NameIdentifier *v1nameid=nullptr, const opensaml::saml1::AuthenticationStatement *v1statement=nullptr, const opensaml::saml2::NameID *nameid=nullptr, const opensaml::saml2::AuthnStatement *statement=nullptr, const XMLCh *authncontext_class=nullptr, const XMLCh *authncontext_decl=nullptr, const std::vector< const opensaml::Assertion *> *tokens=nullptr) const
 Attempt SSO-initiated attribute resolution using the supplied information, including NameID and token extraction and filtering followed by secondary resolution. More...
 
virtual LoginEventnewLoginEvent (const Application &application, const xmltooling::HTTPRequest &request) const
 Creates a new LoginEvent for the event log. More...
 
- Protected Member Functions inherited from shibsp::AbstractHandler
 AbstractHandler (const xercesc::DOMElement *e, xmltooling::logging::Category &log, xercesc::DOMNodeFilter *filter=nullptr, const Remapper *remapper=nullptr)
 Constructor. More...
 
void log (SPRequest::SPLogLevel level, const std::string &msg) const
 Log using handler's specific logging object. More...
 
virtual void checkError (const xmltooling::XMLObject *response, const opensaml::saml2md::RoleDescriptor *role=nullptr) const
 Examines a protocol response message for errors and raises an annotated exception if an error is found. More...
 
void fillStatus (opensaml::saml2p::StatusResponseType &response, const XMLCh *code, const XMLCh *subcode=nullptr, const char *msg=nullptr) const
 Prepares Status information in a SAML 2.0 response. More...
 
long sendMessage (const opensaml::MessageEncoder &encoder, xmltooling::XMLObject *msg, const char *relayState, const char *destination, const opensaml::saml2md::RoleDescriptor *role, const Application &application, xmltooling::HTTPResponse &httpResponse, const char *defaultSigningProperty) const
 Encodes and sends SAML 2.0 message, optionally signing it in the process. More...
 
virtual void preservePostData (const Application &application, const xmltooling::HTTPRequest &request, xmltooling::HTTPResponse &response, const char *relayState) const
 Implements a mechanism to preserve form post data. More...
 
virtual DDF recoverPostData (const Application &application, const xmltooling::HTTPRequest &request, xmltooling::HTTPResponse &response, const char *relayState) const
 Implements storage service and cookie mechanism to recover PostData. More...
 
virtual long sendPostResponse (const Application &application, xmltooling::HTTPResponse &response, const char *url, DDF &postData) const
 Post a redirect response with post data. More...
 
std::pair< bool, bool > getBool (const char *name, const xmltooling::HTTPRequest &request, unsigned int type=HANDLER_PROPERTY_ALL) const
 Returns a boolean-valued property. More...
 
std::pair< bool, const char * > getString (const char *name, const xmltooling::HTTPRequest &request, unsigned int type=HANDLER_PROPERTY_ALL) const
 Returns a string-valued property. More...
 
std::pair< bool, unsigned int > getUnsignedInt (const char *name, const xmltooling::HTTPRequest &request, unsigned int type=HANDLER_PROPERTY_ALL) const
 Returns an unsigned integer-valued property. More...
 
std::pair< bool, int > getInt (const char *name, const xmltooling::HTTPRequest &request, unsigned int type=HANDLER_PROPERTY_ALL) const
 Returns an integer-valued property. More...
 
std::pair< bool, bool > getBool (const char *name, const char *ns=nullptr) const
 
std::pair< bool, const char *> getString (const char *name, const char *ns=nullptr) const
 
std::pair< bool, unsigned int > getUnsignedInt (const char *name, const char *ns=nullptr) const
 
std::pair< bool, int > getInt (const char *name, const char *ns=nullptr) const
 
- Protected Member Functions inherited from shibsp::Handler
virtual void cleanRelayState (const Application &application, const xmltooling::HTTPRequest &request, xmltooling::HTTPResponse &response) const
 Prevents unused relay state from building up by cleaning old state from the client. More...
 
virtual void preserveRelayState (const Application &application, xmltooling::HTTPResponse &response, std::string &relayState) const
 Implements various mechanisms to preserve RelayState, such as cookies or StorageService-backed keys. More...
 
virtual void recoverRelayState (const Application &application, const xmltooling::HTTPRequest &request, xmltooling::HTTPResponse &response, std::string &relayState, bool clear=true) const
 Implements various mechanisms to recover RelayState, such as cookies or StorageService-backed keys. More...
 
- Protected Member Functions inherited from shibsp::DOMPropertySet
bool setProperty (const char *name, const char *val, const char *ns=nullptr)
 Post-load injection of a property, for use by subclasses. More...
 
- Protected Member Functions inherited from shibsp::RemotedHandler
void setAddress (const char *address)
 Establishes message remoting using the supplied address. More...
 
virtual DDF send (const SPRequest &request, DDF &in) const
 Send a remoted message and return the response. More...
 
DDF wrap (const SPRequest &request, const std::vector< std::string > *headers=nullptr, bool certs=false) const
 Wraps a request by creating an outgoing data flow with the data needed to remote the request information. More...
 
virtual std::pair< bool, long > unwrap (SPRequest &request, DDF &out) const
 Unwraps a response by examining an incoming data flow to determine whether a response was produced by the remoted handler. More...
 
xmltooling::HTTPRequest * getRequest (const Application &app, DDF &in) const
 Builds a new request instance around a remoted data object. More...
 
xmltooling::HTTPResponse * getResponse (const Application &app, DDF &out) const
 Builds a new response instance around an outgoing data object. More...
 
xmltooling::HTTPRequest * getRequest (DDF &in) const
 
xmltooling::HTTPResponse * getResponse (DDF &out) const
 

Additional Inherited Members

- Static Public Member Functions inherited from shibsp::RemotedHandler
static void addRemotedHeader (const char *header)
 Ensures that a request header will be remoted. More...
 
- Protected Types inherited from shibsp::AbstractHandler
enum  PropertySourceTypes { HANDLER_PROPERTY_REQUEST = 1, HANDLER_PROPERTY_MAP = 2, HANDLER_PROPERTY_FIXED = 4, HANDLER_PROPERTY_ALL = 255 }
 Bitmask of property sources to read from (request query parameter, request mapper, fixed handler property).
 
- Protected Attributes inherited from shibsp::AbstractHandler
xmltooling::logging::Category & m_log
 Logging object. More...
 
- Protected Attributes inherited from shibsp::RemotedHandler
std::string m_address
 Message address for remote half. More...
 

Detailed Description

Base class for handlers that create sessions by consuming SSO protocol responses.

Constructor & Destructor Documentation

◆ AssertionConsumerService()

shibsp::AssertionConsumerService::AssertionConsumerService ( const xercesc::DOMElement *  e,
const char *  appId,
xmltooling::logging::Category &  log,
xercesc::DOMNodeFilter *  filter = nullptr,
const Remapper remapper = nullptr,
bool  deprecationSupport = true 
)
protected

Constructor.

Parameters
eroot of DOM configuration
appIdID of application that "owns" the handler
loga logging object to use
filteroptional filter controls what child elements to include as nested PropertySets
remapperoptional property rename mapper for legacy property support
deprecationSupporttrue iff deprecated settings and features should be supported

Member Function Documentation

◆ checkAddress()

void shibsp::AssertionConsumerService::checkAddress ( const Application application,
const xmltooling::HTTPRequest &  httpRequest,
const char *  issuedTo 
) const
protected

Enforce address checking requirements.

Parameters
applicationreference to application receiving message
httpRequestclient request that initiated session
issuedToaddress for which security assertion was issued

◆ extractMessageDetails()

virtual void shibsp::AssertionConsumerService::extractMessageDetails ( const opensaml::Assertion &  assertion,
const XMLCh *  protocol,
opensaml::SecurityPolicy &  policy 
) const
protectedvirtual

Extracts policy-relevant assertion details.

Parameters
assertionthe incoming assertion
protocolthe protocol family in use
policySecurityPolicy to provide various components and track message data

◆ finalizeResponse()

virtual std::pair<bool,long> shibsp::AssertionConsumerService::finalizeResponse ( const Application application,
const xmltooling::HTTPRequest &  httpRequest,
xmltooling::HTTPResponse &  httpResponse,
std::string &  relayState 
) const
protectedvirtual

Complete the client's transition back to the expected resource.

Parameters
applicationreference to application receiving message
httpRequestclient request that included message
httpResponseresponse to client
relayStaterelay state token

◆ generateMetadata()

void shibsp::AssertionConsumerService::generateMetadata ( opensaml::saml2md::SPSSODescriptor &  role,
const char *  handlerURL 
) const
protectedvirtual

Generates and/or modifies metadata reflecting the Handler.

The default implementation does nothing.

Parameters
rolemetadata role to decorate
handlerURLbase location of handler's endpoint

Reimplemented from shibsp::Handler.

◆ getEventType()

const char* shibsp::AssertionConsumerService::getEventType ( ) const
virtual

Get the type of event, as input to error handling in response to errors raised by this handler.

Returns
an event type for error handling

Reimplemented from shibsp::Handler.

◆ getProfile()

virtual const char* shibsp::AssertionConsumerService::getProfile ( ) const
protectedvirtual

Returns a profile identifier to inject into the SecurityPolicy created by the base class.

Returns
profile identifier if any

◆ getProtocolFamily()

const XMLCh* shibsp::AssertionConsumerService::getProtocolFamily ( ) const
virtual

Returns an identifier for the protocol family associated with the handler, if any.

Returns
a protocol identifier, or nullptr

Reimplemented from shibsp::Handler.

◆ getType()

const char* shibsp::AssertionConsumerService::getType ( ) const
virtual

Returns the "type" of the Handler plugin.

Returns
a Handler type

Reimplemented from shibsp::Handler.

◆ implementProtocol()

virtual void shibsp::AssertionConsumerService::implementProtocol ( const Application application,
const xmltooling::HTTPRequest &  httpRequest,
xmltooling::HTTPResponse &  httpResponse,
opensaml::SecurityPolicy &  policy,
const PropertySet reserved,
const xmltooling::XMLObject &  xmlObject 
) const
protectedpure virtual

Implement protocol-specific handling of the incoming decoded message.

The result of implementing the protocol should be an exception or modifications to the request/response objects to reflect processing of the message.

Parameters
applicationreference to application receiving message
httpRequestclient request that included message
httpResponseresponse to client
policythe SecurityPolicy in effect, after having evaluated the message
reservedignore this parameter
xmlObjecta protocol-specific message object

◆ newLoginEvent()

virtual LoginEvent* shibsp::AssertionConsumerService::newLoginEvent ( const Application application,
const xmltooling::HTTPRequest &  request 
) const
protectedvirtual

Creates a new LoginEvent for the event log.

Parameters
applicationthe Application associated with the event
requestthe HTTP client request associated with the event
Returns
a fresh LoginEvent, prepopulated by the input parameters, or nullptr if an error occurs

◆ receive()

void shibsp::AssertionConsumerService::receive ( DDF in,
std::ostream &  out 
)
virtual

Remoted classes implement this method to process incoming messages.

Parameters
inincoming DDF message
outstream to write outgoing DDF message to

Implements shibsp::Remoted.

◆ resolveAttributes()

ResolutionContext* shibsp::AssertionConsumerService::resolveAttributes ( const Application application,
const xmltooling::GenericRequest *  request = nullptr,
const opensaml::saml2md::RoleDescriptor *  issuer = nullptr,
const XMLCh *  protocol = nullptr,
const xmltooling::XMLObject *  protmsg = nullptr,
const opensaml::saml1::NameIdentifier *  v1nameid = nullptr,
const opensaml::saml1::AuthenticationStatement *  v1statement = nullptr,
const opensaml::saml2::NameID *  nameid = nullptr,
const opensaml::saml2::AuthnStatement *  statement = nullptr,
const XMLCh *  authncontext_class = nullptr,
const XMLCh *  authncontext_decl = nullptr,
const std::vector< const opensaml::Assertion *> *  tokens = nullptr 
) const
protected

Attempt SSO-initiated attribute resolution using the supplied information, including NameID and token extraction and filtering followed by secondary resolution.

The caller must free the returned context handle.

Parameters
applicationreference to application receiving message
requestrequest delivering message, if any
issuersource of SSO tokens
protocolSSO protocol used
protmsgSSO protocol message, if any
v1nameididentifier of principal in SAML 1.x form, if any
v1statementSAML 1.x authentication statement, if any
nameididentifier of principal in SAML 2.0 form
statementSAML 2.0 authentication statement, if any
authncontext_classmethod/category of authentication event, if known
authncontext_declspecifics of authentication event, if known
tokensavailable assertions, if any

◆ run()

std::pair<bool,long> shibsp::AssertionConsumerService::run ( SPRequest request,
bool  isHandler = true 
) const
virtual

Executes handler functionality as an incoming request.

Handlers can be run either directly by incoming web requests or indirectly/implicitly during other SP processing.

Parameters
requestSP request context
isHandlertrue iff executing in the context of a direct handler invocation
Returns
a pair containing a "request completed" indicator and a server-specific response code

Implements shibsp::Handler.


The documentation for this class was generated from the following file: