README.md 10.1 KB
Newer Older
智布道's avatar
智布道 已提交
1
<p align="center">
2
	<a href="https://justauth.wiki"><img src="https://gitee.com/yadong.zhang/static/raw/master/JustAuth/Justauth.png" width="400"></a>
智布道's avatar
智布道 已提交
3 4 5 6 7
</p>
<p align="center">
	<strong>Login, so easy.</strong>
</p>
<p align="center">
智布道's avatar
智布道 已提交
8
	<a target="_blank" href="https://search.maven.org/search?q=JustAuth">
9
		<img src="https://img.shields.io/github/v/release/justauth/JustAuth?style=flat-square" ></img>
智布道's avatar
智布道 已提交
10
	</a>
智布道's avatar
智布道 已提交
11 12 13
	<a target="_blank" href="https://oss.sonatype.org/content/repositories/snapshots/me/zhyd/oauth/JustAuth/">
		<img src="https://img.shields.io/nexus/s/https/oss.sonatype.org/me.zhyd.oauth/JustAuth.svg?style=flat-square" ></img>
	</a>
智布道's avatar
智布道 已提交
14
	<a target="_blank" href="https://gitee.com/yadong.zhang/JustAuth/blob/master/LICENSE">
15
		<img src="https://img.shields.io/apm/l/vim-mode.svg?color=yellow" ></img>
智布道's avatar
智布道 已提交
16 17 18 19
	</a>
	<a target="_blank" href="https://www.oracle.com/technetwork/java/javase/downloads/index.html">
		<img src="https://img.shields.io/badge/JDK-1.8+-green.svg" ></img>
	</a>
20
	<a target="_blank" href="https://justauth.wiki" title="参考文档">
智布道's avatar
智布道 已提交
21
		<img src="https://img.shields.io/badge/Docs-latest-blueviolet.svg" ></img>
智布道's avatar
智布道 已提交
22
	</a>
智布道's avatar
智布道 已提交
23 24
	<a href="https://codecov.io/gh/justauth/JustAuth">
		<img src="https://codecov.io/gh/justauth/JustAuth/branch/master/graph/badge.svg?token=zYiAqd9aFz" />
智布道's avatar
智布道 已提交
25
	</a>
智布道's avatar
智布道 已提交
26
	<a href='https://gitee.com/yadong.zhang/JustAuth/stargazers'>
智布道's avatar
智布道 已提交
27
	  <img src='https://gitee.com/yadong.zhang/JustAuth/badge/star.svg?theme=gvp' alt='star'></img>
智布道's avatar
智布道 已提交
28 29 30 31
	</a>
	<a target="_blank" href='https://github.com/zhangyd-c/JustAuth'>
		<img src="https://img.shields.io/github/stars/zhangyd-c/JustAuth.svg?style=social" alt="github star"></img>
	</a>
智布道's avatar
智布道 已提交
32 33
</p>

智布道's avatar
智布道 已提交
34 35 36 37
-------------------------------------------------------------------------------
<p align="center">
<img src='./docs/media/75a3c076.png' alt='star'></img>
</p>
智布道's avatar
智布道 已提交
38

智布道's avatar
智布道 已提交
39
-------------------------------------------------------------------------------
智布道's avatar
智布道 已提交
40

41 42 43
QQ 群:230017570    
微信群:justauth (备注`justauth`或者`ja`
帮助文档:[justauth.wiki](https://justauth.wiki)    
智布道's avatar
智布道 已提交
44

45
## 什么是 JustAuth?
智布道's avatar
智布道 已提交
46

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

智布道's avatar
智布道 已提交
49
JustAuth 集成了诸如:Github、Gitee、支付宝、新浪微博、微信、Google、Facebook、Twitter、StackOverflow等国内外数十家第三方平台。更多请参考<a href="https://justauth.wiki" target="_blank">已集成的平台</a>
50

51
## 有哪些特点?
52

53
1. **全**:已集成十多家第三方平台(国内外常用的基本都已包含),仍然还在持续扩展中([开发计划](https://gitee.com/yadong.zhang/JustAuth/issues/IUGRK))!
54 55
2. **简**:API就是奔着最简单去设计的(见后面`快速开始`),尽量让您用起来没有障碍感!

56 57
## 有哪些功能?

智布道's avatar
智布道 已提交
58 59 60 61 62
- 集成国内外数十家第三方平台,实现快速接入。<a href="https://justauth.wiki/quickstart/how-to-use.html" target="_blank">参考文档</a>
- 自定义 State 缓存,支持各种分布式缓存组件。<a href="https://justauth.wiki/features/customize-the-state-cache.html" target="_blank">参考文档</a>
- 自定义 OAuth 平台,更容易适配自有的 OAuth 服务。<a href="https://justauth.wiki/features/customize-the-oauth.html" target="_blank">参考文档</a>
- 自定义 Http 实现,选择权完全交给开发者,不会单独依赖某一具体实现。<a href="https://justauth.wiki/quickstart/how-to-use.html#%E4%BD%BF%E7%94%A8%E6%96%B9%E5%BC%8F" target="_blank">参考文档</a>
- 自定义 Scope,支持更完善的授权体系。<a href="https://justauth.wiki/features/customize-scopes.html" target="_blank">参考文档</a>
63 64
- 更多...<a href="https://justauth.wiki" target="_blank">参考文档</a>

智布道's avatar
智布道 已提交
65
## 快速开始
66

67
### 引入依赖
68 69 70 71
```xml
<dependency>
    <groupId>me.zhyd.oauth</groupId>
    <artifactId>JustAuth</artifactId>
智布道's avatar
智布道 已提交
72
    <version>{latest-version}</version>
73 74 75
</dependency>
```

智布道's avatar
智布道 已提交
76 77 78
> **latest-version** 可选:
> - 稳定版:![](https://img.shields.io/github/v/release/justauth/JustAuth?style=flat-square) 
> - 快照版:![](https://img.shields.io/nexus/s/https/oss.sonatype.org/me.zhyd.oauth/JustAuth.svg?style=flat-square)
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
> > 注意:快照版本是功能的尝鲜,并不保证稳定性。请勿在生产环境中使用。
>
> <details>
>   <summary>如何引入快照版本</summary>
>
> JustAuth 的快照版本托管在 ossrh 上,所以要指定下载地址。
> 
> ```xml
> <repositories>
>     <repository>
>         <id>ossrh-snapshot</id>
>         <url>https://oss.sonatype.org/content/repositories/snapshots</url>
>         <snapshots>
>             <enabled>true</enabled>
>         </snapshots>
>     </repository>
> </repositories>
> ```
> 
> 如果你想第一时间获取 JustAuth 的最新快照,可以添加下列代码,每次构建时都检查是否有最新的快照(默认每天检查)。
> 
> ```diff
>        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
>         <snapshots>
> +           <updatePolicy>always</updatePolicy>
>             <enabled>true</enabled>
>         </snapshots>
> ```
> 
> </details>
智布道's avatar
智布道 已提交
109 110

如下**任选一种** HTTP 工具 依赖,_项目内如果已有,请忽略。另外需要特别注意,如果项目中已经引入了低版本的依赖,请先排除低版本依赖后,再引入高版本或者最新版本的依赖_
智布道's avatar
智布道 已提交
111 112 113 114 115 116 117

- hutool-http

  ```xml
  <dependency>
      <groupId>cn.hutool</groupId>
      <artifactId>hutool-http</artifactId>
118
      <version>5.7.7</version>
智布道's avatar
智布道 已提交
119 120 121 122 123 124 125 126 127
  </dependency>
  ```

- httpclient

  ```xml
  <dependency>
  	<groupId>org.apache.httpcomponents</groupId>
    	<artifactId>httpclient</artifactId>
128
    	<version>4.5.13</version>
智布道's avatar
智布道 已提交
129 130 131 132 133 134 135 136 137
  </dependency>
  ```

- okhttp

  ```xml
  <dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
138
    <version>4.9.1</version>
智布道's avatar
智布道 已提交
139 140
  </dependency>
  ```
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
  
### 调用api

#### 普通方式

```java
// 创建授权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`

```java
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 方式二

智布道's avatar
智布道 已提交
182
动态获取并配置 `AuthConfig`
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206

```java
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 方式支持自定义的平台

```java
AuthRequest authRequest = AuthRequestBuilder.builder()
    // 关键点:将自定义实现的 AuthSource 配置上
    .extendSource(AuthExtendSource.values())
智布道's avatar
智布道 已提交
207 208
    // source 对应 AuthExtendSource 中的枚举 name
    .source("other")
209 210 211
    // ... 其他内容不变,参考上面的示例
    .build();
```
智布道's avatar
智布道 已提交
212

智布道's avatar
智布道 已提交
213 214 215 216
## 赞助和支持

感谢以下赞助商的支持:

智布道's avatar
智布道 已提交
217
[我要赞助](https://justauth.wiki/sponsor.html)
智布道's avatar
智布道 已提交
218

219 220 221
## JustAuth 的用户
有很多公司、组织和个人把 JustAuth 用于学习、研究、生产环境和商业产品中,包括(但不限于):
![](docs/users/4ca0177c.png)
智布道's avatar
智布道 已提交
222 223


智布道's avatar
智布道 已提交
224
怎么没有我?[登记](https://gitee.com/yadong.zhang/JustAuth/issues/IZ2T7)
智布道's avatar
智布道 已提交
225

智布道's avatar
智布道 已提交
226
## 开源推荐
智布道's avatar
智布道 已提交
227

智布道's avatar
智布道 已提交
228
- `JAP` 开源的登录认证中间件: [https://gitee.com/fujieid/jap](https://gitee.com/fujieid/jap)
智布道's avatar
智布道 已提交
229 230
- `spring-boot-demo` 深度学习并实战 spring boot 的项目: [https://github.com/xkcoding/spring-boot-demo](https://github.com/xkcoding/spring-boot-demo)
- `mica` SpringBoot 微服务高效开发工具集: [https://github.com/lets-mica/mica](https://github.com/lets-mica/mica)
智布道's avatar
智布道 已提交
231
- `sureness` 面向restful api的高性能认证鉴权框架:[sureness](https://github.com/usthe/sureness)
智布道's avatar
智布道 已提交
232
  
智布道's avatar
智布道 已提交
233
更多推荐,请参考:[JustAuth - 开源推荐](https://justauth.wiki)
智布道's avatar
智布道 已提交
234

智布道's avatar
智布道 已提交
235
## 鸣谢
智布道's avatar
智布道 已提交
236

237
- 感谢 JetBrains 提供的免费开源 License:
智布道's avatar
智布道 已提交
238 239

<p>
240
<img src="https://images.gitee.com/uploads/images/2020/0406/220236_f5275c90_5531506.png" alt="图片引用自lets-mica" style="float:left;">
智布道's avatar
智布道 已提交
241
</p>
智布道's avatar
智布道 已提交
242

243
## 其他
智布道's avatar
智布道 已提交
244

智布道's avatar
智布道 已提交
245 246
- [CONTRIBUTORS](https://justauth.wiki/contributors.html)
- [CHANGELOGS](https://justauth.wiki/update.html)
智布道's avatar
智布道 已提交
247 248
- [PLAN](https://gitee.com/yadong.zhang/JustAuth/issues/IUGRK)

智布道's avatar
智布道 已提交
249
## 贡献者列表
智布道's avatar
智布道 已提交
250 251 252

[![contributors](https://whnb.wang/contributors/yadong.zhang/JustAuth)](https://whnb.wang)

智布道's avatar
智布道 已提交
253 254 255 256 257 258 259 260 261 262
## Stars 趋势

### Gitee

[![Stargazers over time](https://whnb.wang/img/yadong.zhang/JustAuth?e=604800)](https://whnb.wang/yadong.zhang/JustAuth?e=604800)

### Github

[![Stargazers over time](https://starchart.cc/justauth/JustAuth.svg)](https://starchart.cc/justauth/JustAuth)

智布道's avatar
智布道 已提交
263 264 265
### ProductHunt

<a href="https://www.producthunt.com/posts/justauth?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-justauth" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=196886&theme=dark" alt="JustAuth - Login, so easy! | Product Hunt Embed" style="width: 250px; height: 54px;" width="250px" height="54px" /></a>