com.unboundid.directory.sdk.broker.api

Class IdentityAuthenticator

java.lang.Object

com.unboundid.directory.sdk.broker.api.IdentityAuthenticator

All Implemented Interfaces:

Configurable, ExampleUsageProvider, UnboundIDExtension

@Extensible
 @BrokerExtension
 @ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class IdentityAuthenticator
extends java.lang.Object
implements UnboundIDExtension, Configurable, ExampleUsageProvider

This class defines an API that may be implemented by extensions that provide a way to authenticate a user or provide additional assurance about the identity of a user that has already been authenticated. This API is generic and can support a wide range of authentication and second-factor authentication methods.

Configuring Identity Authenticators

In order to configure an Identity Authenticator created using this API, use a command like:

      dsconfig create-identity-authenticator \
           ---authenticator-name "{name}" \
           --type third-party \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
 

where "{name}" is the name to use for the Identity Authenticator instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.broker.api.IdentityAuthenticator, and "{name=value}" represents name-value pairs for any arguments to provide to the Identity Authenticator. If multiple arguments should be provided to the extension, then the "--set extension-argument:{name=value}" option should be provided multiple times.

Constructor Summary

Constructors

Constructor and Description
IdentityAuthenticator() Creates a new instance of this Identity Authenticator.

Method Summary

Modifier and Type	Method and Description
abstract AuthenticationResult	authenticate(AuthenticationRequest request) Process an authentication request.
void	defineConfigArguments(com.unboundid.util.args.ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizeAuthenticator() This hook is called when the Identity Authenticator is disabled or the server shuts down.
java.util.Map<java.util.List<java.lang.String>,java.lang.String>	getExamplesArgumentSets() Retrieves a map containing examples of configurations that may be used for this extension.
abstract java.lang.String[]	getExtensionDescription() Retrieves a human-readable description for this extension.
abstract java.lang.String	getExtensionName() Retrieves a human-readable name for this extension.
abstract StatusResult	getStatus(StatusRequest request) Process a status request.
void	initializeAuthenticator(BrokerContext serverContext, IdentityAuthenticatorConfig config, com.unboundid.util.args.ArgumentParser parser) Initializes this Identity Authenticator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IdentityAuthenticator

public IdentityAuthenticator()

Creates a new instance of this Identity Authenticator. All implementations must include a default constructor, but any initialization should generally be done in the initializeAuthenticator(com.unboundid.directory.sdk.broker.types.BrokerContext, com.unboundid.directory.sdk.broker.config.IdentityAuthenticatorConfig, com.unboundid.util.args.ArgumentParser) method.

Method Detail

getExtensionName

public abstract java.lang.String getExtensionName()

Retrieves a human-readable name for this extension.

Specified by:

getExtensionName in interface UnboundIDExtension

Returns:

A human-readable name for this extension.

getExtensionDescription

public abstract java.lang.String[] getExtensionDescription()

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.

Specified by:

getExtensionDescription in interface UnboundIDExtension

Returns:

A human-readable description for this extension, or null or an empty array if no description should be available.

getExamplesArgumentSets

public java.util.Map<java.util.List<java.lang.String>,java.lang.String> getExamplesArgumentSets()

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.

Specified by:

getExamplesArgumentSets in interface ExampleUsageProvider

Returns:

A map containing examples of configurations that may be used for this extension. It may be null or empty if there should not be any example argument sets.

defineConfigArguments

public void defineConfigArguments(com.unboundid.util.args.ArgumentParser parser)
                           throws com.unboundid.util.args.ArgumentException

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).

Specified by:

defineConfigArguments in interface Configurable

Parameters:

parser - The argument parser to be updated with the configuration arguments which may be used by this extension.

Throws:

com.unboundid.util.args.ArgumentException - If a problem is encountered while updating the provided argument parser.

initializeAuthenticator

public void initializeAuthenticator(BrokerContext serverContext,
                                    IdentityAuthenticatorConfig config,
                                    com.unboundid.util.args.ArgumentParser parser)
                             throws java.lang.Exception

Initializes this Identity Authenticator. Any initialization should be performed here. This method should generally store the BrokerContext in a class member so that it can be used elsewhere in the implementation.

The default implementation is empty.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running. Extensions should typically store this in a class member.

config - The general configuration for this object.

parser - The argument parser which has been initialized from the configuration for this Identity Authenticator.

Throws:

java.lang.Exception - If a problem occurs while initializing this store adapter.

finalizeAuthenticator

public void finalizeAuthenticator()

This hook is called when the Identity Authenticator is disabled or the server shuts down. Any clean-up of this Identity Authenticator should be performed here.

The default implementation is empty.

getStatus

public abstract StatusResult getStatus(StatusRequest request)

Process a status request. The current state of the authenticator for this flow should be returned in the response parameters.

The content of the response parameters is entirely up to the Identity Authenticator implementation, and should be documented by the implementation.

Parameters:

request - The status request details.

Returns:

The results of the status request.

authenticate

public abstract AuthenticationResult authenticate(AuthenticationRequest request)

Process an authentication request. An authentication process, or flow, for a given Identity Authenticator may be composed of multiple steps (or interactions with the end user or user interface). This method call represents a single authentication step.

If the authentication flow requires further steps, then the result should contain response parameters that can be used to complete the flow. The result must also contain flow state parameters, which will be preserved and resubmitted in the request for the next step. The server encrypts the content of the returned flow state parameters in order to protect any sensitive information.

When the authentication flow is completed successfully, the result must contain the name of the authenticated principal. If authentication fails (e.g. invalid credentials), an unsuccessful result must be returned, rather than an exception.

An authenticator should only return success if the client provided the correct credentials. If additional info is needed or if the provided credentials are incorrect, it should return false. The authenticator should set the principal in the result if it can identify a user with the provided credentials. Otherwise, it should return the principal that was passed in.

The content of the request parameters and response parameters is entirely up to the Identity Authenticator implementation, and should be documented by the implementation.

Parameters:

request - The authentication request details.

Returns:

The results of the authentication request.