jetty-client/src/main/java/org/eclipse/jetty/client/api/Authentication.java

//
//  ========================================================================
//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
//  ------------------------------------------------------------------------
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================
//

package org.eclipse.jetty.client.api;

import java.net.URI;

import org.eclipse.jetty.http.HttpHeader;
import org.eclipse.jetty.util.Attributes;

/**
 * {@link Authentication} represents a mechanism to authenticate requests for protected resources.
 * <p>
 * {@link Authentication}s are added to an {@link AuthenticationStore}, which is then
 * {@link #matches(String, URI, String) queried} to find the right
 * {@link Authentication} mechanism to use based on its type, URI and realm, as returned by
 * {@code WWW-Authenticate} response headers.
 * <p>
 * If an {@link Authentication} mechanism is found, it is then
 * {@link #authenticate(Request, ContentResponse, HeaderInfo, Attributes) executed} for the given request,
 * returning an {@link Authentication.Result}, which is then stored in the {@link AuthenticationStore}
 * so that subsequent requests can be preemptively authenticated.
 */
public interface Authentication
{
    /**
     * Matches {@link Authentication}s based on the given parameters
     * @param type the {@link Authentication} type such as "Basic" or "Digest"
     * @param uri the request URI
     * @param realm the authentication realm as provided in the {@code WWW-Authenticate} response header
     * @return true if this authentication matches, false otherwise
     */
    boolean matches(String type, URI uri, String realm);

    /**
     * Executes the authentication mechanism for the given request, returning a {@link Result} that can be
     * used to actually authenticate the request via {@link org.eclipse.jetty.client.api.Authentication.Result#apply(Request)}.
     * <p>
     * If a request for {@code "/secure"} returns a {@link Result}, then the result may be used for other
     * requests such as {@code "/secure/foo"} or {@code "/secure/bar"}, unless those resources are protected
     * by other realms.
     *
     * @param request the request to execute the authentication mechanism for
     * @param response the 401 response obtained in the previous attempt to request the protected resource
     * @param headerInfo the {@code WWW-Authenticate} (or {@code Proxy-Authenticate}) header chosen for this
     *                     authentication (among the many that the response may contain)
     * @param context the conversation context in case the authentication needs multiple exchanges
     *                to be completed and information needs to be stored across exchanges
     * @return the authentication result, or null if the authentication could not be performed
     */
    Result authenticate(Request request, ContentResponse response, HeaderInfo headerInfo, Attributes context);

    /**
     * Structure holding information about the {@code WWW-Authenticate} (or {@code Proxy-Authenticate}) header.
     */
    public static class HeaderInfo
    {
        private final String type;
        private final String realm;
        private final String params;
        private final HttpHeader header;

        public HeaderInfo(String type, String realm, String params, HttpHeader header)
        {
            this.type = type;
            this.realm = realm;
            this.params = params;
            this.header = header;
        }

        /**
         * @return the authentication type (for example "Basic" or "Digest")
         */
        public String getType()
        {
            return type;
        }

        /**
         * @return the realm name
         */
        public String getRealm()
        {
            return realm;
        }

        /**
         * @return additional authentication parameters
         */
        public String getParameters()
        {
            return params;
        }

        /**
         * @return the {@code Authorization} (or {@code Proxy-Authorization}) header
         */
        public HttpHeader getHeader()
        {
            return header;
        }
    }

    /**
     * {@link Result} holds the information needed to authenticate a {@link Request} via {@link org.eclipse.jetty.client.api.Authentication.Result#apply(org.eclipse.jetty.client.api.Request)}.
     */
    public static interface Result
    {
        /**
         * @return the URI of the request that has been used to generate this {@link Result}
         */
        URI getURI();

        /**
         * Applies the authentication result to the given request.
         * Typically, a {@code Authorization} header is added to the request, with the right information to
         * successfully authenticate at the server.
         *
         * @param request the request to authenticate
         */
        void apply(Request request);
    }
}