shibboleth-3.5.0

Public Member Functions | Protected Member Functions | List of all members
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:

## 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...
virtual const XMLCh * | getProtocolFamily () const
| Returns an identifier for the protocol family associated with the handler, if any. More...
virtual std::pair< bool, long > | run (SPRequest &request, bool isHandler=true) const =0
| Executes handler functionality as an incoming request. More...
virtual void | generateMetadata (opensaml::saml2md::SPSSODescriptor &role, const char *handlerURL) const
| Generates and/or modifies metadata reflecting the Handler. More...
virtual const char * | getType () const
| Returns the "type" of the Handler plugin. More...
virtual const char * | getEventType () const
| Get the type of event, as input to error handling in response to errors raised by this handler. More...
virtual const PropertySet * | getParent () const =0
| Returns parent of this PropertySet, if any. More...
virtual void | setParent (const PropertySet *parent)=0
| Establishes a "parent" PropertySet to supply inherited settings. More...
virtual std::pair< bool, bool > | getBool (const char *name, const char *ns=nullptr) const =0
| Returns a boolean-valued property. More...
virtual std::pair< bool, const char * > | getString (const char *name, const char *ns=nullptr) const =0
| Returns a string-valued property. More...
virtual std::pair< bool, const XMLCh * > | getXMLString (const char *name, const char *ns=nullptr) const =0
| Returns a Unicode string-valued property. More...
virtual std::pair< bool, unsigned int > | getUnsignedInt (const char *name, const char *ns=nullptr) const =0
| Returns an unsigned integer-valued property. More...
virtual std::pair< bool, int > | getInt (const char *name, const char *ns=nullptr) const =0
| Returns an integer-valued property. More...
virtual const PropertySet * | getPropertySet (const char *name, const char *ns=shibspconstants::ASCII_SHIBSPCONFIG_NS) const =0
| Returns a nested property set. More...
virtual const xercesc::DOMElement * | getElement () const =0
| Returns a DOM element representing the property container, if any. More...
Public Member Functions inherited from shibsp::DOMPropertySet
const PropertySet * | getParent () 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 PropertySet * | getPropertySet (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...
virtual void | receive (DDF &in, std::ostream &out)=0
| Remoted classes implement this method to process incoming messages. 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...
ResolutionContext * | 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
| Attempt SSO-initiated attribute resolution using the supplied information, including NameID and token extraction and filtering followed by secondary resolution. More...
virtual LoginEvent * | newLoginEvent (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
| 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, 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...
Protected Member Functions inherited from shibsp::Handler
virtual void | log (SPRequest::SPLogLevel level, const std::string &msg) const
| Log using handler's specific logging object. More...
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
| @Deprecated More...
xmltooling::HTTPResponse * | getResponse (DDF &out) const
| @Deprecated More...

## 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.
Protected Attributes inherited from shibsp::RemotedHandler
std::string | m_address
| Message address for remote half.

## 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

  e | root of DOM configuration
  appId | ID of application that "owns" the handler
  log | a logging object to use
  filter | optional filter controls what child elements to include as nested PropertySets
  remapper | optional property rename mapper for legacy property support
  deprecationSupport | true 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

  application | reference to application receiving message
  httpRequest | client request that initiated session
  issuedTo | address for which security assertion was issued

## ◆ extractMessageDetails()

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

Extracts policy-relevant assertion details.

Parameters

  assertion | the incoming assertion
  protocol | the protocol family in use
  policy | SecurityPolicy 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
| protected virtual

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

Parameters

  application | reference to application receiving message
  httpRequest | client request that included message
  httpResponse | response to client
  relayState | relay state token

## ◆ generateMetadata()

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

Generates and/or modifies metadata reflecting the Handler.

The default implementation does nothing.

Parameters

  role | metadata role to decorate
  handlerURL | base 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
| protected virtual

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
| protected pure 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

  application | reference to application receiving message
  httpRequest | client request that included message
  httpResponse | response to client
  policy | the SecurityPolicy in effect, after having evaluated the message
  reserved | ignore this parameter
  xmlObject | a protocol-specific message object

## ◆ newLoginEvent()

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

Creates a new LoginEvent for the event log.

Parameters

  application | the Application associated with the event
  request | the 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

  in | incoming DDF message
  out | stream 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

  application | reference to application receiving message
  request | request delivering message, if any
  issuer | source of SSO tokens
  protocol | SSO protocol used
  protmsg | SSO protocol message, if any
  v1nameid | identifier of principal in SAML 1.x form, if any
  v1statement | SAML 1.x authentication statement, if any
  nameid | identifier of principal in SAML 2.0 form
  statement | SAML 2.0 authentication statement, if any
  authncontext_class | method/category of authentication event, if known
  authncontext_decl | specifics of authentication event, if known
  tokens | available 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

  request | SP request context
  isHandler | true 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:

- shibsp/handler/AssertionConsumerService.h