com.unboundid.directory.sdk.ds.scripting.ScriptedIdentityMapper Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of server-sdk Show documentation
The UnboundID Server SDK is a library that may be used to develop various types of extensions to Ping Identity server products, including the Directory Server, Directory Proxy Server, Data Sync Server, Data Metrics Server, and Data Governance Broker.
There is a newer version: 6.2.0.0
Show newest version
/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * docs/licenses/cddl.txt
 * or http://www.opensource.org/licenses/cddl1.php.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * docs/licenses/cddl.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Portions Copyright 2010-2024 Ping Identity Corporation
 */
package com.unboundid.directory.sdk.ds.scripting;



import java.util.List;

import com.unboundid.directory.sdk.common.internal.Reconfigurable;
import com.unboundid.directory.sdk.ds.config.IdentityMapperConfig;
import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.util.Extensible;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;



/**
 * This class defines an API that must be implemented by scripted extensions
 * which attempt to map a username to a user defined in the server.  This is
 * generally used when processing an authorization ID, as might be provided when
 * performing SASL authentication or in a control like the proxied authorization
 * or intermediate client controls.  In order for the mapping to be established,
 * the identity mapper must locate exactly one entry in the server corresponding
 * to the provided username.  If no entries are found, or if multiple entries
 * are found, then the mapping attempt must fail.
 * 

 * Configuring Groovy-Scripted Identity Mappers
 * In order to configure a scripted identity mapper based on this API and
 * written in the Groovy scripting language, use a command like:
 *  *      dsconfig create-identity-mapper \
 *           --mapper-name "{mapper-name}" \
 *           --type groovy-scripted \
 *           --set enabled:true \
 *           --set "script-class:{class-name}" \
 *           --set "script-argument:{name=value}"
 * 
 * where "{mapper-name}" is the name to use for the identity mapper
 * instance, "{class-name}" is the fully-qualified name of the Groovy
 * class written using this API, and "{name=value}" represents name-value
 * pairs for any arguments to provide to the identity mapper.  If multiple
 * arguments should be provided to the identity mapper, then the
 * "--set script-argument:{name=value}" option should be
 * provided multiple times.
 *
 * @see  com.unboundid.directory.sdk.ds.api.IdentityMapper
 */
@Extensible()
@DirectoryServerExtension()
@DirectoryProxyServerExtension(appliesToLocalContent=true,
     appliesToRemoteContent=false)
@SynchronizationServerExtension(appliesToLocalContent=true,
     appliesToSynchronizedContent=false)
@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
public abstract class ScriptedIdentityMapper
       implements Reconfigurable
{
  /**
   * Creates a new instance of this identity mapper.  All identity mapper
   * implementations must include a default constructor, but any initialization
   * should generally be done in the {@code initializeIdentityMapper} method.
   */
  public ScriptedIdentityMapper()
  {
    // No implementation is required.
  }



  /**
   * {@inheritDoc}
   */
  public void defineConfigArguments(final ArgumentParser parser)
         throws ArgumentException
  {
    // No arguments will be allowed by default.
  }



  /**
   * Initializes this identity mapper.
   *
   * @param  serverContext  A handle to the server context for the server in
   *                        which this extension is running.
   * @param  config         The general configuration for this identity mapper.
   * @param  parser         The argument parser which has been initialized from
   *                        the configuration for this identity mapper.
   *
   * @throws  LDAPException  If a problem occurs while initializing this
   *                         identity mapper.
   */
  public void initializeIdentityMapper(
                   final DirectoryServerContext serverContext,
                   final IdentityMapperConfig config,
                   final ArgumentParser parser)
         throws LDAPException
  {
    // No initialization will be performed by default.
  }



  /**
   * Performs any cleanup which may be necessary when this identity mapper is
   * to be taken out of service.
   */
  public void finalizeIdentityMapper()
  {
    // No implementation is required.
  }



  /**
   * {@inheritDoc}
   */
  public boolean isConfigurationAcceptable(final IdentityMapperConfig config,
                      final ArgumentParser parser,
                      final List unacceptableReasons)
  {
    // No extended validation will be performed.
    return true;
  }



  /**
   * {@inheritDoc}
   */
  public ResultCode applyConfiguration(final IdentityMapperConfig config,
                                       final ArgumentParser parser,
                                       final List adminActionsRequired,
                                       final List messages)
  {
    // By default, no configuration changes will be applied.  If there are any
    // arguments, then add an admin action message indicating that the extension
    // needs to be restarted for any changes to take effect.
    if (! parser.getNamedArguments().isEmpty())
    {
      adminActionsRequired.add(
           "No configuration change has actually been applied.  The new " +
                "configuration will not take effect until this identity " +
                "mapper is disabled and re-enabled or until the server is " +
                "restarted.");
    }

    return ResultCode.SUCCESS;
  }



  /**
   * Performs any processing which may be necessary to map the provided username
   * to a user within the server.
   *
   * @param  username  The username to be mapped to a user within the server.
   *
   * @return  The DN of the user within the server to which the provided
   *          username corresponds.
   *
   * @throws  LDAPException  If the provided username cannot be mapped to
   *                         exactly one user in the server.
   */
  public abstract String mapUsername(final String username)
         throws LDAPException;
}