/**
 * Authenticates the user with the given user name and password.
 *
 * @param username The name of the user presented by the client
 * @param password The password presented by the client
 * @return Some object representing the authenticated user indicating general
 *         access to be granted to the web console. If the user cannot be
 *         authenticated (e.g. unknown user name or wrong password) or the
 *         user must not be allowed access to the web console at all
 *         <code>null</code> must be returned from this method.
 */
public Object authenticate( String username, String password );


/**
 * Checks whether bthe authenticated user has the given role permission.
 *
 * @param user The object referring to the authenticated user. This is the
 *      object returned from the {@link #authenticate(String, String)}
 *      method and will never be <code>null</code>.
 * @param role The requested role
 * @return <code>true</code> if the user is given permission for the given
 *      role.
 */
public boolean authorize( Object user, String role );

/**
 * The name of the request attribute providing the object representing the
 * authenticated user. This object is used to call the
 * {@link WebConsoleSecurityProvider#authorize(Object, String)} to
 * authorize access for certain roles.
 */
String USER_ATTRIBUTE = "org.apache.felix.webconsole.user";


/**
 * Authenticates the given request or asks the client for credentials.
 * <p>
 * Implementations of this method are expected to respect and implement
 * the semantics of the <code>HttpContext.handleSecurity</code> method
 * as specified in the OSGi HTTP Service specification.
 * <p>
 * If this method returns <code>true</code> it is assumed the request
 * provided valid credentials identifying the user as accepted to access
 * the web console. In addition, the {@link #USER_ATTRIBUTE} request
 * attribute must be set to a non-<code>null</code> object reference
 * identifying the authenticated user.
 * <p>
 * If this method returns <code>false</code> the request to the web console
 * is terminated without any more response sent back to the client. That is
 * the implementation is expected to have informed the client in case of
 * non-granted access.
 *
 * @param request The request object
 * @param response The response object
 * @return <code>true</code> If the request provided valid credentials.
 */
public boolean authenticate( HttpServletRequest request, HttpServletResponse response );