1 /**
2 * Copyright [2006] [University Corporation for Advanced Internet Development, Inc.]
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 package edu.internet2.middleware.shibboleth.wayf.plugins;
17
18 import java.util.Collection;
19 import java.util.List;
20 import java.util.Map;
21
22 import javax.servlet.http.HttpServletRequest;
23 import javax.servlet.http.HttpServletResponse;
24
25 import org.opensaml.saml2.metadata.provider.MetadataProvider;
26
27 import edu.internet2.middleware.shibboleth.wayf.IdPSite;
28
29 /**
30 *
31 * The Plugin interface is used to affect the 'hints' that the WAYF offers to the users.
32 * <p>
33 * The WAYF can register any number of plugins. Each plugin is called when the metadata is loaded or realoaded
34 * (so it can do any indexing) and at the three entry points into the WAYF - Lookup (main entry), Search and Select.
35 * Plugins are called in the order in which they are declared to the WAYF.
36 * <p>
37 * Each plugin is called once when the user has made a selection.
38 * <p>
39 * For Search and Lookup, each plugin is called multiple times, once for each metadata provider which has
40 * been declared to this particular WAYF instance. The plugin can return a context which is handed to subsequent calls.
41 * <p>
42 * The idea is that each plugin can affect the displayed lists of IdPs. As a reminder the WAYF displays two lists of
43 * IdPs - the complete list, displayed either as a single list or a list of lists, and the hint list (which was
44 * previously only populated from the _saml_idp cookie. In the search case the WAYF displays a third list of
45 * the search hits.
46 * <p>
47 * When the plugin in called it is given the current set of potential IdPs as a Map from EntityID to {@link IdPSite}
48 * and lists representing the current hint list and search results. A Plugin can remove an entry from
49 * the map or the lists. Additionally it can insert an IdPSite found in the Map into the hint or search lists.
50 * Thus the plugin can restrict the number of sites that the WAYF instance displays in the 'complete list' and
51 * can add or remove IdPs from the hint list.
52 * <p>
53 * At any stage the plugin can take control of the current request and redirect or forward it. It signals that
54 * it has done this to the WAYF by means of an exception.
55 * <p>
56 * The _saml_idp cookie handling code is written as a WAYF plugin. Other plugins have been written to allow IdPs
57 * to be presented as hints based on the client's IP address or to redirect back to the SP once the choice of
58 * IdP has been made.
59 * <p>
60 * Object implementing this interface are created during WAYF discovery service initialization. There are
61 * expected to implement a constructor which takes a {@link org.w3c.dom.Element} as the only parameter and they are
62 * created via this constructor, with the parameter being the appropriate section of the WAYF configuration file
63 *
64 * @version Discussion
65 *
66 */
67 public interface Plugin {
68
69 /**
70 * Whenever the WAYF discoveres that the metadata is stale, it reloads it and calls each plugin at this method.
71 *
72 * @param metadata - where to get the data from.
73 * @return the value which will be provided as input to subsequent calls to {@link #lookup Lookup} and
74 * {@link #search Search}
75 */
76 PluginMetadataParameter refreshMetadata(MetadataProvider metadata);
77
78 /**
79 * The WAYF calls each plugin at this entry point when it is first contacted.
80 *
81 * @param req - Describes the current request. A Plugin might use it to find any appropriate cookies
82 * @param res - Describes the current response. A Plugin might use it to redirect a the request.
83 * @param parameter Describes the metadata.
84 * @param context Any processing context returned from a previous call.
85 * @param validIdps The list of IdPs which is currently views as possibly matches for the pattern.
86 * The Key is the EntityId for the IdP and the value the object which describes
87 * the Idp
88 * @param idpList The set of Idps which are currently considered as potential hints.
89 * @return a context to hand to subsequent calls
90 * @throws WayfRequestHandled if the plugin has handled the request (for instance it has
91 * issues a redirect)
92 *
93 * Each plugin is called multiple times,
94 * once for each metadata provider which is registered (Depending on the precise configuration of the WAYF
95 * metadata providers whose metadata does not include the target may be dropped). Initially the plugin is
96 * called with a context parameter of <code>null</code>. In subsequent calls, the value returned from
97 * the previous call is passed in as the context parameter.
98 *
99 * The plugin may remove IdPSite objects from the validIdps list.
100 *
101 * The plugin may add or remove them to the idpList. IdPSite Objects which are to be added to the idpList
102 * should be looked up by EntityIdName in validIdps by EntityId. Hence any metadata processing shoudl
103 * store the entityID.
104 *
105 */
106 PluginContext lookup(HttpServletRequest req,
107 HttpServletResponse res,
108 PluginMetadataParameter parameter,
109 Map<String, IdPSite> validIdps,
110 PluginContext context,
111 List<IdPSite> idpList) throws WayfRequestHandled;
112
113 /**
114 * This method is called when the user specified a search operation. The processing is similar to
115 * that described for {@link #lookup lookup}.
116 * Two additional paramaters are provided, the search parameter which was provided, and the current
117 * proposed list of candidate IdPs. The plugin is at liberty to alter both the list of hints and the
118 * list of valid IdPs.
119 *
120 * @param req Describes the current request. The Plugin could use it to find any appropriate cookies
121 * @param res Describes the result - this is needed if (for instance) a plung needs to change cookie values
122 * @param parameter Describes the metadata
123 * @param pattern The Search pattern provided
124 * @param validIdps The list of IdPs which is currently views as possibly matches for the pattern.
125 * The Key is the Idp Name an the value the idp
126 * @param context Any processing context returned from a previous call.
127 * @param searchResult the resukt of any search
128 * @param idpList The set of Idps which are currently considered as potential hints. Each Idp is associated
129 * with a numeric weight, where the lower the number is the more likely the IdP is to be a candidate.
130 * As descibed above the WAYF uses this to provide hint list to the GUI (or even to dispatch
131 * immediately to the IdP).
132 * @return a context to hand to subsequent calls
133 * @throws WayfRequestHandled if the plugin has handled the request (for instance it has
134 * issues a redirect)
135 */
136 PluginContext search(HttpServletRequest req,
137 HttpServletResponse res,
138 PluginMetadataParameter parameter,
139 String pattern,
140 Map<String, IdPSite> validIdps,
141 PluginContext context,
142 Collection<IdPSite> searchResult,
143 List<IdPSite> idpList) throws WayfRequestHandled;
144
145 /**
146 * This method is called, for every plugin, after a user has selected an IdP. The plugin is expected
147 * to use it to update any in memory state (via the {@link PluginMetadataParameter} parameter or permananent
148 * state (for instance by writing back a cookie.
149 * @param req Describes the current request.
150 * @param res Describes the current response
151 * @param parameter Describes the metadata
152 * @throws WayfRequestHandled if the plugin has handled the request (for instance it has
153 * issues a redirect)
154 */
155 void selected(HttpServletRequest req,
156 HttpServletResponse res,
157 PluginMetadataParameter parameter,
158 String idP) throws WayfRequestHandled;
159 }