# JustAuth: one Java library for dozens of third-party OAuth logins

> JustAuth wraps GitHub, Gitee, WeChat, Alipay and dozens of other OAuth providers behind a single Java API, so you stop writing one login flow per platform. Here is what it does, how to wire it up, and where it stops being the right tool.

**justauth/JustAuth** — 🏆Gitee 最有价值开源项目 🚀:100: 小而全而美的第三方登录开源组件。目前已支持Github、Gitee、微博、钉钉、百度、Coding、腾讯云开发者平台、OSChina、支付宝、QQ、微信、淘宝、Google、Facebook、抖音、领英、小米、微软、今日头条、Teambition、StackOverflow、Pinterest、人人、华为、企业微信、酷家乐、Gitlab、美团、饿了么、推特、飞书、京东、阿里云、喜马拉雅、Amazon、Slack和 Line 等第三方平台的授权登录。 Login, so easy!

- Repository: https://github.com/justauth/JustAuth
- Website: https://www.justauth.cn
- Stars: 17,528 · Forks: 2,855
- Language: Java
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/justauth-justauth

## The problem JustAuth solves for JVM teams

Every third-party login is the same dance with different steps. You register an application, get a clientId and clientSecret, redirect the user to an authorization page, receive a code, exchange it for a token, and fetch the user profile. The endpoints, parameter names and response shapes differ per platform, and each vendor usually ships its own SDK with its own object model. A service that accepts GitHub, Gitee, WeChat and Alipay logins ends up carrying four integrations that do almost the same thing. JustAuth's answer is a single abstraction. The README describes it as a third-party authorization login utility library that lets you avoid the tedious third-party login SDKs, and the integration list covers GitHub, Gitee, Weibo, DingTalk, Baidu, Coding, Tencent Cloud Developer Platform, OSChina, Alipay, QQ, WeChat, Taobao, Google, Facebook, Douyin, LinkedIn, Xiaomi, Microsoft, Toutiao, Teambition, StackOverflow, Pinterest, Renren, Huawei, WeCom, Kujiale, GitLab, Meituan, Ele.me, Twitter, Feishu, JD, Alibaba Cloud, Ximalaya, Amazon, Slack and Line. The audience is Java backend developers, typically the people maintaining a login page for a product that has users on more than one platform. If your service only ever accepts one provider, this library is more indirection than you need.

## How the AuthRequest and AuthConfig mechanism works

The core objects are AuthConfig and AuthRequest. AuthConfig is built with a builder and holds clientId, clientSecret and redirectUri. AuthRequest is an interface, and each platform has a concrete implementation such as AuthGiteeRequest. You call authorize(state) to produce the authorization URL the user should be sent to, and login(callback) after the provider redirects back with a code and state. The callback can be passed as an AuthCallback object from version 1.8.0 onward. State handling is the part worth reading twice. JustAuth keeps a state cache, and the README states that the default validity is three minutes, after which an unused state is cleared. That default is an in-memory structure, so a multi-instance deployment behind a load balancer will break unless you supply a shared store. The project documents custom state caching for distributed cache components, which is the intended path for anything running on more than one node. HTTP is not baked in either. You choose hutool-http, Apache httpclient or okhttp, and the README says the project does not depend on one specific implementation. That keeps the dependency graph under your control, at the cost of one more decision at setup time. There is also a Builder form: AuthRequestBuilder.builder().source("github") with either a static AuthConfig or a lambda that resolves AuthConfig from the source string, which is how you load per-tenant credentials from a database. Custom providers go through extendSource(AuthExtendSource.values()) plus a source name, so an internal OAuth server can be adapted without forking the library.

## Installing JustAuth from Maven and running a first login

The README gives the dependency coordinates directly. The version placeholder is written as {latest-version}, so you pick the current stable release from Maven Central rather than copying a number out of the documentation. Add the library first, then exactly one HTTP implementation. The README lists hutool-http 5.7.7, httpclient 4.5.13 and okhttp 4.9.1 as the three options, and warns that if your project already pulls in an older version of one of them you should exclude it before adding the newer one.

```xml
<dependency>
    <groupId>me.zhyd.oauth</groupId>
    <artifactId>JustAuth</artifactId>
    <version>{latest-version}</version>
</dependency>
```

Then add one HTTP client. This is the hutool-http option:

```xml
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-http</artifactId>
    <version>5.7.7</version>
</dependency>
```

With dependencies in place, the README's plain example builds an AuthConfig, constructs an AuthGiteeRequest, generates the authorization page and then handles the callback. The same shape applies to every other platform, only the request class changes.

```java
AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder()
        .clientId("clientId")
        .clientSecret("clientSecret")
        .redirectUri("redirectUri")
        .build());
authRequest.authorize("state");
authRequest.login(callback);
```

What you should see: authorize returns the URL to redirect the browser to, and login returns the login result once the provider sends the user back with code and state. If you prefer not to hard-code the platform class, the builder form takes a source string and resolves the implementation, and a lambda variant of authConfig lets you look up credentials per source at runtime. The README also notes that Alipay returns auth_code rather than code, which matters if you write shared callback logic across providers.

## Where JustAuth is the wrong dependency

The three-minute state expiry is the sharpest edge. A user who opens the login page, gets distracted, and returns after four minutes will hit a state that has already been cleared, and the failure surfaces as a rejected callback rather than an obvious error. You can raise or replace that store through custom state caching, but the default is not a production configuration for a distributed service. Second, this is a library, not a service. It does not host a login page, does not store users, and does not manage sessions for you. If your team wants an identity provider rather than an OAuth client, JustAuth is a layer you would still have to build on. Third, the integration list is broad but finite. A provider that is not in it needs a custom AuthSource and a custom AuthRequest, which means reading that provider's OAuth documentation yourself; the library removes the boilerplate, not the work. Fourth, the release history shows an uneven cadence: v1.16.7 landed on 2024-12-14, v1.16.6 on 2023-12-03, and v1.16.5 on 2021-10-18. The last push to the repository was on 2026-04-16, so the project is not abandoned, but a team expecting frequent releases should check the changelog before planning around a fix. Finally, the README documents the snapshot repository for pre-release builds and states plainly that snapshot versions are not guaranteed stable and should not be used in production.

## JustAuth against a Spring Boot starter or a full identity platform

The most common alternative in this space is a Spring Boot starter that wraps the same kind of OAuth client work in auto-configuration. The difference is not the providers, it is who owns the wiring. A starter reads credentials from application properties, registers the callback endpoint and the request beans for you, and fits a project that already lives inside Spring Boot's configuration model. JustAuth stays a plain library: you construct AuthConfig, you keep the AuthRequest, and you decide where state lives. That is more code in your application and less magic in your framework, which is an advantage if you are not on Spring Boot or if you need per-tenant credentials resolved at runtime. A second alternative is a full identity and access management platform, which handles user storage, session issuance, token refresh and admin screens as a running service. Choosing that means operating another component and accepting its data model; choosing JustAuth means the user record stays in your database and the login flow stays in your code. The trade is operational surface against integration surface. Neither is wrong, but a team that wants a login page out of the box is shopping in the wrong category if it picks up JustAuth.

## Licence, maintenance and upgrade cost

JustAuth is MIT licensed, which is permissive and imposes no copyleft obligation on your application. The repository carries a LICENSE file at the top level, and the README links to it. For a commercial product, that is about as low-friction as a dependency licence gets, though the usual caveat applies: this is a description of the licence identifier, not legal advice, and your own counsel decides what your distribution requires. Upgrade cost is mostly about the HTTP layer. Because you pick hutool-http, httpclient or okhttp yourself, a CVE or a breaking change in that client is your problem to schedule, and the README's warning about excluding older transitive versions applies on every upgrade. The library itself has moved slowly across the 1.16.x line, so the practical risk is not churn but staleness: a provider that changes its OAuth endpoints between JustAuth releases leaves you waiting or writing a custom AuthSource. The CHANGELOGS.md file in the repository root is where release-level changes are recorded, and it is the first thing to read before bumping the version.

## Conclusion

Adopt JustAuth if you are building a JVM service that must accept logins from several Chinese and international platforms and you want one AuthRequest API instead of one SDK per provider. Do not adopt it if you need a hosted login service, a JavaScript front end, or a provider it has not integrated. Before writing code, confirm the latest stable version on Maven Central, verify which AuthRequest implementation exists for each platform you need, and decide where the OAuth state will live, because the default in-memory store expires entries after three minutes.

## FAQ

### How do I add JustAuth to a Maven project?

Add the me.zhyd.oauth:JustAuth dependency with the current stable version, then add exactly one HTTP client dependency from hutool-http, httpclient or okhttp. If your project already brings in an older version of that HTTP client, exclude it first and then add the newer version.

### How long does JustAuth keep the OAuth state value?

The README states that the default state cache holds a state for three minutes and clears it if it is not used within that window. For anything beyond a single instance, the project documents custom state caching against a distributed cache component.

### Can I use JustAuth with a provider it does not support yet?

Yes. The README shows a builder form that calls extendSource(AuthExtendSource.values()) and then selects the source by name, which is the documented path for adapting a custom OAuth service. You still implement the provider-specific request class yourself.

## Sources

- [justauth/JustAuth on GitHub](https://github.com/justauth/JustAuth)
- [License: MIT](https://github.com/justauth/JustAuth/blob/master/LICENSE)
- [Project website](https://www.justauth.cn)
- [README](https://github.com/justauth/JustAuth/blob/master/README.md)
- [Releases](https://github.com/justauth/JustAuth/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/justauth-justauth