ScribeJava: a plain OAuth client for Java, without the framework

What ScribeJava actually takes off your plate

OAuth is a set of HTTP exchanges with fiddly details: a redirect URL that has to match exactly, a state parameter, a code exchanged for a token, a refresh call when the token expires. Writing that by hand for one provider is an afternoon. Writing it for five is a week, and the fifth one always has a quirk. ScribeJava packages those exchanges behind a small API so the calling code looks the same whether the provider speaks OAuth 1.0a or OAuth 2.0.

The library is aimed at two groups. The first is backend Java services that need to talk to a third-party API on behalf of a user, where the service is the OAuth client and the provider is someone else's authorization server. The second is Android apps, which is why the README points out Java 7 compatibility: the library can run in old environments and in Android apps, while compiling from source needs Java 9 or newer. ScribeJava is not an authorization server. It does not issue tokens, store user records, or render a login page. It is the client half only, and anyone expecting the other half will be disappointed.

The ServiceBuilder, the API class and the HTTP client layer

The core object is an OAuthService, built by a ServiceBuilder that takes the client id, then the client secret, then an API class such as LinkedInApi20.instance(). That API class is where the provider-specific URLs and parameter names live. The repository splits the code into scribejava-core, which holds the protocol logic and the OAuthService interface, and scribejava-apis, which holds the per-provider classes and the runnable examples. Adding a provider that is not shipped means writing one more class in the shape of the existing ones, not changing the core.

HTTP is deliberately not baked in. The README lists several client modules: scribejava-httpclient-ning for the ning async client 1.9.x, scribejava-httpclient-ahc for Async Http Client 2.x, scribejava-httpclient-okhttp, scribejava-httpclient-apache for Apache HttpComponents, and scribejava-httpclient-armeria, which the README notes requires Java 8 or newer. There is also a path for any externally created HTTP client. The plain synchronous default lives in the core, and the async modules are opt-in additions. That separation is the main architectural decision in the project: the protocol layer never assumes a particular connection pool or thread model.

Installing ScribeJava and running a first authorization code flow

ScribeJava is published to Maven Central under the group com.github.scribejava, so a Maven build adds the core artifact and the API artifact. The README shows the configuration as a single builder chain, reproduced here with the LinkedIn API class used in the documentation.

OAuthService service = new ServiceBuilder(YOUR_CLIENT_ID)
                                  .apiSecret(YOUR_CLIENT_SECRET)
                                  .build(LinkedInApi20.instance());

After that call the service object is ready. To start the flow you ask it for an authorization URL, send the user there, and receive a code on your redirect endpoint. The README points to Google20Example.java under scribejava-apis/src/test/java/com/github/scribejava/apis/examples as the common usage reference, and that file also shows the refresh call. The same directory holds Google20WithPKCEExample.java for RFC 7636, Google20RevokeExample.java for RFC 7009 token revocation, and Google20DeviceAuthorizationGrantExample.java for RFC 8628, so the fastest way to learn a flow is to read the example for it rather than the README. If your build already uses OkHttp, the corresponding module is scribejava-httpclient-okhttp and the README points at GitHubAsyncOkHttpExample.java; the async modules are added to the pom alongside the core, not instead of it.

Where ScribeJava stops being the right tool

The library is a client, and that boundary causes most of the friction people hit. It will not validate an ID token for you, because OpenID Connect is a different specification from the OAuth RFCs the README lists. If your product needs to log users in with a provider and trust the resulting identity assertion, ScribeJava gets you the token but not the verification step, and you will be writing that yourself or adding another library.

The second limit is provider drift. The built-in API classes encode each provider's endpoints and parameter names at the time they were written. When a provider changes a token endpoint or adds a required parameter, the fix has to land in scribejava-apis and then in a release. The releases shown in the repository are scribejava-8.3.3 from 2023-01-25, scribejava-8.3.2 from 2022-10-10 and scribejava-8.3.1 from 2021-05-11, so the tagged cadence is slow. The last push to the default branch was on 2026-05-18, which means the repository is not dormant, but a consumer tracking only releases is working with a version that is years old. If your provider is not in the list of fifty-odd built-in APIs, or if it has moved on since its class was written, budget time for a custom API class or a fork.

Finally, the Java 7 target is a real constraint in both directions. It buys you Android and legacy runtime support, and it costs you modern language features in the core. Teams on Java 17 or 21 who expect records, sealed types or virtual threads in the API surface will not find them.

ScribeJava against Spring Security OAuth and plain HTTP calls

The closest thing to a direct alternative in the Java world is Spring Security's OAuth client support. The difference is scope. Spring Security integrates the OAuth client into a filter chain, so the authorization redirect, the callback handling and the token storage are wired into the application's security configuration and its HTTP session. ScribeJava has no filter chain and no session concept. You call the service, you get URLs and tokens back, and you decide where to keep them. That makes ScribeJava lighter in a service that already has its own request pipeline, and it makes it more work in a servlet application that expects the framework to intercept the callback for it.

The other option is to skip a library and call the token endpoint with whatever HTTP client you already use. That is defensible for a single provider and a single grant, especially the client credentials grant, which is one POST. It becomes expensive once you need PKCE, refresh handling, token revocation and a second provider, because at that point you are reimplementing what scribejava-core already contains, including the OAuth 1.0a signature base string, which is the least pleasant part of the older protocol to get right by hand.

Maintenance, upgrades and the MIT licence

Upgrading ScribeJava is a Maven version bump on the artifacts you use, and the changelog file at the repository root is where the project records what changed between them. The practical risk is not the upgrade itself but the gap between the last tagged release and the state of the default branch: if you need a fix that landed after scribejava-8.3.3, you are either building from source, which the README says requires Java 9 or newer, or waiting. Pin the version explicitly in your pom rather than tracking a range, so an upgrade is a deliberate act you can tie to a changelog entry.

The licence is MIT, stated in LICENSE.txt at the repository root. MIT is permissive: it allows use in closed-source products and modification, and it requires that the copyright notice and permission notice be kept with the distribution. It does not grant trademark rights and it includes no patent grant, which matters to some legal teams more than others. This is a description of the licence text, not legal advice; if your organisation has a policy on permissive licences, route the LICENSE.txt file through it.

Editorial conclusion

Adopt ScribeJava if you have a Java 7 or Android codebase that needs OAuth 1.0a or 2.0 flows and you want the protocol handled by a library rather than by a full identity framework. Do not adopt it if you need an authorization server, an OpenID Connect stack, or a dependency with recent tagged releases, since the newest release shown in the repository is scribejava-8.3.3 from 2023-01-25. Before committing, verify that the provider API you need has an example under scribejava-apis/src/test/java/com/github/scribejava/apis/examples, confirm the token endpoint you plan to call is covered by the grant you picked, and check which HTTP client module your build already pulls in so you do not add two.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. scribejava/scribejava on GitHub