/*
* 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 2021-2024 Ping Identity Corporation
*/
package com.unboundid.directory.sdk.examples;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import com.unboundid.directory.sdk.common.operation.SimpleBindRequest;
import com.unboundid.directory.sdk.common.types.Entry;
import com.unboundid.directory.sdk.common.types.OperationContext;
import com.unboundid.directory.sdk.ds.api.PassThroughAuthenticationHandler;
import com.unboundid.directory.sdk.ds.config.
PassThroughAuthenticationHandlerConfig;
import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
import com.unboundid.directory.sdk.ds.types.PassThroughAuthenticationResult;
import com.unboundid.directory.sdk.ds.types.PassThroughAuthenticationResultCode;
import com.unboundid.ldap.sdk.Attribute;
import com.unboundid.ldap.sdk.DN;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.util.NotNull;
import com.unboundid.util.StaticUtils;
import com.unboundid.util.args.ArgumentParser;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.FileArgument;
import com.unboundid.util.json.JSONException;
import com.unboundid.util.json.JSONObject;
import com.unboundid.util.json.JSONObjectReader;
/**
* This class provides an example pass-through authentication handler
* implementation that reads the "remote" users from a file with a separate JSON
* object for each of the users. The fields that may appear in each JSON
* object include:
* <BR>
* <UL>
* <LI>dn -- A mandatory string field that holds the DN of the user. This is
* expected to match the DN of the corresponding local user.</li>
* <LI>password -- A mandatory string field that holds the password for the
* user.</LI>
* <LI>result-code -- An optional string field that holds the name of the
* {@code PassThroughAuthenticationResultCode} to return for the user if
* the provided password is correct. If this field is not present for a
* user, then a default result code of "success" will be used.</LI>
* <LI>diagnostic-message -- An optional string field that holds the text of
* a diagnostic message to include in the response to the client.</LI>
* </UL>
* <BR>
* This pass-through authentication handler supports the following configuration
* properties:
* <UL>
* <LI>
* user-file -- The path to the file containing the JSON objects that
* represent the remote users.
* </LI>
* </UL>
*/
public final class ExamplePassThroughAuthenticationHandler
extends PassThroughAuthenticationHandler
{
/**
* The name of the extension argument that specifies the path to the file
* containing the JSON objects that represent the remote users.
*/
@NotNull private static final String ARG_NAME_USER_FILE = "user-file";
/**
* The name of the JSON field that holds the DN for a user.
*/
@NotNull private static final String JSON_FIELD_NAME_USER_DN = "dn";
/**
* The name of the JSON field that holds the password for a user.
*/
@NotNull private static final String JSON_FIELD_NAME_USER_PASSWORD =
"password";
/**
* The name of the JSON field that holds the name of the result code to return
* for a user if the correct password is provided for that user.
*/
@NotNull private static final String JSON_FIELD_NAME_RESULT_CODE =
"result-code";
/**
* The name of the JSON field that holds the name of the result code to return
* for a user if the correct password is provided for that user.
*/
@NotNull private static final String JSON_FIELD_NAME_DIAGNOSTIC_MESSAGE =
"diagnostic-message";
/**
* The name of a custom log field that will be used to hold the reason that
* the pass-through authentication result has the result code it was given.
*/
@NotNull private static final String LOG_FIELD_NAME_RESULT_CODE_REASON =
"passThroughAuthenticationResultCodeReason";
// A map with information about the users read from the user file.
@NotNull private volatile Map<DN,JSONObject> userMap;
/**
* Creates a new instance of this pass-through authentication handler. All
* pass-through authentication handler implementations must include a default
* constructor, but most initialization should be done in the
* {@link #initializePassThroughAuthenticationHandler} method.
*/
public ExamplePassThroughAuthenticationHandler()
{
userMap = Collections.emptyMap();
}
/**
* Retrieves a human-readable name for this extension.
*
* @return A human-readable name for this extension.
*/
@Override()
@NotNull()
public String getExtensionName()
{
return "Example Pass-Through Authentication Handler";
}
/**
* Retrieves a human-readable description for this extension. Each element
* of the array that is returned will be considered a separate paragraph in
* generated documentation.
*
* @return A human-readable description for this extension, or {@code null}
* or an empty array if no description should be available.
*/
@Override()
@NotNull()
public String[] getExtensionDescription()
{
return new String[]
{
"An example pass-through authentication handler that can allow a local " +
"user to authenticate with a password read from a specified file."
};
}
/**
* Updates the provided argument parser to define any configuration arguments
* which may be used by this extension. The argument parser may also be
* updated to define relationships between arguments (e.g., to specify
* required, exclusive, or dependent argument sets).
*
* @param parser The argument parser to be updated with the configuration
* arguments which may be used by this extension.
*
* @throws ArgumentException If a problem is encountered while updating the
* provided argument parser.
*/
@Override()
public void defineConfigArguments(@NotNull final ArgumentParser parser)
throws ArgumentException
{
final Character shortIdentifier = null;
final String longIdentifier = ARG_NAME_USER_FILE;
final boolean required = true;
final int maxOccurrences = 1;
final String placeholder = "{path}";
final String description = "The path to a file containing JSON objects " +
"with information about the 'remote' users that will be " +
"authenticated through this pass-through authentication handler.";
final boolean fileMustExist = true;
final boolean parentMustExist = true;
final boolean mustBeFile = true;
final boolean mustBeDirectory = false;
parser.addArgument(new FileArgument(shortIdentifier, longIdentifier,
required, maxOccurrences, placeholder, description, fileMustExist,
parentMustExist, mustBeFile, mustBeDirectory));
}
/**
* Initializes this pass-through authentication handler.
*
* @param serverContext A handle to the server context for the server in
* which this extension is running. It will not be
* {@code null}.
* @param config The general configuration for this pass-through
* authentication handler. It will not be
* {@code null}.
* @param parser The argument parser which has been initialized from
* the configuration for this pass-through
* authentication handler. It will not be
* {@code null}.
*
* @throws LDAPException If a problem occurs while initializing this
* pass-through authentication handler.
*/
public void initializePassThroughAuthenticationHandler(
@NotNull final DirectoryServerContext serverContext,
@NotNull final PassThroughAuthenticationHandlerConfig config,
@NotNull final ArgumentParser parser)
throws LDAPException
{
userMap = readUserMap(serverContext, parser);
}
/**
* Indicates whether the configuration represented by the provided argument
* parser is acceptable for use by this extension. The parser will have been
* used to parse any configuration available for this extension, and any
* automatic validation will have been performed. This method may be used to
* perform any more complex validation which cannot be performed automatically
* by the argument parser.
*
* @param config The general configuration for this extension.
* @param parser The argument parser that has been used to
* parse the proposed configuration for this
* extension.
* @param unacceptableReasons A list to which messages may be added to
* provide additional information about why the
* provided configuration is not acceptable.
*
* @return {@code true} if the configuration in the provided argument parser
* appears to be acceptable, or {@code false} if not.
*/
@Override()
public boolean isConfigurationAcceptable(
@NotNull final PassThroughAuthenticationHandlerConfig config,
@NotNull final ArgumentParser parser,
@NotNull final List<String> unacceptableReasons)
{
try
{
readUserMap(config.getServerContext(), parser);
return true;
}
catch (final LDAPException e)
{
config.getServerContext().debugCaught(e);
unacceptableReasons.add(e.getMessage());
return false;
}
}
/**
* Attempts to apply the configuration from the provided argument parser to
* this extension.
*
* @param config The general configuration for this extension.
* @param parser The argument parser that has been used to
* parse the new configuration for this
* extension.
* @param adminActionsRequired A list to which messages may be added to
* provide additional information about any
* additional administrative actions that may
* be required to apply some of the
* configuration changes.
* @param messages A list to which messages may be added to
* provide additional information about the
* processing performed by this method.
*
* @return A result code providing information about the result of applying
* the configuration change. A result of {@code SUCCESS} should be
* used to indicate that all processing completed successfully. Any
* other result will indicate that a problem occurred during
* processing.
*/
@Override()
@NotNull()
public ResultCode applyConfiguration(
@NotNull final PassThroughAuthenticationHandlerConfig config,
@NotNull final ArgumentParser parser,
@NotNull final List<String> adminActionsRequired,
@NotNull final List<String> messages)
{
try
{
userMap = readUserMap(config.getServerContext(), parser);
return ResultCode.SUCCESS;
}
catch (final LDAPException e)
{
config.getServerContext().debugCaught(e);
messages.add(e.getMessage());
return e.getResultCode();
}
}
/**
* Reads the user map from the file specified by the user-file argument.
*
* @param serverContext The server context for this pass-through
* authentication handler. It must not be
* {@code null}.
* @param parser The argument parser that has been used to parse the
* configuration for this extension. It must not be
* {@code null}.
*
* @return The map that was read from the target file.
*
* @throws LDAPException If a problem occurs while trying to determine the
* target file or while trying to read and parse its
* contents.
*/
@NotNull()
private Map<DN,JSONObject> readUserMap(
@NotNull final DirectoryServerContext serverContext,
@NotNull final ArgumentParser parser)
throws LDAPException
{
final FileArgument userFileArgument =
parser.getFileArgument(ARG_NAME_USER_FILE);
if ((userFileArgument == null) || (! userFileArgument.isPresent()))
{
// This should not happen, as the argument is declared as required, and
// the server will have already validated the provided set of arguments.
throw new LDAPException(ResultCode.PARAM_ERROR,
"The required '" + ARG_NAME_USER_FILE + "' was not provided.");
}
final File userFile = userFileArgument.getValue();
try (InputStream fileInputStream = userFileArgument.getFileInputStream();
JSONObjectReader jsonReader = new JSONObjectReader(fileInputStream))
{
final Map<DN,JSONObject> m = new HashMap<>();
while (true)
{
final JSONObject jsonObject;
try
{
jsonObject = jsonReader.readObject();
}
catch (final JSONException e)
{
serverContext.debugCaught(e);
throw new LDAPException(ResultCode.DECODING_ERROR,
"An error occurred while attempting to read a JSON object " +
"from file '" + userFile.getAbsolutePath() + ": " +
StaticUtils.getExceptionMessage(e),
e);
}
if (jsonObject == null)
{
return Collections.unmodifiableMap(m);
}
final String dnString =
jsonObject.getFieldAsString(JSON_FIELD_NAME_USER_DN);
if (dnString == null)
{
throw new LDAPException(ResultCode.DECODING_ERROR,
"JSON object " + jsonObject.toSingleLineString() +
" read from file '" + userFile.getAbsolutePath() +
"' is missing the required '" + JSON_FIELD_NAME_USER_DN +
"' field.");
}
final DN dn;
try
{
dn = new DN(dnString);
}
catch (final LDAPException e)
{
serverContext.debugCaught(e);
throw new LDAPException(ResultCode.INVALID_DN_SYNTAX,
"JSON object " + jsonObject.toSingleLineString() +
" read from file '" + userFile.getAbsolutePath() +
"' has a '" + JSON_FIELD_NAME_USER_DN +
"' value that cannot be parsed as a valid DN.",
e);
}
if (dn.isNullDN())
{
throw new LDAPException(ResultCode.INVALID_DN_SYNTAX,
"JSON object " + jsonObject.toSingleLineString() +
" read from file '" + userFile.getAbsolutePath() +
"' has a '" + JSON_FIELD_NAME_USER_DN +
"' value that is an empty DN.");
}
final String password =
jsonObject.getFieldAsString(JSON_FIELD_NAME_USER_PASSWORD);
if (password == null)
{
throw new LDAPException(ResultCode.DECODING_ERROR,
"JSON object " + jsonObject.toSingleLineString() +
" read from file '" + userFile.getAbsolutePath() +
"' is missing the required '" +
JSON_FIELD_NAME_USER_PASSWORD + "' field.");
}
else if (password.isEmpty())
{
throw new LDAPException(ResultCode.DECODING_ERROR,
"JSON object " + jsonObject.toSingleLineString() +
" read from file '" + userFile.getAbsolutePath() +
"' has an empty value for the '" +
JSON_FIELD_NAME_USER_PASSWORD + "' field.");
}
final String resultCodeString =
jsonObject.getFieldAsString(JSON_FIELD_NAME_RESULT_CODE);
if (resultCodeString != null)
{
final PassThroughAuthenticationResultCode resultCode =
PassThroughAuthenticationResultCode.forName(resultCodeString);
if (resultCode == null)
{
throw new LDAPException(ResultCode.DECODING_ERROR,
"JSON object " + jsonObject.toSingleLineString() +
" read from file '" + userFile.getAbsolutePath() +
"' has an unrecognized result code value in the '" +
JSON_FIELD_NAME_RESULT_CODE + "' field.");
}
}
m.put(dn, jsonObject);
}
}
catch (final IOException e)
{
serverContext.debugCaught(e);
throw new LDAPException(ResultCode.LOCAL_ERROR,
"An error occurred while attempting to read from user file '" +
userFileArgument.getValue().getAbsolutePath() + "': " +
StaticUtils.getExceptionMessage(e),
e);
}
}
/**
* Performs any cleanup which may be necessary when this pass-through
* authentication handler is to be taken out of service.
*/
@Override()
public void finalizePassThroughAuthenticationHandler()
{
// No special finalization is required.
}
/**
* Attempts to pass through authentication for the provided bind operation to
* the external service.
*
* @param operationContext The context for the bind operation. It will not
* be {@code null}.
* @param bindRequest The bind request being processed. It will not
* be {@code null}.
* @param localEntry The local entry for the account targeted by the
* bind operation. It will not be {@code null}.
*
* @return The result of the pass-through authentication attempt. It must
* not be {@code null}.
*/
@Override()
@NotNull()
public PassThroughAuthenticationResult attemptPassThroughAuthentication(
@NotNull final OperationContext operationContext,
@NotNull final SimpleBindRequest bindRequest,
@NotNull final Entry localEntry)
{
// Make sure that the bind request has a valid DN. If not, then fail the
// attempt.
final DN bindDN;
final String bindDNString = bindRequest.getDN();
try
{
bindDN = new DN(bindDNString);
}
catch (final LDAPException e)
{
operationContext.getServerContext().debugCaught(e);
final PassThroughAuthenticationResult result =
new PassThroughAuthenticationResult(
PassThroughAuthenticationResultCode.NO_SUCH_USER);
result.setRemoteUserIdentifier(bindDNString);
result.setCustomLogElement(LOG_FIELD_NAME_RESULT_CODE_REASON,
"Unable to parse provided bind DN string '" + bindDNString + "'.");
return result;
}
// Get the JSON object that describes the user with the provided DN. If no
// object exists with that DN, then fail the attempt.
final JSONObject userObject = userMap.get(bindDN);
if (userObject == null)
{
final PassThroughAuthenticationResult result =
new PassThroughAuthenticationResult(
PassThroughAuthenticationResultCode.NO_SUCH_USER);
result.setRemoteUserIdentifier(bindDNString);
result.setCustomLogElement(LOG_FIELD_NAME_RESULT_CODE_REASON,
"User '" + bindDNString + "' does not exist.");
return result;
}
// Make sure that the bind request includes the correct password. if not,
// then fail the attempt.
final String providedPassword = bindRequest.getPassword().stringValue();
final String expectedPassword =
userObject.getFieldAsString(JSON_FIELD_NAME_USER_PASSWORD);
if (! providedPassword.equals(expectedPassword))
{
final PassThroughAuthenticationResult result =
new PassThroughAuthenticationResult(
PassThroughAuthenticationResultCode.WRONG_PASSWORD);
result.setRemoteUserIdentifier(bindDNString);
result.setCustomLogElement(LOG_FIELD_NAME_RESULT_CODE_REASON,
"The wrong password was provided.");
return result;
}
// Create and return an appropriate result. If the user object specifies
// the result code that should be used for this user, then use it.
// Otherwise, go with the default of SUCCESS.
final PassThroughAuthenticationResult result;
final String resultCodeString =
userObject.getFieldAsString(JSON_FIELD_NAME_RESULT_CODE);
if (resultCodeString == null)
{
result = new PassThroughAuthenticationResult(
PassThroughAuthenticationResultCode.SUCCESS);
}
else
{
result = new PassThroughAuthenticationResult(
PassThroughAuthenticationResultCode.forName(resultCodeString));
result.setCustomLogElement(LOG_FIELD_NAME_RESULT_CODE_REASON,
"The result code was specified in the user file.");
}
result.setRemoteUserIdentifier(
userObject.getFieldAsString(JSON_FIELD_NAME_USER_DN));
final String diagnosticMessage =
userObject.getFieldAsString(JSON_FIELD_NAME_DIAGNOSTIC_MESSAGE);
if (diagnosticMessage != null)
{
result.setDiagnosticMessageForClient(diagnosticMessage);
}
return result;
}
/**
* Retrieves a list of any handler-specific attributes that should be included
* in the monitor entry for the associated pluggable pass-through
* authentication plugin.
*
* @return A list of any handler-specific attributes that should be included
* in the monitor entry for the associated plugin. It may be
* {@code null} or empty if no handler-specific monitor attributes
* should be included.
*/
@Override()
@NotNull()
public List<Attribute> getMonitorAttributes()
{
final List<Attribute> monitorAttributes = new ArrayList<>();
monitorAttributes.add(new Attribute("user-count",
String.valueOf(userMap.size())));
return Collections.unmodifiableList(monitorAttributes);
}
/**
* Retrieves a map containing examples of configurations that may be used for
* this extension. The map key should be a list of sample arguments, and the
* corresponding value should be a description of the behavior that will be
* exhibited by the extension when used with that configuration.
*
* @return A map containing examples of configurations that may be used for
* this extension. It may be {@code null} or empty if there should
* not be any example argument sets.
*/
@NotNull()
@Override()
public Map<List<String>,String> getExamplesArgumentSets()
{
return StaticUtils.mapOf(
Collections.singletonList(
ARG_NAME_USER_FILE + "=/path/to/user/file"),
"Defines a pass-through authentication handler that will read user " +
"data from the specified file.");
}
}
