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 * 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 org.eclipse.jetty.client.api.Authentication.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 org.eclipse.jetty.client.api.Authentication.Result#apply(org.eclipse.jetty.client.api.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 }