JustAuth Documentation

File: README.md Copy Chapter

QQ 群：230017570
微信群：justauth （备注justauth或者ja）
帮助文档：www.justauth.cn

什么是 JustAuth？ Copy Chapter

JustAuth，如你所见，它仅仅是一个第三方授权登录的工具类库，它可以让我们脱离繁琐的第三方登录 SDK，让登录变得So easy!

JustAuth 集成了诸如：Github、Gitee、支付宝、新浪微博、微信、Google、Facebook、Twitter、StackOverflow等国内外数十家第三方平台。更多请参考已集成的平台

有哪些特点？ Copy Chapter

1. 全：已集成十多家第三方平台（国内外常用的基本都已包含），仍然还在持续扩展中（开发计划）！
2. 简：API就是奔着最简单去设计的（见后面快速开始），尽量让您用起来没有障碍感！

有哪些功能？ Copy Chapter

• 集成国内外数十家第三方平台，实现快速接入。参考文档
• 自定义 State 缓存，支持各种分布式缓存组件。参考文档
• 自定义 OAuth 平台，更容易适配自有的 OAuth 服务。参考文档
• 自定义 Http 实现，选择权完全交给开发者，不会单独依赖某一具体实现。参考文档
• 自定义 Scope，支持更完善的授权体系。参考文档
• 更多...参考文档

快速开始 Copy Chapter

引入依赖 Copy Section

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

latest-version 可选：

• 稳定版：
• 快照版：

注意：快照版本是功能的尝鲜，并不保证稳定性。请勿在生产环境中使用。

如何引入快照版本

JustAuth 的快照版本托管在 ossrh 上，所以要指定下载地址。

xml Copy

<repositories>
    <repository>
        ossrh-snapshot
        https://oss.sonatype.org/content/repositories/snapshots
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

如果你想第一时间获取 JustAuth 的最新快照，可以添加下列代码，每次构建时都检查是否有最新的快照（默认每天检查）。

diff Copy

https://oss.sonatype.org/content/repositories/snapshots
        <snapshots>
+           always
            <enabled>true</enabled>
        </snapshots>

如下任选一种 HTTP 工具 依赖，项目内如果已有，请忽略。另外需要特别注意，如果项目中已经引入了低版本的依赖，请先排除低版本依赖后，再引入高版本或者最新版本的依赖

• hutool-http

  xml Copy

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

• httpclient

  xml Copy

  <dependency>
      <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>4.5.13</version>
  </dependency>

• okhttp

  xml Copy

  <dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.9.1</version>
  </dependency>

调用api Copy Section

普通方式

// 创建授权request
AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder()
        .clientId("clientId")
        .clientSecret("clientSecret")
        .redirectUri("redirectUri")
        .build());
// 生成授权页面
authRequest.authorize("state");
// 授权登录后会返回code（auth_code（仅限支付宝））、state，1.8.0版本后，可以用AuthCallback类作为回调接口的参数
// 注：JustAuth默认保存state的时效为3分钟，3分钟内未使用则会自动清除过期的state
authRequest.login(callback);

Builder 方式一

静态配置 AuthConfig

AuthRequest authRequest = AuthRequestBuilder.builder()
    .source("github")
    .authConfig(AuthConfig.builder()
        .clientId("clientId")
        .clientSecret("clientSecret")
        .redirectUri("redirectUri")
        .build())
    .build();
// 生成授权页面
  authRequest.authorize("state");
// 授权登录后会返回code（auth_code（仅限支付宝））、state，1.8.0版本后，可以用AuthCallback类作为回调接口的参数
// 注：JustAuth默认保存state的时效为3分钟，3分钟内未使用则会自动清除过期的state
  authRequest.login(callback);

Builder 方式二

动态获取并配置 AuthConfig

AuthRequest authRequest = AuthRequestBuilder.builder()
    .source("gitee")
    .authConfig((source) -> {
        // 通过 source 动态获取 AuthConfig
        // 此处可以灵活的从 sql 中取配置也可以从配置文件中取配置
        return AuthConfig.builder()
            .clientId("clientId")
            .clientSecret("clientSecret")
            .redirectUri("redirectUri")
            .build();
    })
    .build();
Assert.assertTrue(authRequest instanceof AuthGiteeRequest);
System.out.println(authRequest.authorize(AuthStateUtils.createState()));

Builder 方式支持自定义的平台

AuthRequest authRequest = AuthRequestBuilder.builder()
    // 关键点：将自定义实现的 AuthSource 配置上
    .extendSource(AuthExtendSource.values())
    // source 对应 AuthExtendSource 中的枚举 name
    .source("other")
    // ... 其他内容不变，参考上面的示例
    .build();

赞助和支持 Copy Chapter

感谢以下赞助商的支持：

我要赞助

JustAuth 的用户 Copy Chapter

有很多公司、组织和个人把 JustAuth 用于学习、研究、生产环境和商业产品中，包括（但不限于）：

怎么没有我？登记

开源推荐 Copy Chapter

• JAP 开源的登录认证中间件: https://gitee.com/fujieid/jap
• spring-boot-demo 深度学习并实战 spring boot 的项目: https://github.com/xkcoding/spring-boot-demo
• mica SpringBoot 微服务高效开发工具集: https://github.com/lets-mica/mica
• sureness 面向restful api的高性能认证鉴权框架：sureness

更多推荐，请参考：JustAuth - 开源推荐

鸣谢 Copy Chapter

• 感谢 JetBrains 提供的免费开源 License：

其他 Copy Chapter

• CONTRIBUTORS
• CHANGELOGS
• PLAN

贡献者列表 Copy Chapter

Stars 趋势 Copy Chapter

Gitee Copy Section

Github Copy Section

ProductHunt Copy Section

File: README.en-US.md Copy Chapter

JustAuth, as you see, It is just a Java library of third-party authorized login, It's smaller and easier to use. JustAuth is the best third-party login tool written in JAVA.

Source Code：gitee | github
Docs：Reference Doc

Features Copy Chapter

1. Multiple platform: Has integrated more than a dozen third-party platforms.(plan)
2. Minimalist: The minimalist design is very simple to use.

Quick start Copy Chapter

Add maven dependency Copy Section

• Add JustAuth dependency

These artifacts are available from Maven Central:

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

latest-version ：

• CURRENT:
• SNAPSHOT:

• Add http dependency（Only need one）

If there is already in the project, please ignore it. In addition, you need to pay special attention. If the low version of the dependency has been introduced in the project, please exclude the low version of the dependency first, and then introduce the high version or the latest version of the dependency

• hutool-http

  xml Copy

  <dependency>
      <groupId>cn.hutool</groupId>
      <artifactId>hutool-http</artifactId>
      <version>5.2.5</version>
  </dependency>

• httpclient

  xml Copy

  <dependency>
      <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>4.5.12</version>
  </dependency>

• okhttp

  xml Copy

  <dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.4.1</version>
  </dependency>

Using JustAuth API Copy Section

Simple

// Create authorization request
AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder()
        .clientId("clientId")
        .clientSecret("clientSecret")
        .redirectUri("redirectUri")
        .build());
// Generate authorization page url
authRequest.authorize("state");
// Get token and userinfo
authRequest.login(callback);

Builder 1. Use unchanging `AuthConfig`

// Create authorization request
AuthRequest authRequest = AuthRequestBuilder.builder()
    .source("github")
    .authConfig(AuthConfig.builder()
        .clientId("clientId")
        .clientSecret("clientSecret")
        .redirectUri("redirectUri")
        .build())
    .build();

Builder 2. Use dynamic `AuthConfig`

// Create authorization request
AuthRequest authRequest = AuthRequestBuilder.builder()
    .source("gitee")
    .authConfig((source) -> {
        // Use source to dynamically get AuthConfig
        // Here you can flexibly take the configuration from sql or take the configuration from the configuration file
        return AuthConfig.builder()
            .clientId("clientId")
            .clientSecret("clientSecret")
            .redirectUri("redirectUri")
            .build();
    })
    .build();

Builder 3. Support custom platform

AuthRequest authRequest = AuthRequestBuilder.builder()
    // Key point: configure the custom implementation of AuthSource
    .extendSource(AuthExtendSource.values())
    // Enum name in AuthExtendSource
    .source("other")
    // ... Do other things
    .build();

Contributions Copy Chapter

1. Fork this project to your repository
2. Clone the project after fork.
3. Modify the code (either to fix issue, or to add new features)
4. Commit and push code to a remote repository
5. Create a new PR (pull request), and select dev branch
6. Waiting for author to merge

I look forward to your joining us.

Contributors Copy Chapter

contributors

Change Logs Copy Chapter

CHANGELOGS

Recommend Copy Chapter

• spring-boot-demo In-depth study and actual combat of spring boot projects: https://github.com/xkcoding/spring-boot-demo
• mica Efficient Development of scaffolding by Spring Cloud: https://github.com/lets-mica/mica
• pig Cosmic strongest Micro Services Certified authorized scaffolding (essential for Architects): https://gitee.com/log4j/pig
• SpringBlade Complete online solution (necessary for enterprise development): https://gitee.com/smallc/SpringBlade

References Copy Chapter

• The OAuth 2.0 Authorization Framework
• OAuth 2.0