2. Tutorials
  3. Retrofit 2 — Hawk Authentication on Android

Retrofit 2 — Hawk Authentication on Android

Hawk authentication is sort of the underdog in the class of authentication types. It’s been officially around since November 2012 when Eran Hammer (aka hueniverse) published the first version. Since than, the HTTP authentication scheme has evolved to its current version 6.x.

This tutorial guides you through the setup on client side using Android. Additionally, this guide is Retrofit 2 only.

Retrofit Series Overview

  1. Getting Started and Creating an Android Client
  2. Basics of API Description
  3. Creating a Sustainable Android Client
  4. URL Handling, Resolution and Parsing
  5. How to Change API Base Url at Runtime
  6. Multiple Server Environments (Develop, Staging, Production)
  7. Share OkHttp Client and Converters between Retrofit Instances
  8. Upgrade Guide from 1.9
  9. Beyond Android: Retrofit for Java Projects
  10. How to use OkHttp 3 with Retrofit 1
  1. Synchronous and Asynchronous Requests
  2. Send Objects in Request Body
  3. Add Custom Request Header
  4. Manage Request Headers in OkHttp Interceptor
  5. Dynamic Request Headers with @HeaderMap
  6. Multiple Query Parameters of Same Name
  7. Optional Query Parameters
  8. Send Data Form-Urlencoded
  9. Send Data Form-Urlencoded Using FieldMap
  10. How to Add Query Parameters to Every Request
  11. Add Multiple Query Parameter With QueryMap
  12. How to Use Dynamic Urls for Requests
  13. Constant, Default and Logic Values for POST and PUT Requests
  14. Cancel Requests
  15. Reuse and Analyze Requests
  16. Optional Path Parameters
  17. How to Send Plain Text Request Body
  18. Customize Network Timeouts
  19. How to Trust Unsafe SSL certificates (Self-signed, Expired)
  20. Dynamic Endpoint-Dependent Interceptor Actions
  21. How to Update Objects on the Server (PUT vs. PATCH)
  22. How to Delete Objects on the Server
  1. Ignore Response Payload with Call<Void>
  2. Receive Plain-String Responses
  3. Crawl HTML Responses with jspoon (Wikipedia Example)
  4. Loading Data into RecyclerView and CardView
  1. Introduction to (Multiple) Converters
  2. Adding & Customizing the Gson Converter
  3. Implementing Custom Converters
  4. How to Integrate XML Converter
  5. Access Mapped Objects and Raw Response Payload
  6. Supporting JSON and XML Responses Concurrently
  7. Handling of Empty Server Responses with Custom Converter
  8. Send JSON Requests and Receive XML Responses (or vice versa)
  9. Unwrapping Envelope Responses with Custom Converter
  10. Wrapping Requests in Envelope with Custom Converter
  11. Define a Custom Response Converter
  1. Simple Error Handling
  2. Error Handling for Synchronous Requests
  3. Catch Server Errors Globally with Response Interceptor
  4. How to Detect Network and Conversion Errors in onFailure
  1. Log Requests and Responses
  2. Enable Logging for Development Builds Only
  3. Log Network Traffic with Stetho and Chrome Developer Tools
  4. Using the Log Level to Debug Requests
  5. Analyze Network Traffic with Android Studio Profiler
  6. Debug and Compare Requests with RequestBin
  1. Introduction to Call Adapters
  2. Custom Call Adapter to Separate OnResponse Callback
  3. How to Integrate RxJava 1.x Call Adapter
  4. How to Integrate RxJava 2.x Call Adapter
  5. How to Integrate Guava Call Adapter
  6. Custom Call Adapter to Separate Network and Gson Errors
  1. Pagination Using Query Parameter
  2. Pagination Using Link Header and Dynamic Urls (Like GitHub)
  3. Pagination Using Range Header Fields (Like Heroku)
  1. How to Upload Files to Server
  2. How to Upload Multiple Files to Server
  3. How to Upload a Dynamic Amount of Files to Server
  4. Upload Files with Progress
  5. Passing Multiple Parts Along a File with @PartMap
  6. How to Download Files from Server
  7. Download Files with Progress Updates
  8. How to Upload Files to Server
  1. Activate Response Caching (Etag, Last-Modified)
  2. Check Response Origin (Network, Cache, or Both)
  3. Force Server Cache Support with Response Interceptor
  4. Support App Offline Mode by Accessing Response Caches
  5. Analyze Cache Files
  1. Basics of Mocking Server Responses
  2. Customizing Network Behavior of Mocked Server Responses
  3. Mock APIs with JsonServer
  1. Callbacks
  2. Annotations
  3. Fluent Interface with Builders

Why Is This Post Retrofit 2 Only?

The Hawk authentication scheme requires you to generate the HTTP Authorization header including the request url. On Retrofit 1, there is no simple setup to get the request url. This behavior changes with Retrofit 2, because the HTTP layer is completely driven by OkHttp which allows access to the request url using a request interceptor.

Hawk Authentication

Hawk is an HTTP authentication scheme allowing authenticated client requests with partial cryptographic request (and response) verification. The verification includes the HTTP method, request URI, host and optionally the request payload.

We won’t dive deeper into the details of Hawk and assume that you’re already familiar with the authentication scheme. And due to the fact that you’re reading this article, you’ve decided to give it a shot. If you need more information about Hawk, please visit the GitHub project repository and follow the information provided within the Readme.

Add Hawk Dependencies

There are already implementation available for Node.js, Java, Ruby, Python and F#/.Net. We’re using the Java implementation from wealdtech to handle the hawk credentials and header generation on client side (Android). Add the following line to your build.gradle and sync the project in Android Studio.

compile 'com.wealdtech.hawk:hawk-core:1.2.0'

Once the synchronization process finishes, move on with the next paragraph and integrate Hawk into your project.

Integrate Hawk Authentication

Generally, the implementation of Hawk authentication on Android is similar to every other authentication type (like basic, token, or OAuth). Depending on the implementation of your API, you’ll need to send an appropriate value for the HTTP Authorization header field.

If you read the previous articles within the Retrofit series, you’re already familiar with our concept of the ServiceGenerator. We’re using this class to generate service clients from your interface definitions using Retrofit annotations. The following code depicts the createService() method which does all the magic in regard to authorization header generation.

public class ServiceGenerator {

    public static final String API_BASE_URL = "https://your.api-base.url";

    private static OkHttpClient.Builder httpClient = new OkHttpClient.Builder();

    private static Retrofit.Builder builder =
        new Retrofit.Builder()
            .baseUrl(API_BASE_URL)
            .addConverterFactory(GsonConverterFactory.create());


    public static <S> S createService(
            Class<S> serviceClass, final HawkCredentials credentials) {
        if (credentials != null) {
            HawkAuthenticationInterceptor interceptor =
                    new HawkAuthenticationInterceptor(credentials);

            if (!httpClient.interceptors().contains(interceptor)) {
                httpClient.addInterceptor(interceptor);

                builder.client(httpClient.build());
                retrofit = builder.build();
            }
        }

        return retrofit.create(serviceClass);
    }
}

Let’s review the code and what’s actually going on here. The method parameters for createService() are the class you want to be generated (actually it’s the interface) and second the Hawk credentials. After clearing the already defined request interceptors, we’re creating a new one and intercept the request to add the desired header fields.

For the generation of the Authorization header, we need at least the request URI and request method. The used Java library will automatically add the required host information while generating the header.

Once the required authorization header is created, we’re taking the original request as the base reference to create a new one. We set the appropriate header fields and proceed the request chain using our newly created request.

Usage

It’s important to understand, that you need to request your Hawk credentials first before you’re able to use the authentication. Request your credentials like you would for any other authentication type using a login via username and password. Your API should return the Hawk credentials in response which you’ll use for further requests against API endpoints.

Let’s look at the following interface definition which only describes the /me endpoint requiring authentication before returning the User object.

public interface UserService {  
    @POST("me")
    Call<User> me();
}

This article guides you through the setup and usage of the Hawk authentication scheme using Android as the client. We assume that you have already requested your Hawk credentials from the API you’re consuming. If you need to get those credentials first, you may benefit from our basic authentication on Android tutorial as well.

For illustration purposes, we’re using the test credentials from Hawk’s GitHub repository. On server side, we’re using a Node.js server which requires Hawk authentication for the /me endpoint.

HawkCredentials hawkCredentials =  
    new HawkCredentials.Builder()
        .keyId("dh37fgj492je")
        .key("werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn")
        .algorithm(HawkCredentials.Algorithm.SHA256)
        .build();

UserService userService = ServiceGenerator.create(UserService.class, hawkCredentials);  
Call<User> call = userService.me();  
User user = call.execute().body();

Use the Java library to create a HawkCredentials object. Pass this object to the createService() method while generating the service client using the ServiceGenerator. Get the Call object for your request and execute it (synchronous or asynchronous) to receive the response object. The defined OkHttp interceptor will add the authorization token before executing requests.

That’s all the magic! You’re now able to authenticate your requests using the Hawk scheme.

Outlook

We’ve already covered basic and token authentication as well as OAuth on Android. This guide shows you how to create an Android client consuming API’s which require Hawk authentication. You’ve learned how to intercept the request and add the required authorization token based on your credentials.

The next tutorial will show you a generally applicable method to handle errors using Retrofit 2.

Additional Resources

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous