From 16f77ec77083520b6816c7655bb003dff1dd0729 Mon Sep 17 00:00:00 2001 From: "yadong.zhang" Date: Fri, 23 Aug 2019 20:05:26 +0800 Subject: [PATCH] =?UTF-8?q?:memo:=20=E7=BC=96=E5=86=99=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.en-US.md | 167 ++++++++++++++++++ README.md | 3 +- docs/README.md | 4 + docs/_sidebar.md | 9 +- docs/explain.md | 29 +++ docs/how-to-use.md | 34 +++- docs/index.html | 23 +++ .../java/me/zhyd/oauth/config/AuthConfig.java | 4 +- 8 files changed, 264 insertions(+), 9 deletions(-) create mode 100644 README.en-US.md create mode 100644 docs/explain.md diff --git a/README.en-US.md b/README.en-US.md new file mode 100644 index 0000000..cdb2936 --- /dev/null +++ b/README.en-US.md @@ -0,0 +1,167 @@ +

+ +

+

+ Login, so easy. +

+

+ + + + + + + + + + + + + + + + + + + + star + + + github star + +

+ +
+ + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + +
+
+ +------------------------------------------------------------------------------- + + + +`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](https://gitee.com/yadong.zhang/JustAuth) | [github](https://github.com/zhangyd-c/JustAuth) +Docs：[Reference Doc](https://docs.justauth.whnb.wang) + +## Features + +1. **Multiple platform**: Has integrated more than a dozen third-party platforms. +2. **Minimalist**: The minimalist design is very simple to use. + +## Quick start + +- Add maven dependency + +These artifacts are available from Maven Central: +```xml + + me.zhyd.oauth + JustAuth + 1.10.1 + +``` +- Using JustAuth +```java +// Create authorization request +AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder() + .clientId("clientId") + .clientSecret("clientSecret") + .redirectUri("redirectUri") + .build()); +// Generate authorization url +authRequest.authorize(); +// After authorization to login, it will return: code(auth_code(Alipay only)),state, After version 1.8.0, you can use the AuthCallback as a parameter to the callback interface +// Note: JustAuth saves state for 3 minutes by default. If it is not used within 3 minutes, the expired state will be cleared automatically. +authRequest.login(callback); +``` + +**Examples**： +- [Springboot Example](https://gitee.com/yadong.zhang/JustAuth-demo) +- [jFinal Example](https://github.com/xkcoding/jfinal-justauth-demo) +- [ActFramework Example](https://github.com/xkcoding/act-justauth-demo) + +**Springboot Starter** + +- [justauth-spring-boot-starter](https://github.com/xkcoding/justauth-spring-boot-starter): Spring Boot integrates best practices with JustAuth + +#### API +| :computer: platform | :coffee: API | :page_facing_up: Official document | +|:------:|:-------:|:-------:| +| | [AuthGiteeRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthGiteeRequest.java) | 参考文档 | +| | [AuthGithubRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthGiteeRequest.java) | 参考文档 | +| | [AuthWeiboRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthGiteeRequest.java) | 参考文档 | +| | [AuthDingTalkRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthDingTalkRequest.java) | 参考文档 | +| | [AuthBaiduRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthBaiduRequest.java) | 参考文档 | +| | [AuthCodingRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthCodingRequest.java) | 参考文档 | +| | [AuthTencentCloudRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthTencentCloudRequest.java) | 参考文档 | +| | [AuthOschinaRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthOschinaRequest.java) | 参考文档 | +| | [AuthAlipayRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthAlipayRequest.java) | 参考文档 | +| | [AuthQqRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthQqRequest.java) | 参考文档 | +| | [AuthWeChatRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthWeChatRequest.java) | 参考文档 | +| | [AuthTaobaoRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthTaobaoRequest.java) | 参考文档 | +| | [AuthGoogleRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthGoogleRequest.java) | 参考文档 | +| | [AuthFacebookRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthFacebookRequest.java) | 参考文档 | +| | [AuthDouyinRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthDouyinRequest.java) | 参考文档 | +| | [AuthLinkedinRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthLinkedinRequest.java) | 参考文档 | +| | [AuthMicrosoftRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthMicrosoftRequest.java) | 参考文档 | +| | [AuthMiRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthMiRequest.java) | 参考文档 | +| | [AuthToutiaoRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthToutiaoRequest.java) | 参考文档 | +| | [AuthTeambitionRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthTeambitionRequest.java) | 参考文档 | +| | [AuthRenrenRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthRenrenRequest.java) | 参考文档 | +| | [AuthPinterestRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthPinterestRequest.java) | 参考文档 | +| | [AuthStackOverflowRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthStackOverflowRequest.java) | 参考文档 | +| | [AuthHuaweiRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthHuaweiRequest.java) | 参考文档 | +| | [AuthWeChatEnterpriseRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthWeChatEnterpriseRequest.java) | 参考文档 | +| | [AuthCsdnRequest](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/request/AuthCsdnRequest.java) | 无 | + + + +## Contributions + +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. + +## References + +- [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) +- [OAuth 2.0](https://oauth.net/2/) \ No newline at end of file diff --git a/README.md b/README.md index 5cd83fd..1d0b421 100644 --- a/README.md +++ b/README.md @@ -187,7 +187,8 @@ _请知悉：经咨询CSDN官方客服得知，CSDN的授权开放平台已经 ## 关于OAuth -[The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) +- [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) +- [OAuth 2.0](https://oauth.net/2/) ## 关注&交流 diff --git a/docs/README.md b/docs/README.md index e91eba1..04349f4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -54,6 +54,10 @@ JustAuth，如你所见，它仅仅是一个**第三方授权登录**的**工具 1. **全**：已集成十多家第三方平台（国内外常用的基本都已包含），后续依然还有扩展计划！ 2. **简**：API就是奔着最简单去设计的，尽量让您用起来没有障碍感！ +## 项目关注度趋势 + +[![Stargazers over time](https://starchart.cc/justauth/JustAuth.svg)](https://starchart.cc/justauth/JustAuth) + ## 已集成的平台 | :computer: 平台 | :coffee: API类 | :page_facing_up: SDK | diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 17a2ae5..ad462e1 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,7 +1,7 @@ -- [入门](README.md) -- [更新记录](update.md) -- 引导 - - [如何使用JustAuth集成一个平台](how-to-use.md) +- [概述](README.md) +- 快速开始 + - [名词解释](explain.md) + - [如何使用](how-to-use.md) - [获取授权链接](authorize.md) - [登录](login.md) - 其他特性 @@ -10,3 +10,4 @@ - [配套项目](supporting.md) - [Q&A](Q&A.md) - [Who is using](users.md) +- [更新记录](update.md) diff --git a/docs/explain.md b/docs/explain.md new file mode 100644 index 0000000..cb7d57e --- /dev/null +++ b/docs/explain.md @@ -0,0 +1,29 @@ +本文将就JustAuth中涉及到的一些配置、关键词做一下简单说明，方便使用者理解、使用。 + +## 本文相关名词 + +- `调用者` 指使用`JustAuth`的开发者 +- `第三方` 指开发者对接的第三方网站，比如：QQ平台、微信平台、微博平台 +- `用户` 指最终服务的真实用户 + +## JustAuth中的关键词 + +以下内容了解后，将会使你更容易地上手JustAuth。 + +- `clientId` 客户端身份标识符（应用id），一般在申请完Oauth应用后，由**第三方平台颁发**，唯一 +- `clientSecret` 客户端密钥，一般在申请完Oauth应用后，由**第三方平台颁发** +- `redirectUri` **调用者项目中的有效api地址**。用户在确认第三方平台授权（登录）后，第三方平台会重定向到该地址，并携带code等参数 +- `state` 用来保持授权会话流程完整性，防止CSRF攻击的安全的随机的参数，由**调用者生成** +- `alipayPublicKey` 支付宝公钥。当选择支付宝登录时，必传该值，由**调用者生成** +- `unionId` 是否需要申请unionid，目前只针对**qq登录**。注：qq授权登录时，获取unionid需要单独发送邮件申请权限。如果个人开发者账号中申请了该权限，可以将该值置为true，在获取openId时就会同步获取unionId。参考链接：[UnionID介绍](http://wiki.connect.qq.com/unionid%E4%BB%8B%E7%BB%8D) +- `stackOverflowKey` Stack Overflow 登陆时需单独提供的key，由**第三方平台颁发** +- `agentId` 企业微信登陆时需单独提供该值，由**第三方平台颁发**，为授权方的网页应用ID +- `source` JustAuth支持的第三方平台，比如：GITHUB、GITEE等 + +## 参考资料 + +关于OAuth2相关的内容、原理可以自行参阅以下资料： + +- [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) +- [OAuth 2.0](https://oauth.net/2/) + diff --git a/docs/how-to-use.md b/docs/how-to-use.md index 6c1d801..c83d399 100644 --- a/docs/how-to-use.md +++ b/docs/how-to-use.md @@ -1,3 +1,33 @@ -# 如何使用JustAuth集成一个平台 +在前面有介绍到，JustAuth的特点之一就是**简**，极简主义，不给使用者造成不必要的障碍。 -待补充 +既然牛皮吹下了， 那么如何才能用JustAuth实现第三方登录呢？ + +使用JustAuth总共分三步（**这三步也适合于任何一个支持的平台**）： + +1. 申请注册第三方平台的开发者账号 +2. 创建第三方平台的应用，获取配置信息(id, secret, callbackUrl) +3. 使用该工具实现授权登陆 + + +- 引入依赖 +```xml + + me.zhyd.oauth + JustAuth + 1.10.1 + +``` +- 调用api +```java +// 创建授权request +AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder() + .clientId("clientId") + .clientSecret("clientSecret") + .redirectUri("redirectUri") + .build()); +// 生成授权页面 +authRequest.authorize(); +// 授权登录后会返回code（auth_code（仅限支付宝））、state，1.8.0版本后，可以用AuthCallback类作为回调接口的参数 +// 注：JustAuth默认保存state的时效为3分钟，3分钟内未使用则会自动清除过期的state +authRequest.login(callback); +``` \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index db25103..6150505 100644 --- a/docs/index.html +++ b/docs/index.html @@ -48,6 +48,29 @@ auto2top: true, coverpage: true, formatUpdated: '{YYYY}/{MM}/{DD} {HH}:{mm}:{ss}', + plugins: [ + function (hook, vm) { + var footer = [ + '
', + '' + ].join(''); + hook.afterEach(function (html) { + return html + footer + }); + hook.beforeEach(function (html) { + var url = 'https://gitee.com/yadong.zhang/JustAuth/tree/master/docs/' + vm.route.file; + var editHtml = '[📝 编辑该文档](' + url + ')\n'; + + return html + + '\n----\n' + + 'Last modified {docsify-updated} ' + + editHtml + }) + } + ] } diff --git a/src/main/java/me/zhyd/oauth/config/AuthConfig.java b/src/main/java/me/zhyd/oauth/config/AuthConfig.java index 2fef943..d93d053 100644 --- a/src/main/java/me/zhyd/oauth/config/AuthConfig.java +++ b/src/main/java/me/zhyd/oauth/config/AuthConfig.java @@ -16,12 +16,12 @@ import lombok.*; public class AuthConfig { /** - * 客户端id：对应个平台的appKey + * 客户端id：对应各平台的appKey */ private String clientId; /** - * 客户端Secret：对应个平台的appSecret + * 客户端Secret：对应各平台的appSecret */ private String clientSecret; -- GitLab