// Copyright 2013 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.enterprise.adaptor;

import com.sun.net.httpserver.HttpExchange;

import java.io.IOException;

/**
 * Interface for adaptors capable of authenticating users.
 *
 * <p>Instances of this interface are typically registered with {@link
 * AdaptorContext#setAuthnAuthority}.
 */
public interface AuthnAuthority {
  /**
   * Authenticate the user connected via {@code ex}. After attempting to
   * authenticate the user the implementation should respond by calling {@link
   * Callback#userAuthenticated}.
   *
   * <p>The implementation is expected to provide a response to the user with
   * {@code ex}. Since authentication commonly requires redirects, forms, and
   * other general HTTP mechanisms, full control is given to the implementation.
   * The implementation will likely need to use its own {@link
   * com.sun.net.httpserver.HttpHandler}s that can be registered with {@link
   * AdaptorContext#createHttpContext}.
   *
   * <p>If an implementation places {@code callback} in a session object, the
   * implementation should also remove the instance when {@code
   * userAuthenticated()} is called. This is to release resources as well as
   * preventing re-use of the callback.
   *
   * @param ex exchange whose request body has been processed, but whose
   *     response body and headers have not been sent
   * @param callback object to receive and respond with authentication results
   */
  public void authenticateUser(HttpExchange ex, Callback callback)
      throws IOException;

  /**
   * Interface for replying to {@link #authenticateUser
   * AuthnAdaptor.authenticateUser(HttpExchange, Callback)}.
   */
  public interface Callback {
    /**
     * Respond with authentication information discovered during {@link
     * #authenticateUser AuthnAdaptor.authenticateUser(HttpExchange, Callback)}.
     * The exchange {@code ex} does not need to be the same instance provided to
     * {@code authenticateUser()}, but it does need to be a connection to the
     * same client. This method provides a response to the client using {@code
     * ex}, so the exchange should not have had its headers sent and should be
     * considered completed after the method returns.
     *
     * <p>If authentication failed, then identity should be {@code null}. If an
     * {@code identity} is provided, its username must not be {@code null} or
     * empty.
     *
     * @param ex exchange whose request body has been processed, but whose
     *     response body and headers have not been sent
     * @param identity authenticated user identity information, or {@code null}
     */
    public void userAuthenticated(HttpExchange ex, AuthnIdentity identity)
        throws IOException;
  }
}