| // ======================================================================== |
| // Copyright (c) 1995-2017 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. |
| // ======================================================================== |
| |
| [[http-client-proxy]] |
| === Proxy Support |
| |
| Jetty's HTTP client can be configured to use proxies to connect to destinations. |
| |
| Two types of proxies are available out of the box: a HTTP proxy (provided by class `org.eclipse.jetty.client.HttpProxy`) and a SOCKS 4 proxy (provided by class `org.eclipse.jetty.client.Socks4Proxy`). |
| Other implementations may be written by subclassing `ProxyConfiguration.Proxy`. |
| |
| The following is a typical configuration: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| ProxyConfiguration proxyConfig = httpClient.getProxyConfiguration(); |
| HttpProxy proxy = new HttpProxy("proxyHost", proxyPort); |
| |
| // Do not proxy requests for localhost:8080 |
| proxy.getExcludedAddresses().add("localhost:8080"); |
| |
| // add the new proxy to the list of proxies already registered |
| proxyConfig.getProxies().add(proxy); |
| |
| ContentResponse response = httpClient.GET(uri); |
| ---- |
| |
| You specify the proxy host and port, and optionally also the addresses that you do not want to be proxied, and then add the proxy configuration on the `ProxyConfiguration` instance. |
| |
| Configured in this way, `HttpClient` makes requests to the HTTP proxy (for plain-text HTTP requests) or establishes a tunnel via `HTTP CONNECT` (for encrypted HTTPS requests). |
| |
| [[http-client-proxy-authentication]] |
| ==== Proxy Authentication Support |
| |
| Jetty's HTTP client support proxy authentication in the same way it supports link:#http-client-authentication[server authentication]. |
| |
| In the example below, the proxy requires Basic authentication, but the server requires Digest authentication, and therefore: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| URI proxyURI = new URI("http://proxy.net:8080"); |
| URI serverURI = new URI("http://domain.com/secure"); |
| |
| AuthenticationStore auth = httpClient.getAuthenticationStore(); |
| |
| // Proxy credentials. |
| auth.addAuthentication(new BasicAuthentication(proxyURI, "ProxyRealm", "proxyUser", "proxyPass")); |
| |
| // Server credentials. |
| auth.addAuthentication(new DigestAuthentication(serverURI, "ServerRealm", "serverUser", "serverPass")); |
| |
| // Proxy configuration. |
| ProxyConfiguration proxyConfig = httpClient.getProxyConfiguration(); |
| HttpProxy proxy = new HttpProxy("proxy.net", 8080); |
| proxyConfig.getProxies().add(proxy); |
| |
| ContentResponse response = httpClient.newRequest(serverURI) |
| .send() |
| .get(5, TimeUnit.SECONDS); |
| ---- |
| |
| The HTTP conversation for successful authentications on both the proxy and the server is the following: |
| |
| ---- |
| Application HttpClient Proxy Server |
| | | | | |
| |--- GET -->|------------- GET ------------->| | |
| | | | | |
| | |<----- 407 + Proxy-Authn -------| | |
| | | | | |
| | |------ GET + Proxy-Authz ------>| | |
| | | | | |
| | | |---------- GET --------->| |
| | | | | |
| | | |<--- 401 + WWW-Authn ----| |
| | | | | |
| | |<------ 401 + WWW-Authn --------| | |
| | | | | |
| | |-- GET + Proxy-Authz + Authz -->| | |
| | | | | |
| | | |------ GET + Authz ----->| |
| | | | | |
| |<-- 200 ---|<------------ 200 --------------|<--------- 200 ----------| |
| ---- |
| |
| The application does not receive events related to the responses with code 407 and 401 since they are handled internally by `HttpClient`. |
| |
| Similarly to the link:#http-client-authentication[authentication section], the proxy authentication result and the server authentication result can be preempted to avoid, respectively, the 407 and 401 roundtrips. |
