Guide · Open source
How to use JustAuth: Java third-party login setup and examples
Updated · written with AI from the project's own documentation and checked against our catalogue data
JustAuth is an open-source Java library for adding third-party login, such as "log in with GitHub" or WeChat, to an application without writing each provider's login SDK yourself. This guide walks through adding the Maven dependency, choosing an HTTP client, and creating an authorization request in three styles. By the end you will know the basic flow the library expects and where to look next for provider-specific settings.
JustAuthjustauth/JustAuth · ★ 17.5k · MIT Install options & downloads Quick start
- 1Confirm Java and build tool. Make sure your project uses JDK 1.8 or newer and a build tool such as Maven.
- 2Add the JustAuth dependency. Copy the me.zhyd.oauth JustAuth dependency into pom.xml and replace {latest-version} with a release number.
- 3Add one HTTP client. Add hutool-http, httpclient or okhttp unless your project already has a suitable client.
- 4Register your app with the provider. Obtain a client ID, client secret and redirect URI from the platform you want to support. The README uses placeholder values, so use your own.
- 5Create the authorization request. Build an AuthRequest with AuthConfig, then call authorize with a state value to get the login page URL.
- 6Handle the callback. After the user returns, call login with the callback data. Use a state within 3 minutes of creating it.
What JustAuth does and who it is for
JustAuth is a third-party authorization login utility library. The README says it lets you avoid working directly with each platform's login SDK. It supports a long list of platforms, including GitHub, Gitee, Alipay, WeChat, Google, Facebook, Microsoft and DingTalk.
The project is written in Java and its README examples are Java only. Its documentation is mainly in Chinese.
- Good fit: Java developers adding social or third-party login to a web backend.
- Good fit: teams that need several Chinese platforms such as WeChat, Alipay, Gitee or DingTalk.
- Not a fit: non-Java projects, or teams that need only one provider and prefer that provider's official SDK.
Check the prerequisites before you start
The README badge shows JDK 1.8 or newer. You also need Maven or another build tool that can fetch the me.zhyd.oauth JustAuth dependency.
JustAuth does not bundle an HTTP client. Pick one of the supported options and add it to your project unless it is already there. The README lists hutool-http, httpclient and okhttp.
- Java (JDK 1.8+)
- Maven or another build tool
- One HTTP client: hutool-http, httpclient or okhttp
Add JustAuth and an HTTP client to your project
Copy the dependency into your pom.xml. Replace {latest-version} with a release number from the project's release badge or Maven Central. The README does not give a fixed version, so do not reuse a version number from older examples without checking.
Then add exactly one HTTP client dependency. If your project already includes a suitable client, skip this step. If a lower-version dependency is already present, the README advises excluding it before adding a higher or the latest version.
<dependency>
<groupId>me.zhyd.oauth</groupId>
<artifactId>JustAuth</artifactId>
<version>{latest-version}</version>
</dependency>Create an authorization request
The simplest style creates a request object for a specific provider, such as AuthGiteeRequest, passing an AuthConfig with your client ID, client secret and redirect URI. You then call authorize with a state value to get the authorization page URL, and call login with a callback after the user returns.
The README notes that JustAuth keeps state for 3 minutes by default. A state that is not used within that time is cleared automatically. From version 1.8.0 onward, the callback can be an AuthCallback object.
- authorize(state) generates the authorization page.
- login(callback) handles the return from the provider.
- State expires after 3 minutes by default.
AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder()
.clientId("clientId")
.clientSecret("clientSecret")
.redirectUri("redirectUri")
.build());
authRequest.authorize("state");
authRequest.login(callback);Use the builder styles to pick a provider
The builder approach selects the provider by a source name, such as github or gitee. The README shows two forms: a static AuthConfig, and a dynamic one where a function receives the source and returns a config. The dynamic form can read settings from a database or a configuration file.
Use AuthStateUtils.createState() to generate a state value when you do not want to write your own.
- Static config: set AuthConfig directly on the builder.
- Dynamic config: pass a function that returns AuthConfig for the given source.
AuthRequest authRequest = AuthRequestBuilder.builder()
.source("gitee")
.authConfig((source) -> {
return AuthConfig.builder()
.clientId("clientId")
.clientSecret("clientSecret")
.redirectUri("redirectUri")
.build();
})
.build();
System.out.println(authRequest.authorize(AuthStateUtils.createState()));Add a custom provider or your own HTTP and state handling
If your provider is not built in, the README describes a custom OAuth platform feature. You define your own AuthSource and register it with extendSource, then refer to it by its enum name in the source field. The README example uses the value other.
The library also supports a custom State cache for distributed caches, a custom HTTP implementation so you are not tied to one client, and custom scopes. Check the linked feature pages on the project website for details, since the README only links to them.
- Custom provider: implement AuthSource and register it via extendSource.
- Custom state cache: use a distributed cache component.
- Custom HTTP: choose your own HTTP implementation.
- Custom scope: adjust the requested permissions.
AuthRequest authRequest = AuthRequestBuilder.builder()
.extendSource(AuthExtendSource.values())
.source("other")
.build();What people use it for
- Letting users sign in to a web app with GitHub or Gitee accounts.
- Offering WeChat or Alipay login in a Java backend serving Chinese users.
- Adding a private or in-house OAuth service through the custom provider mechanism.
- Replacing a set of per-provider login SDKs with one API.
Frequently asked questions
Is JustAuth free to use?
The project is released under the MIT licence, according to the README. MIT allows use, including in commercial products, subject to the licence terms. Read the LICENSE file in the repository for the exact wording.
What do I need to install JustAuth?
You need Java with JDK 1.8 or newer, a build tool such as Maven, and one HTTP client library such as hutool-http, httpclient or okhttp. Then add the me.zhyd.oauth JustAuth dependency to your project.
Which platforms does JustAuth support?
The README lists dozens of platforms, including GitHub, Gitee, WeChat, Alipay, QQ, Google, Facebook, DingTalk, Microsoft, Slack and Line. The full current list is on the project website at justauth.cn.
Can I use JustAuth outside Java?
The library is written for Java and the README only shows Java examples. If your stack is not Java, this library is not a direct fit, and you should look at the provider's own SDK or a library for your language.
How do I add a provider that JustAuth does not support?
Use the custom OAuth platform feature. The README describes implementing your own AuthSource, registering it with extendSource, and referring to it by its enum name in the source field.
Why does my login state stop working after a few minutes?
The README says JustAuth keeps state for 3 minutes by default and clears unused states automatically. Use the state within that window, or use the custom state cache feature if your setup needs a different storage approach.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
JustAuth suits Java developers who want one API for many third-party login providers, especially Chinese platforms like WeChat, Alipay and Gitee. Skip it if your project is not in Java, if you only need one provider and prefer its official SDK, or if you need English-language documentation.
Install options & downloads