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 * trunk/ds/resource/legal-notices/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 * trunk/ds/resource/legal-notices/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 2016-2017 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.broker.api;
028
029import com.unboundid.directory.sdk.broker.config.IdentityAuthenticatorConfig;
030import com.unboundid.directory.sdk.broker.internal.BrokerExtension;
031import com.unboundid.directory.sdk.broker.types.AuthenticationRequest;
032import com.unboundid.directory.sdk.broker.types.AuthenticationResult;
033import com.unboundid.directory.sdk.broker.types.BrokerContext;
034import com.unboundid.directory.sdk.broker.types.StatusRequest;
035import com.unboundid.directory.sdk.broker.types.StatusResult;
036import com.unboundid.directory.sdk.common.internal.Configurable;
037import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
038import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
039import com.unboundid.util.Extensible;
040import com.unboundid.util.ThreadSafety;
041import com.unboundid.util.ThreadSafetyLevel;
042import com.unboundid.util.args.ArgumentException;
043import com.unboundid.util.args.ArgumentParser;
044
045import java.util.Collections;
046import java.util.List;
047import java.util.Map;
048
049
050
051/**
052 * This class defines an API that may be implemented by extensions that provide
053 * a way to authenticate a user or provide additional assurance about the
054 * identity of a user that has already been authenticated.
055 * This API is generic and can support a wide range of authentication and
056 * second-factor authentication methods.
057 *
058 * <H2>Configuring Identity Authenticators</H2>
059 * <p>
060 * In order to configure an Identity Authenticator created using this API, use
061 * a command like:
062 * </p>
063 * <PRE>
064 *      dsconfig create-identity-authenticator \
065 *           ---authenticator-name "<I>{name}</I>" \
066 *           --type third-party \
067 *           --set "extension-class:<I>{class-name}</I>" \
068 *           --set "extension-argument:<I>{name=value}</I>"
069 * </PRE>
070 * where "<I>{name}</I>" is the name to use for the Identity Authenticator
071 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Java class
072 * that extends
073 * {@code com.unboundid.directory.sdk.broker.api.IdentityAuthenticator},
074 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to
075 * provide to the Identity Authenticator. If multiple arguments should be
076 * provided to the extension, then the
077 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
078 * provided multiple times.
079 */
080@Extensible()
081@BrokerExtension
082@ThreadSafety(level= ThreadSafetyLevel.INTERFACE_THREADSAFE)
083public abstract class IdentityAuthenticator implements UnboundIDExtension,
084        Configurable, ExampleUsageProvider
085{
086  /**
087   * Creates a new instance of this Identity Authenticator.  All
088   * implementations must include a default constructor, but any
089   * initialization should generally be done in the
090   * {@link #initializeAuthenticator} method.
091   */
092  public IdentityAuthenticator()
093  {
094    // No implementation is required.
095  }
096
097
098
099  /**
100   * {@inheritDoc}
101   */
102  @Override
103  public abstract String getExtensionName();
104
105
106
107  /**
108   * {@inheritDoc}
109   */
110  @Override
111  public abstract String[] getExtensionDescription();
112
113
114
115  /**
116   * {@inheritDoc}
117   */
118  @Override
119  public Map<List<String>,String> getExamplesArgumentSets()
120  {
121    return Collections.emptyMap();
122  }
123
124
125
126  /**
127   * {@inheritDoc}
128   */
129  @Override
130  public void defineConfigArguments(final ArgumentParser parser)
131         throws ArgumentException
132  {
133    // No arguments will be allowed by default.
134  }
135
136
137
138  /**
139   * Initializes this Identity Authenticator. Any initialization should be
140   * performed here. This method should generally store the
141   * {@link BrokerContext} in a class member so that it can be used elsewhere
142   * in the implementation.
143   * <p>
144   * The default implementation is empty.
145   *
146   * @param  serverContext  A handle to the server context for the server in
147   *                        which this extension is running. Extensions should
148   *                        typically store this in a class member.
149   * @param  config         The general configuration for this object.
150   * @param  parser         The argument parser which has been initialized from
151   *                        the configuration for this Identity Authenticator.
152   * @throws Exception      If a problem occurs while initializing this store
153   *                        adapter.
154   */
155  public void initializeAuthenticator(final BrokerContext serverContext,
156                                      final IdentityAuthenticatorConfig config,
157                                      final ArgumentParser parser)
158      throws Exception
159  {
160    // No initialization will be performed by default.
161  }
162
163
164
165  /**
166   * This hook is called when the Identity Authenticator is disabled or the
167   * server shuts down. Any clean-up of this Identity Authenticator should
168   * be performed here.
169   * <p>
170   * The default implementation is empty.
171   */
172  public void finalizeAuthenticator()
173  {
174    // No implementation is performed by default.
175  }
176
177  /**
178   * Process a status request. The current state of the authenticator for this
179   * flow should be returned in the response parameters.
180   * <p>
181   * The content of the response parameters is entirely up to the Identity
182   * Authenticator implementation, and should be documented by the
183   * implementation.
184   *
185   * @param request The status request details.
186   *
187   * @return  The results of the status request.
188   */
189  public abstract StatusResult getStatus(final StatusRequest request);
190
191  /**
192   * Process an authentication request. An authentication process, or flow,
193   * for a given Identity Authenticator may be composed of multiple steps
194   * (or interactions with the end user or user interface). This method call
195   * represents a single authentication step.
196   * <p>
197   * If the authentication flow requires further steps, then the result should
198   * contain response parameters that can be used to complete the flow.
199   * The result must also contain flow state parameters, which will be
200   * preserved and resubmitted in the request for the next step. The server
201   * encrypts the content of the returned flow state parameters in order to
202   * protect any sensitive information.
203   * <p>
204   * When the authentication flow is completed successfully, the result must
205   * contain the name of the authenticated principal. If authentication fails
206   * (e.g. invalid credentials), an unsuccessful result must be returned,
207   * rather than an exception.
208   * <p>
209   * An authenticator should only return success if the client provided the
210   * correct credentials. If additional info is needed or if the provided
211   * credentials are incorrect, it should return false. The authenticator
212   * should set the principal in the result if it can identify a user with
213   * the provided credentials. Otherwise, it should return the principal
214   * that was passed in.
215   * <p>
216   * The content of the request parameters and response parameters is entirely
217   * up to the Identity Authenticator implementation, and should be documented
218   * by the implementation.
219   *
220   * @param request The authentication request details.
221   *
222   * @return  The results of the authentication request.
223   */
224  public abstract AuthenticationResult authenticate(
225      final AuthenticationRequest request);
226}