shibsp/Application.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file shibsp/Application.h
  23  *
  24  * Interface to a Shibboleth Application instance.
  25  */
  26
  27 #ifndef __shibsp_app_h__
  28 #define __shibsp_app_h__
  29
  30 #include <shibsp/util/PropertySet.h>
  31
  32 #include <string>
  33 #include <vector>
  34 #ifndef SHIBSP_LITE
  35 # include <saml/binding/MessageEncoder.h>
  36 #endif
  37
  38 namespace xmltooling {
  39     class XMLTOOL_API CredentialResolver;
  40     class XMLTOOL_API GenericRequest;
  41     class XMLTOOL_API RWLock;
  42     class XMLTOOL_API SOAPTransport;
  43     class XMLTOOL_API StorageService;
  44     class XMLTOOL_API TrustEngine;
  45 };
  46
  47 #ifndef SHIBSP_LITE
  48 namespace opensaml {
  49     class SAML_API SecurityPolicyRule;
  50     namespace saml2md {
  51         class SAML_API MetadataProvider;
  52     };
  53 };
  54 #endif
  55
  56 namespace shibsp {
  57
  58 #ifndef SHIBSP_LITE
  59     class SHIBSP_API AttributeExtractor;
  60     class SHIBSP_API AttributeFilter;
  61     class SHIBSP_API AttributeResolver;
  62 #endif
  63     class SHIBSP_API Attribute;
  64     class SHIBSP_API Handler;
  65     class SHIBSP_API ServiceProvider;
  66     class SHIBSP_API SessionInitiator;
  67     class SHIBSP_API SPRequest;
  68
  69 #if defined (_MSC_VER)
  70     #pragma warning( push )
  71     #pragma warning( disable : 4251 )
  72 #endif
  73
  74     /**
  75      * Interface to a Shibboleth Application instance.
  76      *
  77      * <p>An Application is a logical set of resources that act as a unit
  78      * of session management and policy.
  79      */
  80     class SHIBSP_API Application : public virtual PropertySet
  81 #ifndef SHIBSP_LITE
  82         ,public virtual opensaml::MessageEncoder::ArtifactGenerator
  83 #endif
  84     {
  85         MAKE_NONCOPYABLE(Application);
  86     protected:
  87         /**
  88          * Constructor.
  89          *
  90          * @param sp    parent ServiceProvider instance
  91          */
  92         Application(const ServiceProvider* sp);
  93
  94         /** Pointer to parent SP instance. */
  95         const ServiceProvider* m_sp;
  96
  97         /** Shared lock for manipulating application state. */
  98         mutable xmltooling::RWLock* m_lock;
  99
 100         /** Pairs of raw and normalized CGI header names to clear. */
 101         mutable std::vector< std::pair<std::string,std::string> > m_unsetHeaders;
 102
 103     public:
 104         virtual ~Application();
 105
 106         /**
 107          * Returns the owning ServiceProvider instance.
 108          *
 109          * @return a locked ServiceProvider
 110          */
 111         const ServiceProvider& getServiceProvider() const;
 112
 113         /**
 114          * Returns the Application's ID.
 115          *
 116          * @return  the ID
 117          */
 118         virtual const char* getId() const;
 119
 120         /**
 121          * Returns a unique hash for the Application.
 122          *
 123          * @return a value resulting from a computation over the Application's configuration
 124          */
 125         virtual const char* getHash() const=0;
 126
 127         /**
 128          * Returns the name and cookie properties to use for this Application.
 129          *
 130          * @param prefix    a value to prepend to the base cookie name
 131          * @param lifetime  if non-null, will be populated with a suggested lifetime for the cookie, or 0 if session-bound
 132          * @return  a pair containing the cookie name and the string to append to the cookie value
 133          */
 134         virtual std::pair<std::string,const char*> getCookieNameProps(const char* prefix, time_t* lifetime=nullptr) const;
 135
 136 #ifndef SHIBSP_LITE
 137         /**
 138          * Returns a MetadataProvider for use with this Application.
 139          *
 140          * @param required  true iff an exception should be thrown if no MetadataProvider is available
 141          * @return  a MetadataProvider instance, or nullptr
 142          */
 143         virtual opensaml::saml2md::MetadataProvider* getMetadataProvider(bool required=true) const=0;
 144
 145         /**
 146          * Returns a TrustEngine for use with this Application.
 147          *
 148          * @param required  true iff an exception should be thrown if no TrustEngine is available
 149          * @return  a TrustEngine instance, or nullptr
 150          */
 151         virtual xmltooling::TrustEngine* getTrustEngine(bool required=true) const=0;
 152
 153         /**
 154          * Returns an AttributeExtractor for use with this Application.
 155          *
 156          * @return  an AttributeExtractor, or nullptr
 157          */
 158         virtual AttributeExtractor* getAttributeExtractor() const=0;
 159
 160         /**
 161          * Returns an AttributeFilter for use with this Application.
 162          *
 163          * @return  an AttributeFilter, or nullptr
 164          */
 165         virtual AttributeFilter* getAttributeFilter() const=0;
 166
 167         /**
 168          * Returns an AttributeResolver for use with this Application.
 169          *
 170          * @return  an AttributeResolver, or nullptr
 171          */
 172         virtual AttributeResolver* getAttributeResolver() const=0;
 173
 174         /**
 175          * Returns the CredentialResolver instance associated with this Application.
 176          *
 177          * @return  a CredentialResolver, or nullptr
 178          */
 179         virtual xmltooling::CredentialResolver* getCredentialResolver() const=0;
 180
 181         /**
 182          * Returns configuration properties governing security interactions with a peer.
 183          *
 184          * @param provider  a peer entity's metadata
 185          * @return  the applicable PropertySet
 186          */
 187         virtual const PropertySet* getRelyingParty(const opensaml::saml2md::EntityDescriptor* provider) const=0;
 188
 189         /**
 190          * Returns configuration properties governing security interactions with a named peer.
 191          *
 192          * @param entityID  a peer name
 193          * @return  the applicable PropertySet
 194          */
 195         virtual const PropertySet* getRelyingParty(const XMLCh* entityID) const=0;
 196
 197         /**
 198          * @deprecated
 199          * Returns any additional audience values associated with this Application.
 200          *
 201          * @return additional audience values associated with the Application, or nullptr
 202          */
 203         virtual const std::vector<const XMLCh*>* getAudiences() const=0;
 204 #endif
 205
 206         /**
 207          * Returns the designated notification URL, or an empty string if no more locations are specified.
 208          *
 209          * @param request   requested URL to use to fill in missing pieces of notification URL
 210          * @param front     true iff front channel notification is desired, false iff back channel is desired
 211          * @param index     zero-based index of URL to return
 212          * @return  the designated URL, or an empty string
 213          */
 214         virtual std::string getNotificationURL(const char* request, bool front, unsigned int index) const=0;
 215
 216         /**
 217          * Returns an array of attribute IDs to use as a REMOTE_USER value, in order of preference.
 218          *
 219          * @return  an array of attribute IDs, possibly empty
 220          */
 221         virtual const std::vector<std::string>& getRemoteUserAttributeIds() const=0;
 222
 223         /**
 224          * Ensures no value exists for a request header, allowing for application-specific customization.
 225          *
 226          * @param request  SP request to modify
 227          * @param rawname  raw name of header to clear
 228          * @param cginame  CGI-equivalent name of header, <strong>MUST</strong> begin with "HTTP_".
 229          */
 230         virtual void clearHeader(SPRequest& request, const char* rawname, const char* cginame) const;
 231
 232         /**
 233          * Sets a value for a request header allowing for application-specific customization.
 234          *
 235          * @param request   SP request to modify
 236          * @param name      name of header to set
 237          * @param value     value to set
 238          */
 239         virtual void setHeader(SPRequest& request, const char* name, const char* value) const;
 240
 241         /**
 242          * Returns a non-spoofable request header value allowing for application-specific customization.
 243          *
 244          * @param request   SP request to access
 245          * @param name      the name of the secure header to return
 246          * @return  the header's value, or an empty string
 247          */
 248         virtual std::string getSecureHeader(const SPRequest& request, const char* name) const;
 249
 250         /**
 251          * Clears any headers that may be used to hold attributes after export.
 252          *
 253          * @param request   SP request to clear
 254          */
 255         virtual void clearAttributeHeaders(SPRequest& request) const;
 256
 257         /**
 258          * Returns the default SessionInitiator when automatically requesting a session.
 259          *
 260          * @return the default SessionInitiator, or nullptr
 261          */
 262         virtual const SessionInitiator* getDefaultSessionInitiator() const=0;
 263
 264         /**
 265          * Returns a SessionInitiator with a particular ID when automatically requesting a session.
 266          *
 267          * @param id    an identifier unique to the Application
 268          * @return the designated SessionInitiator, or nullptr
 269          */
 270         virtual const SessionInitiator* getSessionInitiatorById(const char* id) const=0;
 271
 272         /**
 273          * Returns the default AssertionConsumerService Handler
 274          * for use in AuthnRequest messages.
 275          *
 276          * @return the default AssertionConsumerService, or nullptr
 277          */
 278         virtual const Handler* getDefaultAssertionConsumerService() const=0;
 279
 280         /**
 281          * Returns an AssertionConsumerService Handler with a particular index
 282          * for use in AuthnRequest messages.
 283          *
 284          * @param index an index unique to an application
 285          * @return the designated AssertionConsumerService, or nullptr
 286          */
 287         virtual const Handler* getAssertionConsumerServiceByIndex(unsigned short index) const=0;
 288
 289         /**
 290          * Returns an AssertionConsumerService Handler that supports
 291          * a particular protocol "family" and optional binding.
 292          *
 293          * @param protocol  a protocol identifier
 294          * @param binding   a binding identifier
 295          * @return a matching AssertionConsumerService, or nullptr
 296          */
 297         virtual const Handler* getAssertionConsumerServiceByProtocol(const XMLCh* protocol, const char* binding=nullptr) const;
 298
 299         /**
 300          * @deprecated
 301          * Returns one or more AssertionConsumerService Handlers that support
 302          * a particular protocol binding.
 303          *
 304          * @param binding   a protocol binding identifier
 305          * @return a set of qualifying AssertionConsumerServices
 306          */
 307         virtual const std::vector<const Handler*>& getAssertionConsumerServicesByBinding(const XMLCh* binding) const=0;
 308
 309         /**
 310          * Returns the Handler associated with a particular path/location.
 311          *
 312          * @param path  the PATH_INFO appended to the end of a base Handler location
 313          *              that invokes the Handler
 314          * @return the mapped Handler, or nullptr
 315          */
 316         virtual const Handler* getHandler(const char* path) const=0;
 317
 318         /**
 319          * Returns all registered Handlers.
 320          *
 321          * @param handlers  array to populate
 322          */
 323         virtual void getHandlers(std::vector<const Handler*>& handlers) const=0;
 324
 325         /**
 326          * Checks a proposed redirect URL against application-specific settings for legal redirects,
 327          * such as same-host restrictions or whitelisted domains, and raises a SecurityPolicyException
 328          * in the event of a violation.
 329          *
 330          * @param request   the request leading to the redirect
 331          * @param url       an absolute URL to validate
 332          */
 333         virtual void limitRedirect(const xmltooling::GenericRequest& request, const char* url) const;
 334     };
 335
 336 #if defined (_MSC_VER)
 337     #pragma warning( pop )
 338 #endif
 339
 340 };
 341
 342 #endif /* __shibsp_app_h__ */