Guide to ScribeJava

1. Introduction

In this tutorial, we’re going to look at the ScribeJava library.

ScribeJava is a simple OAuth client for Java which helps manage the OAuth flow.

The main feature of the library is that it supports all major 1.0 and 2.0 OAuth APIs out-of-the-box. Moreover, if we’ll have to work with an API that’s not supported, the library provides a couple of classes for implements our OAuth’s APIs.

Another important feature is that is possible to choose which client use. Indeed, ScribeJava supports several HTTP clients:

• Async Http Client
• OkHttp
• Apache HttpComponents HttpClient

Furthermore, the library is thread-safe and Java7-compatible, so we can use it in legacy environments.

2. Dependencies

ScribeJava is organized into a core and APIs module, the latter includes a set of external API (Google, GitHub, Twitter, etc) and the core artifact:

<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-apis</artifactId>
    <version>latest-version</version>
</dependency>

In case we need just core classes without any external API, we have to pull just core module:

<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-core</artifactId>
    <version>latest-version</version>
</dependency>

The latest versions can be found at Maven repository.

3. OAuthService

The main part of the library is the abstract class OAuthService which contains all the parameters needed to correctly manage the OAuth’s ‘handshake’.

Depending on the version of the protocol, we’ll use Oauth10Service or Oauth20Service concrete classes respectively for OAuth 1.0 and OAuth 2.0.

In order to build the OAuthService implementations, the library provides a ServiceBuilder:

OAuthService service = new ServiceBuilder("api_key")
  .apiSecret("api_secret")
  .scope("scope")
  .callback("callback")
  .build(GoogleApi20.instance());

We should set the api_key and the api_secret tokens provided by the authorization server.

Also, we can set the scope of the request and the callback to which the authorization server should redirect the user at the end of the authorization flow.

Note that depending on the version of the protocol not all parameters are mandatory.

Finally, we have to build the OAuthService calling the build() method and passing it an instance of the APIs we want to use. We can find a full list of the APIs supported at ScribeJava GitHub.

3.1. HTTP Client

Moreover, the library allows us to choose which HTTP Client to use:

ServiceBuilder builder = new ServiceBuilder("api_key")
  .httpClient(new OkHttpHttpClient());

After, of course, we have included the required dependencies, for the previous example:

<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-httpclient-okhttp</artifactId>
    <version>latest-version</version>
</dependency>

The latest versions can be found at Maven repository.

3.2. Debug Mode

In addition, there’s a debug mode we can use to help us troubleshooting:

ServiceBuilder builder = new ServiceBuilder("api_key")
  .debug();

We simply have to call debug() method. Debug will output to System.out some relevant information.

Also, if we want to use a different output, there’s another method that accepts an OutputStream to send the debugging information to:

FileOutputStream debugFile = new FileOutputStream("debug");

ServiceBuilder builder = new ServiceBuilder("api_key")
  .debug()
  .debugStream(debugFile);

4. OAuth 1.0 Flow

Now let’s focus on how to handle an OAuth1 flow.

In this example, we’re going to get an access token with the Twitter APIs and we’ll use it to make a request.

First of all, we have to build the Oauth10Service, as we saw earlier, using builder:

OAuth10aService service = new ServiceBuilder("api_key")
  .apiSecret("api_secret")
  .build(TwitterApi.instance());

Once we have the OAuth10Service, we can get a requestToken and use it to get the authorization URL:

OAuth1RequestToken requestToken = service.getRequestToken();
String authUrl = service.getAuthorizationUrl(requestToken);

At this point, it’s necessary to redirect the user to authUrl and to get the oauthVerifier provided by the page.

Hence, we use the oauthVerifier to get the accessToken:

OAuth1AccessToken accessToken = service.getAccessToken(requestToken,oauthVerifier);

Finally, we can create a request using OAuthRequest object and add the token to it with signRequest() method:

OAuthRequest request = new OAuthRequest(Verb.GET, 
    "https://api.twitter.com/1.1/account/verify_credentials.json");
service.signRequest(accessToken, request);

Response response = service.execute(request);

As a result of the execution of that request, we get a Response object.

5. OAuth 2.0 Flow

The OAuth 2.0 flow is not much different from OAuth 1.0. In order to explain these variations, we’re going to get an access token with Google APIs.

In the same way, we did in the OAuth 1.0 flow, we have to build the OAuthService and get the authUrl, but this time we’ll use an OAuth20Service instance:

OAuth20Service service = new ServiceBuilder("api_key")
  .apiSecret("api_secret")
  .scope("https://www.googleapis.com/auth/userinfo.email")
  .callback("http://localhost:8080/auth")
  .build(GoogleApi20.instance());

String authUrl = service.getAuthorizationUrl();

Note that, in this case, we need to provide the scope of the request and the callback to which we’ll be contacted at the end of the authorization flow.

Likewise, we have to redirect the user to authUrl and take the code parameter in the url of the callback:

OAuth2AccessToken accessToken = service.getAccessToken(code);

OAuthRequest request = new OAuthRequest(Verb.GET, "https://www.googleapis.com/oauth2/v1/userinfo?alt=json");
service.signRequest(accessToken, request);

Response response = service.execute(request);

In the end, in order to make the request, we get the accessToken with getAccessToken() method.

6. Custom APIs

We’ll probably have to work with an API that’s not supported by ScribeJava. Under those circumstances, the library allows us to implement our own APIs.

The only thing we need to do is to provide an implementation of DefaultApi10 or DefaultApi20 class.

Let’s imagine we have an OAuth 2.0 authorization server with password grant. In this case, we can implement the DefaultApi20 so that we can take an access token:

public class MyApi extends DefaultApi20 {

    public MyApi() {}

    private static class InstanceHolder {
        private static final MyApi INSTANCE = new MyApi();
    }

    public static MyApi instance() {
        return InstanceHolder.INSTANCE;
    }

    @Override
    public String getAccessTokenEndpoint() {
        return "http://localhost:8080/oauth/token";
    }

    @Override
    protected String getAuthorizationBaseUrl() {
        return null;
    }
}

Thus, we can get an access token in a similar fashion as we did before:

OAuth20Service service = new ServiceBuilder("baeldung_api_key")
  .apiSecret("baeldung_api_secret")
  .scope("read write")
  .build(MyApi.instance());

OAuth2AccessToken token = service.getAccessTokenPasswordGrant(username, password);

OAuthRequest request = new OAuthRequest(Verb.GET, "http://localhost:8080/me");
service.signRequest(token, request);
Response response = service.execute(request);

7. Conclusion

In this article, we took a look at the most useful classes that ScribeJava provides off the shelf.

We learned how to handle OAuth 1.0 and OAuth 2.0 flows with external APIs. We also learned how to configure the library in order to use our own APIs.

As usual, all code samples shown in this tutorial are available over on GitHub.