shibsp::Application Class Referenceabstract

Interface to a Shibboleth Application instance. More...

`#include <shibsp/Application.h>`

Inheritance diagram for shibsp::Application:
[legend]
Collaboration diagram for shibsp::Application:
[legend]

## Public Member Functions

const ServiceProvider & | getServiceProvider () const
| Returns the owning ServiceProvider instance.
virtual const char * | getId () const
| Returns the Application's ID.
virtual const char * | getHash () const =0
| Returns a unique hash for the Application.
virtual std::string | getCookieName (const char *prefix, time_t *lifetime=nullptr) const
| @Deprecated
virtual std::pair< std::string, const char * > | getCookieNameProps (const char *prefix, time_t *lifetime=nullptr) const
| @Deprecated
virtual opensaml::saml2md::MetadataProvider * | getMetadataProvider (bool required=true) const =0
| Returns a MetadataProvider for use with this Application.
virtual xmltooling::TrustEngine * | getTrustEngine (bool required=true) const =0
| Returns a TrustEngine for use with this Application.
virtual AttributeExtractor * | getAttributeExtractor () const =0
| Returns an AttributeExtractor for use with this Application.
virtual AttributeFilter * | getAttributeFilter () const =0
| Returns an AttributeFilter for use with this Application.
virtual AttributeResolver * | getAttributeResolver () const =0
| Returns an AttributeResolver for use with this Application.
virtual xmltooling::CredentialResolver * | getCredentialResolver () const =0
| Returns the CredentialResolver instance associated with this Application.
virtual const PropertySet * | getRelyingParty (const opensaml::saml2md::EntityDescriptor *provider) const =0
| Returns configuration properties governing security interactions with a peer.
virtual const PropertySet * | getRelyingParty (const XMLCh *entityID) const =0
| Returns configuration properties governing security interactions with a named peer.
virtual const std::vector< const XMLCh * > * | getAudiences () const =0
virtual std::string | getNotificationURL (const char *request, bool front, unsigned int index) const =0
| Returns the designated notification URL, or an empty string if no more locations are specified.
virtual const std::vector< std::string > & | getRemoteUserAttributeIds () const =0
| Returns an array of attribute IDs to use as a REMOTE_USER value, in order of preference.
virtual void | clearHeader (SPRequest &request, const char *rawname, const char *cginame) const
| Ensures no value exists for a request header, allowing for application-specific customization.
virtual void | setHeader (SPRequest &request, const char *name, const char *value) const
| Sets a value for a request header allowing for application-specific customization.
virtual std::string | getSecureHeader (const SPRequest &request, const char *name) const
| Returns a non-spoofable request header value allowing for application-specific customization.
virtual void | clearAttributeHeaders (SPRequest &request) const
| Clears any headers that may be used to hold attributes after export.
virtual const SessionInitiator * | getDefaultSessionInitiator () const =0
| Returns the default SessionInitiator when automatically requesting a session.
virtual const SessionInitiator * | getSessionInitiatorById (const char *id) const =0
| Returns a SessionInitiator with a particular ID when automatically requesting a session.
virtual const Handler * | getDefaultAssertionConsumerService () const =0
| Returns the default AssertionConsumerService Handler for use in AuthnRequest messages.
virtual const Handler * | getAssertionConsumerServiceByIndex (unsigned short index) const =0
| Returns an AssertionConsumerService Handler with a particular index for use in AuthnRequest messages.
virtual const Handler * | getAssertionConsumerServiceByProtocol (const XMLCh *protocol, const char *binding=nullptr) const =0
| Returns an AssertionConsumerService Handler that supports a particular protocol "family" and optional binding.
virtual const Handler * | getHandler (const char *path) const =0
| Returns the Handler associated with a particular path/location.
virtual void | getHandlers (std::vector< const Handler * > &handlers) const =0
| Returns all registered Handlers.
virtual void | limitRedirect (const xmltooling::GenericRequest &request, const char *url) const
| Checks a proposed redirect URL against application-specific settings for legal redirects, such as same-host restrictions or allowed domains, and raises a SecurityPolicyException in the event of a violation.
Public Member Functions inherited from shibsp::PropertySet
virtual const PropertySet * | getParent () const =0
| Returns parent of this PropertySet, if any.
virtual void | setParent (const PropertySet *parent)=0
| Establishes a "parent" PropertySet to supply inherited settings.
virtual std::pair< bool, bool > | getBool (const char *name, const char *ns=nullptr) const =0
| Returns a boolean-valued property.
virtual std::pair< bool, const char * > | getString (const char *name, const char *ns=nullptr) const =0
| Returns a string-valued property.
virtual std::pair< bool, const XMLCh * > | getXMLString (const char *name, const char *ns=nullptr) const =0
| Returns a Unicode string-valued property.
virtual std::pair< bool, unsigned int > | getUnsignedInt (const char *name, const char *ns=nullptr) const =0
| Returns an unsigned integer-valued property.
virtual std::pair< bool, int > | getInt (const char *name, const char *ns=nullptr) const =0
| Returns an integer-valued property.
virtual const PropertySet * | getPropertySet (const char *name, const char *ns=shibspconstants::ASCII_SHIBSPCONFIG_NS) const =0
| Returns a nested property set.
virtual const xercesc::DOMElement * | getElement () const =0
| Returns a DOM element representing the property container, if any.

## Protected Member Functions

| Application (const ServiceProvider *sp)
| Constructor.

## Protected Attributes

const ServiceProvider * | m_sp
| Pointer to parent SP instance.
xmltooling::RWLock * | m_lock
| Shared lock for manipulating application state.
std::vector< std::pair< std::string, std::string > > | m_unsetHeaders
| Pairs of raw and normalized CGI header names to clear.

## Detailed Description

Interface to a Shibboleth Application instance.

An Application is a logical set of resources that act as a unit of session management and policy.

## Constructor & Destructor Documentation

## Application()

shibsp::Application::Application | ( | const ServiceProvider * | sp | ) |

protected

Constructor.

Parameters

  sp | parent ServiceProvider instance

## Member Function Documentation

## clearAttributeHeaders()

virtual void shibsp::Application::clearAttributeHeaders | ( | SPRequest & | request | ) | const

virtual

Clears any headers that may be used to hold attributes after export.

Parameters

  request | SP request to clear

## clearHeader()

virtual void shibsp::Application::clearHeader | ( | SPRequest & | request,
|  | const char * | rawname,
|  | const char * | cginame ) const

virtual

Ensures no value exists for a request header, allowing for application-specific customization.

Parameters

  request | SP request to modify
  rawname | raw name of header to clear
  cginame | CGI-equivalent name of header, MUST begin with "HTTP_".

Reimplemented in shibsp::XMLApplication.

## getAssertionConsumerServiceByIndex()

virtual const Handler * shibsp::Application::getAssertionConsumerServiceByIndex | ( | unsigned short | index | ) | const

pure virtual

Returns an AssertionConsumerService Handler with a particular index for use in AuthnRequest messages.

Parameters

  index | an index unique to an application

Returns
  the designated AssertionConsumerService, or nullptr

Implemented in shibsp::XMLApplication.

## getAssertionConsumerServiceByProtocol()

virtual const Handler * shibsp::Application::getAssertionConsumerServiceByProtocol | ( | const XMLCh * | protocol,
|  | const char * | binding = nullptr ) const

pure virtual

Returns an AssertionConsumerService Handler that supports a particular protocol "family" and optional binding.

Parameters

  protocol | a protocol identifier
  binding | a binding identifier

Returns
  a matching AssertionConsumerService, or nullptr

Implemented in shibsp::XMLApplication.

## getAttributeExtractor()

virtual AttributeExtractor * shibsp::Application::getAttributeExtractor | ( |  | ) | const

pure virtual

Returns an AttributeExtractor for use with this Application.

Returns
  an AttributeExtractor, or nullptr

Implemented in shibsp::XMLApplication.

## getAttributeFilter()

virtual AttributeFilter * shibsp::Application::getAttributeFilter | ( |  | ) | const

pure virtual

Returns an AttributeFilter for use with this Application.

Returns
  an AttributeFilter, or nullptr

Implemented in shibsp::XMLApplication.

## getAttributeResolver()

virtual AttributeResolver * shibsp::Application::getAttributeResolver | ( |  | ) | const

pure virtual

Returns an AttributeResolver for use with this Application.

Returns
  an AttributeResolver, or nullptr

Implemented in shibsp::XMLApplication.

## getAudiences()

virtual const std::vector< const XMLCh * > * shibsp::Application::getAudiences | ( |  | ) | const

pure virtual

Deprecated
  Returns any additional audience values associated with this Application.

Returns
  additional audience values associated with the Application, or nullptr

Implemented in shibsp::XMLApplication.

## getCookieName()

virtual std::string shibsp::Application::getCookieName | ( | const char * | prefix,
|  | time_t * | lifetime = nullptr ) const

virtual

@Deprecated

Returns the cookies name to use for this Application.

Parameters

  prefix | a value to prepend to the base cookie name
  lifetime | if non-null, will be populated with a suggested lifetime for the cookie, or 0 if session-bound

Returns
  the assigned cookie name to use

## getCookieNameProps()

virtual std::pair< std::string, const char * > shibsp::Application::getCookieNameProps | ( | const char * | prefix,
|  | time_t * | lifetime = nullptr ) const

virtual

@Deprecated

Returns the name and cookie properties to use for this Application.

Parameters

  prefix | a value to prepend to the base cookie name
  lifetime | if non-null, will be populated with a suggested lifetime for the cookie, or 0 if session-bound

Returns
  a pair containing the cookie name and the string to append to the cookie value

## getCredentialResolver()

virtual xmltooling::CredentialResolver * shibsp::Application::getCredentialResolver | ( |  | ) | const

pure virtual

Returns the CredentialResolver instance associated with this Application.

Returns
  a CredentialResolver, or nullptr

Implemented in shibsp::XMLApplication.

## getDefaultAssertionConsumerService()

virtual const Handler * shibsp::Application::getDefaultAssertionConsumerService | ( |  | ) | const

pure virtual

Returns the default AssertionConsumerService Handler for use in AuthnRequest messages.

Returns
  the default AssertionConsumerService, or nullptr

Implemented in shibsp::XMLApplication.

## getDefaultSessionInitiator()

virtual const SessionInitiator * shibsp::Application::getDefaultSessionInitiator | ( |  | ) | const

pure virtual

Returns the default SessionInitiator when automatically requesting a session.

Returns
  the default SessionInitiator, or nullptr

Implemented in shibsp::XMLApplication.

## getHandler()

virtual const Handler * shibsp::Application::getHandler | ( | const char * | path | ) | const

pure virtual

Returns the Handler associated with a particular path/location.

Parameters

  path | the PATH_INFO appended to the end of a base Handler location that invokes the Handler

Returns
  the mapped Handler, or nullptr

Implemented in shibsp::XMLApplication.

## getHandlers()

virtual void shibsp::Application::getHandlers | ( | std::vector< const Handler * > & | handlers | ) | const

pure virtual

Returns all registered Handlers.

Parameters

  handlers | array to populate

Implemented in shibsp::XMLApplication.

## getHash()

virtual const char * shibsp::Application::getHash | ( |  | ) | const

pure virtual

Returns a unique hash for the Application.

Returns
  a value resulting from a computation over the Application's configuration

Implemented in shibsp::XMLApplication.

## getId()

virtual const char * shibsp::Application::getId | ( |  | ) | const

virtual

Returns the Application's ID.

Returns
  the ID

## getMetadataProvider()

virtual opensaml::saml2md::MetadataProvider * shibsp::Application::getMetadataProvider | ( | bool | required = true | ) | const

pure virtual

Returns a MetadataProvider for use with this Application.

Parameters

  required | true iff an exception should be thrown if no MetadataProvider is available

Returns
  a MetadataProvider instance, or nullptr

Implemented in shibsp::XMLApplication.

## getNotificationURL()

virtual std::string shibsp::Application::getNotificationURL | ( | const char * | request,
|  | bool | front,
|  | unsigned int | index ) const

pure virtual

Returns the designated notification URL, or an empty string if no more locations are specified.

Parameters

  request | requested URL to use to fill in missing pieces of notification URL
  front | true iff front channel notification is desired, false iff back channel is desired
  index | zero-based index of URL to return

Returns
  the designated URL, or an empty string

Implemented in shibsp::XMLApplication.

## getRelyingParty() [1/2]

virtual const PropertySet * shibsp::Application::getRelyingParty | ( | const opensaml::saml2md::EntityDescriptor * | provider | ) | const

pure virtual

Returns configuration properties governing security interactions with a peer.

Parameters

  provider | a peer entity's metadata

Returns
  the applicable PropertySet

Implemented in shibsp::XMLApplication.

## getRelyingParty() [2/2]

virtual const PropertySet * shibsp::Application::getRelyingParty | ( | const XMLCh * | entityID | ) | const

pure virtual

Returns configuration properties governing security interactions with a named peer.

Parameters

  entityID | a peer name

Returns
  the applicable PropertySet

Implemented in shibsp::XMLApplication.

## getRemoteUserAttributeIds()

virtual const std::vector< std::string > & shibsp::Application::getRemoteUserAttributeIds | ( |  | ) | const

pure virtual

Returns an array of attribute IDs to use as a REMOTE_USER value, in order of preference.

Returns
  an array of attribute IDs, possibly empty

Implemented in shibsp::XMLApplication.

## getSecureHeader()

virtual std::string shibsp::Application::getSecureHeader | ( | const SPRequest & | request,
|  | const char * | name ) const

virtual

Returns a non-spoofable request header value allowing for application-specific customization.

Parameters

  request | SP request to access
  name | the name of the secure header to return

Returns
  the header's value, or an empty string

Reimplemented in shibsp::XMLApplication.

## getServiceProvider()

const ServiceProvider & shibsp::Application::getServiceProvider | ( |  | ) | const

Returns the owning ServiceProvider instance.

Returns
  a locked ServiceProvider

## getSessionInitiatorById()

virtual const SessionInitiator * shibsp::Application::getSessionInitiatorById | ( | const char * | id | ) | const

pure virtual

Returns a SessionInitiator with a particular ID when automatically requesting a session.

Parameters

  id | an identifier unique to the Application

Returns
  the designated SessionInitiator, or nullptr

Implemented in shibsp::XMLApplication.

## getTrustEngine()

virtual xmltooling::TrustEngine * shibsp::Application::getTrustEngine | ( | bool | required = true | ) | const

pure virtual

Returns a TrustEngine for use with this Application.

Parameters

  required | true iff an exception should be thrown if no TrustEngine is available

Returns
  a TrustEngine instance, or nullptr

Implemented in shibsp::XMLApplication.

## limitRedirect()

virtual void shibsp::Application::limitRedirect | ( | const xmltooling::GenericRequest & | request,
|  | const char * | url ) const

virtual

Checks a proposed redirect URL against application-specific settings for legal redirects, such as same-host restrictions or allowed domains, and raises a SecurityPolicyException in the event of a violation.

Parameters

  request | the request leading to the redirect
  url | an absolute URL to validate

Reimplemented in shibsp::XMLApplication.

## setHeader()

virtual void shibsp::Application::setHeader | ( | SPRequest & | request,
|  | const char * | name,
|  | const char * | value ) const

virtual

Sets a value for a request header allowing for application-specific customization.

Parameters

  request | SP request to modify
  name | name of header to set
  value | value to set

Reimplemented in shibsp::XMLApplication.

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

- shibsp/Application.h