Added javadoc for NameMapper classes.
[java-idp.git] / src / edu / internet2 / middleware / shibboleth / common / NameMapper.java
1 /*
2  * The Shibboleth License, Version 1. Copyright (c) 2002 University Corporation
3  * for Advanced Internet Development, Inc. All rights reserved
4  * 
5  * 
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are met:
8  * 
9  * Redistributions of source code must retain the above copyright notice, this
10  * list of conditions and the following disclaimer.
11  * 
12  * Redistributions in binary form must reproduce the above copyright notice,
13  * this list of conditions and the following disclaimer in the documentation
14  * and/or other materials provided with the distribution, if any, must include
15  * the following acknowledgment: "This product includes software developed by
16  * the University Corporation for Advanced Internet Development
17  * <http://www.ucaid.edu> Internet2 Project. Alternately, this acknowledegement
18  * may appear in the software itself, if and wherever such third-party
19  * acknowledgments normally appear.
20  * 
21  * Neither the name of Shibboleth nor the names of its contributors, nor
22  * Internet2, nor the University Corporation for Advanced Internet Development,
23  * Inc., nor UCAID may be used to endorse or promote products derived from this
24  * software without specific prior written permission. For written permission,
25  * please contact shibboleth@shibboleth.org
26  * 
27  * Products derived from this software may not be called Shibboleth, Internet2,
28  * UCAID, or the University Corporation for Advanced Internet Development, nor
29  * may Shibboleth appear in their name, without prior written permission of the
30  * University Corporation for Advanced Internet Development.
31  * 
32  * 
33  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
34  * AND WITH ALL FAULTS. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
35  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
36  * PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE DISCLAIMED AND THE ENTIRE RISK
37  * OF SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS WITH LICENSEE.
38  * IN NO EVENT SHALL THE COPYRIGHT OWNER, CONTRIBUTORS OR THE UNIVERSITY
39  * CORPORATION FOR ADVANCED INTERNET DEVELOPMENT, INC. BE LIABLE FOR ANY
40  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
41  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
42  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
44  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
45  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
46  */
47
48 package edu.internet2.middleware.shibboleth.common;
49
50 import java.io.StringReader;
51 import java.lang.reflect.Constructor;
52 import java.net.URI;
53 import java.net.URISyntaxException;
54 import java.util.Collections;
55 import java.util.HashMap;
56 import java.util.Map;
57
58 import org.apache.log4j.Logger;
59 import org.apache.xerces.parsers.DOMParser;
60 import org.opensaml.SAMLNameIdentifier;
61 import org.w3c.dom.Element;
62 import org.xml.sax.InputSource;
63
64 import edu.internet2.middleware.shibboleth.hs.provider.SharedMemoryShibHandle;
65
66 /**
67  * Facility for managing mappings from SAML Name Identifiers to local <code>AuthNPrincipal</code>
68  * objects. Mappings are registered by Name Identifier format.
69  * 
70  * @author Walter Hoehn
71  * @see NameIdentifierMapping
72  */
73 public class NameMapper {
74
75         private static Logger log = Logger.getLogger(NameMapper.class.getName());
76         protected Map byFormat = new HashMap();
77         private static Map registeredMappingTypes = Collections.synchronizedMap(new HashMap());
78         /** Indicated of whether mappings have been added */
79         protected boolean initialized = false;
80         /** Mapping to use if no other mappings have been added */
81         protected SharedMemoryShibHandle defaultMapping;
82
83         //Preload aliases for bundled mappings
84         static {
85                 try {
86                         registeredMappingTypes.put(
87                                 "CryptoHandleGenerator",
88                                 Class.forName("edu.internet2.middleware.shibboleth.hs.provider.CryptoShibHandle"));
89
90                         registeredMappingTypes.put(
91                                 "SharedMemoryShibHandle",
92                                 Class.forName("edu.internet2.middleware.shibboleth.hs.provider.SharedMemoryShibHandle"));
93
94                         registeredMappingTypes.put(
95                                 "Principal",
96                                 Class.forName("edu.internet2.middleware.shibboleth.common.PrincipalNameIdentifier"));
97
98                 } catch (ClassNotFoundException e) {
99                         log.error("Unable to pre-register Name mapping implementation types.");
100                 }
101         }
102
103         public NameMapper() {
104                 try {
105                         //Load the default mapping
106                         String rawConfig =
107                                 "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
108                                         + "<NameMapping format=\"urn:mace:shibboleth:1.0:nameIdentifier\""
109                                         + "             handleTTL=\"1800\"/>";
110                         DOMParser parser = new DOMParser();
111                         parser.parse(new InputSource(new StringReader(rawConfig)));
112                         defaultMapping = new SharedMemoryShibHandle(parser.getDocument().getDocumentElement());
113
114                 } catch (Exception e) {
115                         log.error("Unable to register default Name Identifier Mapping.");
116                         initialize();
117                 }
118         }
119
120         protected void initialize() {
121                 initialized = true;
122                 defaultMapping = null;
123         }
124
125         /**
126          * 
127          * Constructs a <code>NameIdentifierMapping</code> based on XML
128          * configuration data and adds it to this <code>NameMapper</code>,
129          * registering it according to its format.
130          * 
131          * @param e
132          *            An XML representation of a <code>NameIdentifierMapping</code>
133          * 
134          * @throws NameIdentifierMappingException
135          *             If the mapping could not be constructed according to the
136          *             supplied configuration
137          */
138         public void addNameMapping(Element e) throws NameIdentifierMappingException {
139
140                 if (!e.getTagName().equals("NameMapping")) {
141                         throw new IllegalArgumentException();
142                 }
143
144                 String type = ((Element) e).getAttribute("type");
145                 String implementation = ((Element) e).getAttribute("class");
146                 if (type != null && (!type.equals("")) && implementation != null && (!implementation.equals(""))) {
147                         log.error("Name Mapping has both a \"type\" and a \"class\" attribute. Only \"type\" will take effect.");
148                 }
149
150                 if (type != null && (!type.equals(""))) {
151
152                         Class registeredImplementation = (Class) registeredMappingTypes.get(type);
153                         if (registeredImplementation == null) {
154                                 log.error("Name Mapping refers to an unregistered implementation type.");
155                                 throw new NameIdentifierMappingException("Invalid mapping implementation specified.");
156                         }
157
158                         log.debug(
159                                 "Found type ("
160                                         + type
161                                         + ") registered with an implementation class of ("
162                                         + registeredImplementation.getName()
163                                         + ").");
164                         addNameMapping(loadNameIdentifierMapping(registeredImplementation, e));
165
166                 } else if (implementation != null && (!implementation.equals(""))) {
167
168                         try {
169                                 Class implementorClass = Class.forName(implementation);
170                                 addNameMapping(loadNameIdentifierMapping(implementorClass, e));
171
172                         } catch (ClassNotFoundException cnfe) {
173                                 log.error("Name Mapping refers to an implementation class that cannot be loaded: " + cnfe);
174                                 throw new NameIdentifierMappingException("Invalid mapping implementation specified.");
175                         }
176
177                 } else {
178                         log.error("Name Mapping requires either a \"type\" or a \"class\" attribute.");
179                         throw new NameIdentifierMappingException("No mapping implementation specified.");
180                 }
181
182         }
183
184         /**
185          * Adds a <code>NameIdentifierMapping</code> to this <code>NameMapper</code>,
186          * registering it according to its format.
187          * 
188          * @param mapping
189          *            the mapping to add
190          */
191         public void addNameMapping(NameIdentifierMapping mapping) {
192
193                 initialize();
194
195                 if (byFormat.containsKey(mapping.getNameIdentifierFormat())) {
196                         log.error("Attempted to register multiple Name Mappings with the same format.  Skipping duplicates...");
197                         return;
198                 }
199                 byFormat.put(mapping.getNameIdentifierFormat(), mapping);
200
201         }
202
203         /**
204          * Returns the <code>NameIdentifierMapping</code> registered for a given
205          * format
206          * 
207          * @param format
208          *            the registered format
209          * @return the mapping or <tt>null</tt> if no mapping is registered for
210          *         the given format
211          */
212         public NameIdentifierMapping getNameIdentifierMapping(URI format) {
213                 if (!initialized) {
214                         return defaultMapping;
215                 }
216                 return (NameIdentifierMapping) byFormat.get(format);
217         }
218
219         protected NameIdentifierMapping loadNameIdentifierMapping(Class implementation, Element config)
220                 throws NameIdentifierMappingException {
221
222                 try {
223                         Class[] params = new Class[] { Element.class };
224                         Constructor implementorConstructor = implementation.getConstructor(params);
225                         Object[] args = new Object[] { config };
226                         log.debug("Initializing Name Identifier Mapping of type (" + implementation.getName() + ").");
227                         return (NameIdentifierMapping) implementorConstructor.newInstance(args);
228
229                 } catch (NoSuchMethodException nsme) {
230                         log.error(
231                                 "Failed to instantiate a Name Identifier Mapping: NameIdentifierMapping "
232                                         + "implementation must contain a constructor that accepts an Element object for "
233                                         + "configuration data.");
234                         throw new NameIdentifierMappingException("Failed to instantiate a Name Identifier Mapping.");
235
236                 } catch (Exception e) {
237                         log.error("Failed to instantiate a Name Identifier Mapping: " + e + ":" + e.getCause());
238                         throw new NameIdentifierMappingException("Failed to instantiate a Name Identifier Mapping: " + e);
239
240                 }
241
242         }
243
244         /**
245          * Maps a SAML Name Identifier to a local principal using the appropriate
246          * registered mapping.
247          * 
248          * @param nameId
249          *            the SAML Name Identifier that should be converted
250          * @param sProv
251          *            the provider initiating the request
252          * @param idProv
253          *            the provider handling the request
254          * @return the local principal
255          * @throws NameIdentifierMappingException
256          *             If the <code>NameMapper</code> encounters an internal
257          *             error
258          * @throws InvalidNameIdentifierException
259          *             If the <code>SAMLNameIdentifier</code> contains invalid
260          *             data
261          */
262         public AuthNPrincipal getPrincipal(SAMLNameIdentifier nameId, ServiceProvider sProv, IdentityProvider idProv)
263                 throws NameIdentifierMappingException, InvalidNameIdentifierException {
264
265                 NameIdentifierMapping mapping = null;
266                 try {
267                         mapping = getNameIdentifierMapping(new URI(nameId.getFormat()));
268                 } catch (URISyntaxException e) {
269                         log.error("Invalid Name Identifier format.");
270                 }
271                 if (mapping == null) {
272                         throw new InvalidNameIdentifierException("Name Identifier format not registered.");
273                 }
274                 return mapping.getPrincipal(nameId, sProv, idProv);
275         }
276
277 }