Unifed NameMapper and HSNameMapper interfaces for use by the new IdPResponder servlet.
[java-idp.git] / src / edu / internet2 / middleware / shibboleth / common / NameIdentifierMapping.java
1 /*
2  * The Shibboleth License, Version 1. Copyright (c) 2002 University Corporation for Advanced Internet Development, Inc.
3  * All rights reserved Redistribution and use in source and binary forms, with or without modification, are permitted
4  * provided that the following conditions are met: Redistributions of source code must retain the above copyright
5  * notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above
6  * copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials
7  * provided with the distribution, if any, must include the following acknowledgment: "This product includes software
8  * developed by the University Corporation for Advanced Internet Development <http://www.ucaid.edu> Internet2 Project.
9  * Alternately, this acknowledegement may appear in the software itself, if and wherever such third-party
10  * acknowledgments normally appear. Neither the name of Shibboleth nor the names of its contributors, nor Internet2, nor
11  * the University Corporation for Advanced Internet Development, Inc., nor UCAID may be used to endorse or promote
12  * products derived from this software without specific prior written permission. For written permission, please contact
13  * shibboleth@shibboleth.org Products derived from this software may not be called Shibboleth, Internet2, UCAID, or the
14  * University Corporation for Advanced Internet Development, nor may Shibboleth appear in their name, without prior
15  * written permission of the University Corporation for Advanced Internet Development. THIS SOFTWARE IS PROVIDED BY THE
16  * COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND WITH ALL FAULTS. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE
18  * DISCLAIMED AND THE ENTIRE RISK OF SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS WITH LICENSEE. IN NO
19  * EVENT SHALL THE COPYRIGHT OWNER, CONTRIBUTORS OR THE UNIVERSITY CORPORATION FOR ADVANCED INTERNET DEVELOPMENT, INC.
20  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
21  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
23  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24  */
25
26 package edu.internet2.middleware.shibboleth.common;
27
28 import java.net.URI;
29
30 import org.opensaml.SAMLNameIdentifier;
31
32 /**
33  * Defines a mechanism for converting back and forth between SAML Name Identifiers and local {@link AuthNPrincipal}
34  * objects.
35  * 
36  * @author Walter Hoehn
37  */
38 public interface NameIdentifierMapping {
39
40         public static final String mappingNamespace = "urn:mace:shibboleth:namemapper:1.0";
41
42         /**
43          * @return the id of this mapping or <code>null</code> is it is not configured with one
44          */
45         public String getId();
46
47         /**
48          * Returns the Name Identifier format for this mapping.
49          * 
50          * @return the format
51          */
52         public URI getNameIdentifierFormat();
53
54         /**
55          * Maps a SAML Name Identifier to a local principal using the appropriate registered mapping. Must ensure that the
56          * SAML NameIdentifer is properly qualified.
57          * 
58          * @param nameId
59          *            the SAML Name Identifier that should be converted
60          * @param sProv
61          *            the provider initiating the request
62          * @param idProv
63          *            the provider handling the request
64          * @return the local principal
65          * @throws NameIdentifierMappingException
66          *             If the {@link NameMapper}encounters an internal error
67          * @throws InvalidNameIdentifierException
68          *             If the {@link SAMLNameIdentifier}contains invalid data
69          */
70         public AuthNPrincipal getPrincipal(SAMLNameIdentifier nameId, ServiceProvider sProv, IdentityProvider idProv)
71                         throws NameIdentifierMappingException, InvalidNameIdentifierException;
72
73         /**
74          * Maps a local principal to a SAML Name Identifier.
75          * 
76          * @param id
77          *            the id under which the effective {@link HSNameIdentifierMapping}is registered
78          * @param principal
79          *            the principal to map
80          * @param sProv
81          *            the provider initiating the request
82          * @param idProv
83          *            the provider handling the request
84          * @return the SAML name identifier
85          * @throws NameIdentifierMappingException
86          *             If the {@link NameMapper}encounters an internal error
87          */
88         public SAMLNameIdentifier getNameIdentifierName(AuthNPrincipal principal, ServiceProvider sProv,
89                         IdentityProvider idProv) throws NameIdentifierMappingException;
90
91         /**
92          * Cleanup resources that won't be released when this object is garbage-collected
93          */
94         public void destroy();
95
96 }