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 #ifndef SHIBSP_LITE
  39 namespace opensaml {
  40     namespace saml2 {
  41         class SAML_API Assertion;
  42     };
  43 };
  44 #endif
  45
  46 namespace shibsp {
  47     class SHIBSP_API Attribute;
  48 };
  49
  50 namespace shibresolver {
  51
  52 #if defined (_MSC_VER)
  53     #pragma warning( push )
  54     #pragma warning( disable : 4250 4251 )
  55 #endif
  56
  57     /**
  58      * An embeddable component interface to Shibboleth SP attribute processing.
  59      */
  60     class SHIBRESOLVER_API ShibbolethResolver
  61     {
  62         MAKE_NONCOPYABLE(ShibbolethResolver);
  63     protected:
  64         ShibbolethResolver();
  65     public:
  66         virtual ~ShibbolethResolver();
  67
  68         /**
  69          * Sets the calling service URI, making the Shibboleth SP responsible for
  70          * mapping the service to an Application instance.
  71          *
  72          * @param uri identifies the service performing attribute resolution
  73          */
  74         void setServiceURI(const char* uri);
  75
  76         /**
  77          * Sets the application ID to use for resolution, bypassing the mapping
  78          * function of the Shibboleth SP.
  79          *
  80          * @param appID identifies an application in the SP configuration
  81          */
  82         void setApplicationID(const char* appID);
  83
  84         /**
  85          * Sets the identity issuer to use for resolution.
  86          *
  87          * @param issuer    entityID of the identity "source", if known
  88          */
  89         void setIssuer(const char* issuer);
  90
  91         /**
  92          * Adds a SAML token as input to the resolver.
  93          * <p>The caller retains ownership of the object.
  94          *
  95          * @param token an input token to evaluate
  96          */
  97         void addToken(
  98 #ifdef SHIBSP_LITE
  99             const xmltooling::XMLObject* token
 100 #else
 101             const opensaml::saml2::Assertion* token
 102 #endif
 103             );
 104
 105         /**
 106          * Adds an Attribute as input to the resolver.
 107          * <p>The caller retains ownership of the object, but it MAY be modified
 108          * during the resolution process.
 109          *
 110          * @param attr  an input Attribute
 111          */
 112         void addAttribute(shibsp::Attribute* attr);
 113
 114         /**
 115          * Resolves Attributes and attaches them to the resolver object.
 116          * <p>The caller is responsible for transferring any Attributes it wishes to
 117          * retain out of the resolver.
 118          */
 119         virtual void resolve();
 120
 121         /**
 122          * Returns a modifiable array of resolved Attribute objects.
 123          * <p>The caller may take ownership of any or all by removing them
 124          * from the array.
 125          *
 126          * @return  array of resolved Attributes
 127          */
 128         std::vector<shibsp::Attribute*>& getResolvedAttributes();
 129
 130         /**
 131          * Returns mapped PropertySet and AccessControl objects, if any.
 132          *
 133          * @return  mapped PropertySet/AccesssControl pair
 134          */
 135         shibsp::RequestMapper::Settings getSettings() const;
 136
 137         /**
 138          * Initializes SP runtime objects based on an XML configuration string or a configuration pathname.
 139          * <p>Each process using the library MUST call this function exactly once before using any library classes.
 140          *
 141          * @param features  bitmask of SP components to enable
 142          * @param config    a snippet of XML to parse (it <strong>MUST</strong> contain a type attribute) or a pathname
 143          * @param rethrow   true iff caught exceptions should be rethrown instead of just returning a true/false result
 144          * @return true iff initialization was successful
 145          */
 146         static bool init(
 147 #ifdef SHIBSP_LITE
 148             unsigned long features = (shibsp::SPConfig::Listener|shibsp::SPConfig::InProcess),
 149 #else
 150             unsigned long features = shibsp::SPConfig::OutOfProcess,
 151 #endif
 152             const char* config = nullptr,
 153             bool rethrow = false
 154             );
 155
 156         /**
 157          * Shuts down runtime.
 158          *
 159          * Each process using the library SHOULD call this function exactly once before terminating itself.
 160          */
 161         static void term();
 162
 163         /**
 164          * Returns a ShibbolethResolver instance.
 165          *
 166          * @return  a ShibbolethResolver instance, must be freed by the caller.
 167          */
 168         static ShibbolethResolver* create();
 169
 170     protected:
 171         /** Service URI */
 172         std::string m_serviceURI;
 173
 174         /** Application ID. */
 175         std::string m_appID;
 176
 177         /** Source of identity, if known. */
 178         std::string m_issuer;
 179
 180         /** Input tokens. */
 181 #ifdef SHIBSP_LITE
 182         std::vector<const xmltooling::XMLObject*> m_tokens;
 183 #else
 184         std::vector<const opensaml::saml2::Assertion*> m_tokens;
 185 #endif
 186         /** Input attributes. */
 187         std::vector<shibsp::Attribute*> m_inputAttributes;
 188
 189     private:
 190         shibsp::ServiceProvider* m_sp;
 191         shibsp::RequestMapper* m_mapper;
 192         shibsp::RequestMapper::Settings m_settings;
 193         std::vector<shibsp::Attribute*> m_resolvedAttributes;
 194     };
 195
 196 #if defined (_MSC_VER)
 197     #pragma warning( pop )
 198 #endif
 199
 200 };
 201
 202 #endif /* __shibresolver_h__ */