When you use the token-based authentication including OAuth, there are two tokens: access token and refresh token. Whenever you need to access a protected resource, An access token should be used to approve the access right. A refresh Token is a kind of special token. It can be used to get a renewed access token because an access Token has a short lifecycle. The value of expires_in in the response shows how long the access token is valid.
{
"token_type":"bearer",
"access_token":"{ACCESS_TOKEN_VALUE}",
"expires_in":3600,
"refresh_token":"{REFRESH_TOKEN_VALUE}"
}
Typically, an access token is used in the request header. OkHttp supports a handy way to tweak your request before sending it, which is Interceptor. With that, you can add an access token information in the header easily without modifying your request call methods.
OkHttpClient client = okHttpClient.newBuilder()
.addInterceptor(new AccessTokenInterceptor())
.build();
public class AccessTokenInterceptor implements Interceptor {
private final AccessTokenRepository accessTokenRepository;
public AccessTokenInterceptor(AccessTokenRepository accessTokenRepository) {
this.accessTokenRepository = accessTokenRepository;
}
@Override
public Response intercept(Chain chain) throws IOException {
String accessToken = accountRepository.getAccessToken();
Request request = newRequestWithAccessToken(chain.request(), accessToken);
return chain.proceed(request);
}
@NonNull
private Request newRequestWithAccessToken(@NonNull Request request, @NonNull String accessToken) {
return request.newBuilder()
.header("Authorization", "Bearer " + accessToken)
.build();
}
}
This works while an access token is valid. Since the access token can be expired, you need to think how to refresh it. One naive approach could be to schedule a job to refresh before expires_in. It could work but there are things you need to consider.
Application Lifecycle: When an application is stopped, a scheduled job could be gone. You would reschedule the job with considering the last refresh time when the application is started.
Unnecessary Refresh: When a user doesn’t access a protected resource for a long time, you don’t need to refresh an access token. If there is a refreshing every 60 minute considering
expires_in
, there would be unnecessary refreshing 24 times for one day.
Interceptor Approach
While intercepting, Interceptor allows you not only to modify your request but also to send a request and get a response. When an access token is expired, there is an HTTP unauthorized error, with 401 error code, from the backend. That is the best time to refresh an access token.
Below code shows how to do it. First, you need to send a refresh access token request. Then, retry the original request with the renewed access token. There are multiple threads in OkHttp to handle requests. It is important to use synchronized
to avoid additional refreshing.
public class AccessTokenInterceptor implements Interceptor {
...
@Override
public Response intercept(Chain chain) throws IOException {
String accessToken = accessTokenRepository.getAccessToken();
Request request = newRequestWithAccessToken(chain.request(), accessToken);
Response response = chain.proceed(request);
if (response.code() == HttpURLConnection.HTTP_UNAUTHORIZED) {
synchronized (this) {
final String newAccessToken = accessTokenRepository.getAccessToken();
// Access token is refreshed in another thread.
if (!accessToken.equals(newAccessToken)) {
return chain.proceed(newRequestWithAccessToken(request, newAccessToken));
}
// Need to refresh an access token
final String updatedAccessToken = accessTokenRepository.refreshAccessToken();
// Retry the request
return chain.proceed(newRequestWithAccessToken(request, updatedAccessToken));
}
}
return response;
}
...
}
Authenticator Approach
Interceptor
approach could be good enough to refresh an access token. Since the token-based authentication is getting common, OkHttp supports a better way, Authenticator
. Authenticator
is specially designed for refreshing an access token. There are three major benefits to use:
- Auto Retry: If you set a request, it will retry it up to 20 times by default.
- No Response Code Check: In the
Interceptor
approach, you manually check the response code to determine refreshing.Authenticator
is only called when there is an HTTP unauthorized error, so you don’t need to check. - No Interceptor Side Effect: OkHttp can have multiple Interceptors. Each interceptor is called orderly what you set and next Interceptor is executed when
chain.proceed()
is called. InInterceptor
approach, there are twochain.proceed()
. One is for the original request and the other is for retry request. In each time, the next Interceptor is executed, soAnotherInterceptor
could be called twice. Depending on what it does, this could make a side effect.
Authenticator
is triggered for every HTTP unauthorized error. For some authentication type such as Basic
, it is not needed to refresh the access token. So, below code checks the header information first. The return type is @Nullable
. If you return null
, it doesn’t do anything. Also, unlike Interceptor, it returns Request
not Response
.
OkHttpClient client = okHttpClient.newBuilder()
.authenticator(new AccessTokenAuthenticator())
.addInterceptor(new AccessTokenInterceptor())
.build();
public class AccessTokenAuthenticator implements Authenticator {
private final AccessTokenRepository accessTokenRepository;
public AccessTokenAuthenticator(AccessTokenRepository accessTokenRepository) {
this.accessTokenRepository = accessTokenRepository;
}
@Nullable
@Override
public Request authenticate(Route route, Response response) {
final String accessToken = accountRepository.getAccessToken();
if (!isRequestWithAccessToken(response) || accessToken == null) {
return null;
}
synchronized (this) {
final String newAccessToken = accountRepository.getAccessToken();
// Access token is refreshed in another thread.
if (!accessToken.equals(newAccessToken)) {
return newRequestWithAccessToken(response.request(), newAccessToken);
}
// Need to refresh an access token
final String updatedAccessToken = accountRepository.refreshAccessToken();
return newRequestWithAccessToken(response.request(), updatedAccessToken);
}
}
private boolean isRequestWithAccessToken(@NonNull Response response) {
String header = response.request().header("Authorization");
return header != null && header.startsWith("Bearer");
}
@NonNull
private Request newRequestWithAccessToken(@NonNull Request request, @NonNull String accessToken) {
return request.newBuilder()
.header("Authorization", "Bearer " + accessToken)
.build();
}
}
Conclusion
OkHttp supports token-based authentication well. Interceptor
allows you to add the access token information in the header easily. For refreshing the access token, you can use Authenticator
. It is specially designed for that and triggered only when there is an HTTP unauthorized error. Moreover, it will retry automatically and doesn’t call Interceptor
additionally.