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.
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @file shibsp/handler/SessionInitiator.h
24 * Pluggable runtime functionality that handles initiating sessions.
27 #ifndef __shibsp_sesinitiator_h__
28 #define __shibsp_sesinitiator_h__
30 #include <shibsp/handler/Handler.h>
38 class SHIBSP_API AuthnRequestEvent;
41 * Pluggable runtime functionality that handles initiating sessions.
43 * <p>By default, SessionInitiators look for an entityID on the incoming request
44 * and pass control to the specialized run method.
46 class SHIBSP_API SessionInitiator : public virtual Handler
48 friend void SHIBSP_API registerSessionInitiators();
50 /** Property remapper for configuration compatibility. */
51 static std::map<std::string,std::string> m_remapper;
53 /** Set of optional settings supported by handler. */
54 std::set<std::string> m_supportedOptions;
59 * Examines the request and applicable settings to determine whether
60 * the handler is able to support the request.
61 * <p>If the handler is within a chain, the method will return false,
62 * otherwise an exception will be raised.
64 * @param request SP request context
65 * @param isHandler true iff executing in the context of a direct handler invocation
66 * @return true iff the request appears to be compatible
68 bool checkCompatibility(SPRequest& request, bool isHandler) const;
72 * Creates a new AuthnRequestEvent for the event log.
74 * @param application the Application associated with the event
75 * @param request the HTTP client request associated with the event, or nullptr
76 * @return a fresh AuthnRequestEvent, prepopulated by the input parameters, or nullptr if an error occurs
78 virtual AuthnRequestEvent* newAuthnRequestEvent(
79 const Application& application, const xmltooling::HTTPRequest* request=nullptr
84 virtual ~SessionInitiator();
87 * Indicates the set of optional settings supported by the handler.
89 * @return a set of the optional settings supported
91 virtual const std::set<std::string>& getSupportedOptions() const;
94 * Executes an incoming request.
96 * <p>SessionInitiators can be run either directly by incoming web requests
97 * or indirectly/implicitly during other SP processing.
99 * @param request SP request context
100 * @param entityID the name of an IdP to request a session from, if known
101 * @param isHandler true iff executing in the context of a direct handler invocation
102 * @return a pair containing a "request completed" indicator and a server-specific response code
104 virtual std::pair<bool,long> run(SPRequest& request, std::string& entityID, bool isHandler=true) const=0;
106 std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const;
109 const char* getType() const;
110 void generateMetadata(opensaml::saml2md::SPSSODescriptor& role, const char* handlerURL) const;
114 /** Registers SessionInitiator implementations. */
115 void SHIBSP_API registerSessionInitiators();
117 /** SessionInitiator that iterates through a set of protocol-specific versions. */
118 #define CHAINING_SESSION_INITIATOR "Chaining"
120 /** SessionInitiator that supports SAML 2.0 AuthnRequests. */
121 #define SAML2_SESSION_INITIATOR "SAML2"
123 /** SessionInitiator that supports SAML Discovery Service protocol. */
124 #define SAMLDS_SESSION_INITIATOR "SAMLDS"
126 /** SessionInitiator that supports Shibboleth V1 AuthnRequest redirects. */
127 #define SHIB1_SESSION_INITIATOR "Shib1"
129 /** SessionInitiator that supports Shibboleth V1 WAYF redirects when no IdP is supplied. */
130 #define WAYF_SESSION_INITIATOR "WAYF"
132 /** SessionInitiator that attempts a sequence of transforms of an input until an entityID is found. */
133 #define TRANSFORM_SESSION_INITIATOR "Transform"
135 /** SessionInitiator that uses HTML form submission from the user. */
136 #define FORM_SESSION_INITIATOR "Form"
138 /** SessionInitiator that reads the CDC. */
139 #define COOKIE_SESSION_INITIATOR "Cookie"
142 #endif /* __shibsp_sesinitiator_h__ */