1 //
2 // ========================================================================
3 // Copyright (c) 1995-2015 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.http.HttpHeader;
24 import org.eclipse.jetty.util.Attributes;
25
26 /**
27 * {@link Authentication} represents a mechanism to authenticate requests for protected resources.
28 * <p />
29 * {@link Authentication}s are added to an {@link AuthenticationStore}, which is then
30 * {@link #matches(String, URI, String) queried} to find the right
31 * {@link Authentication} mechanism to use based on its type, URI and realm, as returned by
32 * {@code WWW-Authenticate} response headers.
33 * <p />
34 * If an {@link Authentication} mechanism is found, it is then
35 * {@link #authenticate(Request, ContentResponse, HeaderInfo, Attributes) executed} for the given request,
36 * returning an {@link Authentication.Result}, which is then stored in the {@link AuthenticationStore}
37 * so that subsequent requests can be preemptively authenticated.
38 */
39 public interface Authentication
40 {
41 /**
42 * Matches {@link Authentication}s based on the given parameters
43 * @param type the {@link Authentication} type such as "Basic" or "Digest"
44 * @param uri the request URI
45 * @param realm the authentication realm as provided in the {@code WWW-Authenticate} response header
46 * @return true if this authentication matches, false otherwise
47 */
48 boolean matches(String type, URI uri, String realm);
49
50 /**
51 * Executes the authentication mechanism for the given request, returning a {@link Result} that can be
52 * used to actually authenticate the request via {@link Result#apply(Request)}.
53 * <p />
54 * If a request for {@code "/secure"} returns a {@link Result}, then the result may be used for other
55 * requests such as {@code "/secure/foo"} or {@code "/secure/bar"}, unless those resources are protected
56 * by other realms.
57 *
58 * @param request the request to execute the authentication mechanism for
59 * @param response the 401 response obtained in the previous attempt to request the protected resource
60 * @param headerInfo the {@code WWW-Authenticate} (or {@code Proxy-Authenticate}) header chosen for this
61 * authentication (among the many that the response may contain)
62 * @param context the conversation context in case the authentication needs multiple exchanges
63 * to be completed and information needs to be stored across exchanges
64 * @return the authentication result, or null if the authentication could not be performed
65 */
66 Result authenticate(Request request, ContentResponse response, HeaderInfo headerInfo, Attributes context);
67
68 /**
69 * Structure holding information about the {@code WWW-Authenticate} (or {@code Proxy-Authenticate}) header.
70 */
71 public static class HeaderInfo
72 {
73 private final String type;
74 private final String realm;
75 private final String params;
76 private final HttpHeader header;
77
78 public HeaderInfo(String type, String realm, String params, HttpHeader header)
79 {
80 this.type = type;
81 this.realm = realm;
82 this.params = params;
83 this.header = header;
84 }
85
86 /**
87 * @return the authentication type (for example "Basic" or "Digest")
88 */
89 public String getType()
90 {
91 return type;
92 }
93
94 /**
95 * @return the realm name
96 */
97 public String getRealm()
98 {
99 return realm;
100 }
101
102 /**
103 * @return additional authentication parameters
104 */
105 public String getParameters()
106 {
107 return params;
108 }
109
110 /**
111 * @return the {@code Authorization} (or {@code Proxy-Authorization}) header
112 */
113 public HttpHeader getHeader()
114 {
115 return header;
116 }
117 }
118
119 /**
120 * {@link Result} holds the information needed to authenticate a {@link Request} via {@link #apply(Request)}.
121 */
122 public static interface Result
123 {
124 /**
125 * @return the URI of the request that has been used to generate this {@link Result}
126 */
127 URI getURI();
128
129 /**
130 * Applies the authentication result to the given request.
131 * Typically, a {@code Authorization} header is added to the request, with the right information to
132 * successfully authenticate at the server.
133 *
134 * @param request the request to authenticate
135 */
136 void apply(Request request);
137 }
138 }