1 //
2 // ========================================================================
3 // Copyright (c) 1995-2013 Mort Bay Consulting Pty. Ltd.
4 // ------------------------------------------------------------------------
5 // All rights reserved. This program and the accompanying materials
6 // are made available under the terms of the Eclipse Public License v1.0
7 // and Apache License v2.0 which accompanies this distribution.
8 //
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
11 //
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
14 //
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
17 //
18
19 package org.eclipse.jetty.client.api;
20
21 import java.net.URI;
22
23 import org.eclipse.jetty.util.Attributes;
24
25 /**
26 * {@link Authentication} represents a mechanism to authenticate requests for protected resources.
27 * <p />
28 * {@link Authentication}s are added to an {@link AuthenticationStore}, which is then
29 * {@link #matches(String, String, String) queried} to find the right
30 * {@link Authentication} mechanism to use based on its type, URI and realm, as returned by
31 * {@code WWW-Authenticate} response headers.
32 * <p />
33 * If an {@link Authentication} mechanism is found, it is then
34 * {@link #authenticate(Request, ContentResponse, String, Attributes) executed} for the given request,
35 * returning an {@link Authentication.Result}, which is then stored in the {@link AuthenticationStore}
36 * so that subsequent requests can be preemptively authenticated.
37 */
38 public interface Authentication
39 {
40 /**
41 * Matches {@link Authentication}s based on the given parameters
42 * @param type the {@link Authentication} type such as "Basic" or "Digest"
43 * @param uri the request URI
44 * @param realm the authentication realm as provided in the {@code WWW-Authenticate} response header
45 * @return true if this authentication matches, false otherwise
46 */
47 boolean matches(String type, URI uri, String realm);
48
49 /**
50 * Executes the authentication mechanism for the given request, returning a {@link Result} that can be
51 * used to actually authenticate the request via {@link Result#apply(Request)}.
52 * <p />
53 * If a request for {@code "/secure"} returns a {@link Result}, then the result may be used for other
54 * requests such as {@code "/secure/foo"} or {@code "/secure/bar"}, unless those resources are protected
55 * by other realms.
56 *
57 * @param request the request to execute the authentication mechanism for
58 * @param response the 401 response obtained in the previous attempt to request the protected resource
59 * @param wwwAuthenticate the {@code WWW-Authenticate} header chosen for this authentication
60 * (among the many that the response may contain)
61 * @param context the conversation context in case the authentication needs multiple exchanges
62 * to be completed and information needs to be stored across exchanges
63 * @return the authentication result, or null if the authentication could not be performed
64 */
65 Result authenticate(Request request, ContentResponse response, String wwwAuthenticate, Attributes context);
66
67 /**
68 * {@link Result} holds the information needed to authenticate a {@link Request} via {@link #apply(Request)}.
69 */
70 public static interface Result
71 {
72 /**
73 * @return the URI of the request that has been used to generate this {@link Result}
74 */
75 URI getURI();
76
77 /**
78 * Applies the authentication result to the given request.
79 * Typically, a {@code Authorization} header is added to the request, with the right information to
80 * successfully authenticate at the server.
81 *
82 * @param request the request to authenticate
83 */
84 void apply(Request request);
85 }
86 }