shibresolver/resolver.h

   1 /*
   2  *  Copyright 2010 JANET(UK)
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file shibresolver/resolver.h
  19  *
  20  * An embeddable component interface to Shibboleth SP attribute processing.
  21  */
  22
  23 #ifndef __shibresolver_h__
  24 #define __shibresolver_h__
  25
  26 #include <shibresolver/base.h>
  27
  28 #include <shibsp/RequestMapper.h>
  29 #include <shibsp/SPConfig.h>
  30
  31 #include <string>
  32 #include <vector>
  33
  34 namespace xmltooling {
  35     class XMLTOOL_API XMLObject;
  36 };
  37
  38 namespace shibsp {
  39     class SHIBSP_API Attribute;
  40     class SHIBSP_API SPRequest;
  41 };
  42
  43 namespace shibresolver {
  44
  45 #if defined (_MSC_VER)
  46     #pragma warning( push )
  47     #pragma warning( disable : 4250 4251 )
  48 #endif
  49
  50     /**
  51      * An embeddable component interface to Shibboleth SP attribute processing.
  52      */
  53     class SHIBRESOLVER_API ShibbolethResolver
  54     {
  55         MAKE_NONCOPYABLE(ShibbolethResolver);
  56     protected:
  57         ShibbolethResolver();
  58     public:
  59         virtual ~ShibbolethResolver();
  60
  61         /**
  62          * Sets the calling service request, making the Shibboleth SP responsible for
  63          * mapping the service to an Application instance.
  64          *
  65          * @param request identifies the service request performing attribute resolution
  66          */
  67         void setRequest(const shibsp::SPRequest* request);
  68
  69         /**
  70          * Sets the application ID to use for resolution, bypassing the mapping
  71          * function of the Shibboleth SP.
  72          *
  73          * @param appID identifies an application in the SP configuration
  74          */
  75         void setApplicationID(const char* appID);
  76
  77         /**
  78          * Sets the identity issuer to use for resolution.
  79          *
  80          * @param issuer    entityID of the identity "source", if known
  81          */
  82         void setIssuer(const char* issuer);
  83
  84         /**
  85          * Adds an XML token as input to the resolver, generally a SAML assertion.
  86          * <p>The caller retains ownership of the object.
  87          *
  88          * @param token an input token to evaluate
  89          */
  90         void addToken(const xmltooling::XMLObject* token);
  91
  92         /**
  93          * Adds an Attribute as input to the resolver.
  94          * <p>The caller retains ownership of the object.
  95          *
  96          * @param attr  an input Attribute
  97          */
  98         void addAttribute(shibsp::Attribute* attr);
  99
 100         /**
 101          * Resolves Attributes and attaches them to the resolver object.
 102          * <p>The caller is responsible for transferring any Attributes it wishes to
 103          * retain out of the resolver.
 104          */
 105         virtual void resolve();
 106
 107         /**
 108          * Returns a modifiable array of resolved Attribute objects.
 109          * <p>The caller may take ownership of any or all by removing them
 110          * from the array.
 111          *
 112          * @return  array of resolved Attributes
 113          */
 114         std::vector<shibsp::Attribute*>& getResolvedAttributes();
 115
 116         /**
 117          * Returns mapped PropertySet and AccessControl objects, if any.
 118          *
 119          * @return  mapped PropertySet/AccesssControl pair
 120          */
 121         shibsp::RequestMapper::Settings getSettings() const;
 122
 123         /**
 124          * Initializes SP runtime objects based on an XML configuration string or a configuration pathname.
 125          * <p>Each process using the library MUST call this function exactly once before using any library classes.
 126          *
 127          * @param features  bitmask of SP components to enable
 128          * @param config    a snippet of XML to parse (it <strong>MUST</strong> contain a type attribute) or a pathname
 129          * @param rethrow   true iff caught exceptions should be rethrown instead of just returning a true/false result
 130          * @return true iff initialization was successful
 131          */
 132         static bool init(
 133 #ifdef SHIBSP_LITE
 134             unsigned long features = (shibsp::SPConfig::Listener|shibsp::SPConfig::InProcess),
 135 #else
 136             unsigned long features = shibsp::SPConfig::OutOfProcess,
 137 #endif
 138             const char* config = NULL,
 139             bool rethrow = false
 140             );
 141
 142         /**
 143          * Shuts down runtime.
 144          *
 145          * Each process using the library SHOULD call this function exactly once before terminating itself.
 146          */
 147         static void term();
 148
 149         /**
 150          * Returns a ShibbolethResolver instance.
 151          *
 152          * @return  a ShibbolethResolver instance, must be freed by the caller.
 153          */
 154         static ShibbolethResolver* create();
 155
 156     protected:
 157         /** Service request. */
 158         const shibsp::SPRequest* m_request;
 159
 160         /** Application ID. */
 161         std::string m_appID;
 162
 163         /** Source of identity, if known. */
 164         std::string m_issuer;
 165
 166         /** Input tokens. */
 167         std::vector<const xmltooling::XMLObject*> m_tokens;
 168
 169         /** Input attributes. */
 170         std::vector<shibsp::Attribute*> m_inputAttributes;
 171
 172     private:
 173         shibsp::ServiceProvider* m_sp;
 174         std::vector<shibsp::Attribute*> m_resolvedAttributes;
 175     };
 176
 177 #if defined (_MSC_VER)
 178     #pragma warning( pop )
 179 #endif
 180
 181 };
 182
 183 #endif /* __shibresolver_h__ */