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