shibboleth-2.6.0

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

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...
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...
void | getAll (std::map< std::string, const char * > &properties) const
| Returns a map of all known properties in string form. More...
const PropertySet * | getPropertySet (const char *name, const char *ns=shibspconstants::ASCII_SHIB2SPCONFIG_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 std::map< std::string, std::string > *remapper=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 std::map< std::string, std::string > *remapper=nullptr)
| 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 opensaml::SecurityPolicy * | createSecurityPolicy (const Application &application, const xmltooling::QName *role, bool validate, const char *policyId) const
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 opensaml::saml2md::RoleDescriptor *issuer=nullptr, const XMLCh *protocol=nullptr, const opensaml::saml1::NameIdentifier *v1nameid=nullptr, const opensaml::saml2::NameID *nameid=nullptr, const XMLCh *authncontext_class=nullptr, const XMLCh *authncontext_decl=nullptr, const std::vector< const opensaml::Assertion * > *tokens=nullptr) const
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 std::map< std::string, std::string > *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...
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, bool signIfPossible=false) const
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...
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...
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 (DDF &in) const
| Builds a new request instance around a remoted data object. More...
xmltooling::HTTPResponse * | getResponse (DDF &out) const
| Builds a new response instance around an outgoing data object. 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. More...
xmltooling::auto_ptr_char | m_configNS
| Configuration namespace for custom properties. 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

shibsp::AssertionConsumerService::AssertionConsumerService | ( | const xercesc::DOMElement * | e,
|  | const char * | appId,
|  | xmltooling::logging::Category & | log,
|  | xercesc::DOMNodeFilter * | filter = `nullptr`,
|  | const std::map< std::string, std::string > * | remapper = `nullptr`
| ) |  |
| 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 map of property rename rules for legacy property support

## Member Function Documentation

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

virtual opensaml::SecurityPolicy* shibsp::AssertionConsumerService::createSecurityPolicy | ( | const Application & | application,
|  | const xmltooling::QName * | role,
|  | bool | validate,
|  | const char * | policyId
| ) |  | const
| protected virtual

Deprecated:
  Returns a SecurityPolicy instance to use for an incoming request.

Allows handlers to customize the type of policy object their policy rules might require.

The caller MUST lock the application's MetadataProvider for the life of the returned object.

Parameters

  application | reference to application receiving message
  role | identifies the role (generally IdP or SP) of the policy peer
  validate | true iff XML parsing should be done with validation
  policyId | identifies policy rules to auto-attach, defaults to the application's set

Returns
  a new policy instance, which the caller is responsible for freeing

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

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

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.

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.

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.

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

Returns the "type" of the Handler plugin.

Returns
  a Handler type

Reimplemented from shibsp::Handler.

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

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

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.

ResolutionContext* shibsp::AssertionConsumerService::resolveAttributes | ( | const Application & | application,
|  | const opensaml::saml2md::RoleDescriptor * | issuer = `nullptr`,
|  | const XMLCh * | protocol = `nullptr`,
|  | const opensaml::saml1::NameIdentifier * | v1nameid = `nullptr`,
|  | const opensaml::saml2::NameID * | nameid = `nullptr`,
|  | const XMLCh * | authncontext_class = `nullptr`,
|  | const XMLCh * | authncontext_decl = `nullptr`,
|  | const std::vector< const opensaml::Assertion * > * | tokens = `nullptr`
| ) |  | const
| protected

Deprecated:
  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
  issuer | source of SSO tokens
  protocol | SSO protocol used
  v1nameid | identifier of principal in SAML 1.x form, if any
  nameid | identifier of principal in SAML 2.0 form
  authncontext_class | method/category of authentication event, if known
  authncontext_decl | specifics of authentication event, if known
  tokens | available assertions, if any

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

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