public interface Authenticator
To make HTTPS calls using an HTTP proxy server OkHttp must first negotiate a connection with the proxy. This proxy connection is called a "TLS Tunnel" and is specified by RFC 2817. The HTTP CONNECT request that creates this tunnel connection is special: it does not participate in any interceptors or event listeners. It doesn't include the motivating request's HTTP headers or even its full URL; only the target server's hostname is sent to the proxy.
Prior to sending any CONNECT request OkHttp always calls the proxy authenticator so that it
may prepare preemptive authentication. OkHttp will call authenticate(okhttp3.Route, okhttp3.Response)
with a fake HTTP/1.1 407 Proxy Authentication Required
response that has a Proxy-Authenticate:
OkHttp-Preemptive
challenge. The proxy authenticator may return either either an authenticated
request, or null to connect without authentication.
for (Challenge challenge : response.challenges()) {
// If this is preemptive auth, use a preemptive credential.
if (challenge.scheme().equalsIgnoreCase("OkHttp-Preemptive")) {
return response.request().newBuilder()
.header("Proxy-Authorization", "secret")
.build();
}
}
return null; // Didn't find a preemptive auth scheme.
Implementations authenticate by returning a follow-up request that includes an authorization header, or they may decline the challenge by returning null. In this case the unauthenticated response will be returned to the caller that triggered it.
Implementations should check if the initial request already included an attempt to authenticate. If so it is likely that further attempts will not be useful and the authenticator should give up.
When reactive authentication is requested by an origin web server, the response code is 401 and the implementation should respond with a new request that sets the "Authorization" header.
if (response.request().header("Authorization") != null) {
return null; // Give up, we've already failed to authenticate.
}
String credential = Credentials.basic(...)
return response.request().newBuilder()
.header("Authorization", credential)
.build();
When reactive authentication is requested by a proxy server, the response code is 407 and the implementation should respond with a new request that sets the "Proxy-Authorization" header.
if (response.request().header("Proxy-Authorization") != null) {
return null; // Give up, we've already failed to authenticate.
}
String credential = Credentials.basic(...)
return response.request().newBuilder()
.header("Proxy-Authorization", credential)
.build();
The proxy authenticator may implement preemptive authentication, reactive authentication, or both.
Applications may configure OkHttp with an authenticator for origin servers, or proxy servers, or both.
Modifier and Type | Field and Description |
---|---|
static Authenticator |
NONE
An authenticator that knows no credentials and makes no attempt to authenticate.
|
Modifier and Type | Method and Description |
---|---|
Request |
authenticate(Route route,
Response response)
Returns a request that includes a credential to satisfy an authentication challenge in
response . |
static final Authenticator NONE
@Nullable Request authenticate(@Nullable Route route, Response response) throws IOException
response
. Returns null if the challenge cannot be satisfied.
The route is best effort, it currently may not always be provided even when logically available. It may also not be provided when an authenticator is re-used manually in an application interceptor, such as when implementing client-specific retries.
IOException
Copyright © 2019. All rights reserved.