001    /*
002     * CDDL HEADER START
003     *
004     * The contents of this file are subject to the terms of the
005     * Common Development and Distribution License, Version 1.0 only
006     * (the "License").  You may not use this file except in compliance
007     * with the License.
008     *
009     * You can obtain a copy of the license at
010     * docs/licenses/cddl.txt
011     * or http://www.opensource.org/licenses/cddl1.php.
012     * See the License for the specific language governing permissions
013     * and limitations under the License.
014     *
015     * When distributing Covered Code, include this CDDL HEADER in each
016     * file and include the License file at
017     * docs/licenses/cddl.txt.  If applicable,
018     * add the following below this CDDL HEADER, with the fields enclosed
019     * by brackets "[]" replaced with your own identifying information:
020     *      Portions Copyright [yyyy] [name of copyright owner]
021     *
022     * CDDL HEADER END
023     *
024     *
025     *      Copyright 2010-2012 UnboundID Corp.
026     */
027    package com.unboundid.directory.sdk.ds.api;
028    
029    
030    
031    import java.util.Collections;
032    import java.util.List;
033    import java.util.Map;
034    
035    import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
036    import com.unboundid.directory.sdk.common.internal.Reconfigurable;
037    import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
038    import com.unboundid.directory.sdk.ds.config.IdentityMapperConfig;
039    import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
040    import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
041    import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
042    import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
043    import com.unboundid.ldap.sdk.LDAPException;
044    import com.unboundid.ldap.sdk.ResultCode;
045    import com.unboundid.util.Extensible;
046    import com.unboundid.util.ThreadSafety;
047    import com.unboundid.util.ThreadSafetyLevel;
048    import com.unboundid.util.args.ArgumentException;
049    import com.unboundid.util.args.ArgumentParser;
050    
051    
052    
053    /**
054     * This class defines an API that must be implemented by extensions which
055     * attempt to map a username to a user defined in the server.  This is generally
056     * used when processing an authorization ID, as might be provided when
057     * performing SASL authentication or in a control like the proxied authorization
058     * or intermediate client controls.  In order for the mapping to be established,
059     * the identity mapper must locate exactly one entry in the server corresponding
060     * to the provided username.  If no entries are found, or if multiple entries
061     * are found, then the mapping attempt must fail.
062     * <BR>
063     * <H2>Configuring Identity Mappers</H2>
064     * In order to configure an identity mapper created using this API, use a
065     * command like:
066     * <PRE>
067     *      dsconfig create-identity-mapper \
068     *           --mapper-name "<I>{mapper-name}</I>" \
069     *           --type third-party \
070     *           --set enabled:true \
071     *           --set "extension-class:<I>{class-name}</I>" \
072     *           --set "extension-argument:<I>{name=value}</I>"
073     * </PRE>
074     * where "<I>{mapper-name}</I>" is the name to use for the identity mapper
075     * instance, "<I>{class-name}</I>" is the fully-qualified name of the Java class
076     * that extends {@code com.unboundid.directory.sdk.ds.api.IdentityMapper},
077     * and "<I>{name=value}</I>" represents name-value pairs for any arguments to
078     * provide to the identity mapper.  If multiple arguments should be provided to
079     * the identity mapper, then the
080     * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
081     * provided multiple times.
082     *
083     * @see  com.unboundid.directory.sdk.ds.scripting.ScriptedIdentityMapper
084     */
085    @Extensible()
086    @DirectoryServerExtension()
087    @DirectoryProxyServerExtension(appliesToLocalContent=true,
088         appliesToRemoteContent=true,
089         notes="Identity mappers may only apply in certain contexts for proxied " +
090              "operations (e.g., when used in the context of SASL authentication " +
091              "but not in the value of the proxied authorization control).")
092    @SynchronizationServerExtension(appliesToLocalContent=true,
093         appliesToSynchronizedContent=false)
094    @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
095    public abstract class IdentityMapper
096           implements UnboundIDExtension, Reconfigurable<IdentityMapperConfig>,
097                      ExampleUsageProvider
098    {
099      /**
100       * Creates a new instance of this identity mapper.  All identity mapper
101       * implementations must include a default constructor, but any initialization
102       * should generally be done in the {@code initializeIdentityMapper} method.
103       */
104      public IdentityMapper()
105      {
106        // No implementation is required.
107      }
108    
109    
110    
111      /**
112       * {@inheritDoc}
113       */
114      public abstract String getExtensionName();
115    
116    
117    
118      /**
119       * {@inheritDoc}
120       */
121      public abstract String[] getExtensionDescription();
122    
123    
124    
125      /**
126       * {@inheritDoc}
127       */
128      public void defineConfigArguments(final ArgumentParser parser)
129             throws ArgumentException
130      {
131        // No arguments will be allowed by default.
132      }
133    
134    
135    
136      /**
137       * Initializes this identity mapper.
138       *
139       * @param  serverContext  A handle to the server context for the server in
140       *                        which this extension is running.
141       * @param  config         The general configuration for this identity mapper.
142       * @param  parser         The argument parser which has been initialized from
143       *                        the configuration for this identity mapper.
144       *
145       * @throws  LDAPException  If a problem occurs while initializing this
146       *                         identity mapper.
147       */
148      public void initializeIdentityMapper(
149                       final DirectoryServerContext serverContext,
150                       final IdentityMapperConfig config,
151                       final ArgumentParser parser)
152             throws LDAPException
153      {
154        // No initialization will be performed by default.
155      }
156    
157    
158    
159      /**
160       * {@inheritDoc}
161       */
162      public boolean isConfigurationAcceptable(final IdentityMapperConfig config,
163                          final ArgumentParser parser,
164                          final List<String> unacceptableReasons)
165      {
166        // No extended validation will be performed by default.
167        return true;
168      }
169    
170    
171    
172      /**
173       * {@inheritDoc}
174       */
175      public ResultCode applyConfiguration(final IdentityMapperConfig config,
176                                           final ArgumentParser parser,
177                                           final List<String> adminActionsRequired,
178                                           final List<String> messages)
179      {
180        // By default, no configuration changes will be applied.  If there are any
181        // arguments, then add an admin action message indicating that the extension
182        // needs to be restarted for any changes to take effect.
183        if (! parser.getNamedArguments().isEmpty())
184        {
185          adminActionsRequired.add(
186               "No configuration change has actually been applied.  The new " +
187                    "configuration will not take effect until this identity " +
188                    "mapper is disabled and re-enabled or until the server is " +
189                    "restarted.");
190        }
191    
192        return ResultCode.SUCCESS;
193      }
194    
195    
196    
197      /**
198       * Performs any cleanup which may be necessary when this identity mapper is to
199       * be taken out of service.
200       */
201      public void finalizeIdentityMapper()
202      {
203        // No implementation is required.
204      }
205    
206    
207    
208      /**
209       * Performs any processing which may be necessary to map the provided username
210       * to a user within the server.
211       *
212       * @param  username  The username to be mapped to a user within the server.
213       *
214       * @return  The DN of the user within the server to which the provided
215       *          username corresponds.
216       *
217       * @throws  LDAPException  If the provided username cannot be mapped to
218       *                         exactly one user in the server.
219       */
220      public abstract String mapUsername(final String username)
221             throws LDAPException;
222    
223    
224    
225      /**
226       * {@inheritDoc}
227       */
228      public Map<List<String>,String> getExamplesArgumentSets()
229      {
230        return Collections.emptyMap();
231      }
232    }