初步完善 oauth2 相关文档

2025-10-26 02:29:01 +08:00 · 2024-08-19 17:49:59 +08:00
parent e8d3a6f137
commit 25b24414ff
17 changed files with 641 additions and 352 deletions
--- a/sa-token-doc/oauth2/oauth2-server.md
+++ b/sa-token-doc/oauth2/oauth2-server.md
@@ -11,7 +11,7 @@


 ### 2、引入依赖 
-创建SpringBoot项目 `sa-token-demo-oauth2-server`（不会的同学自行百度或参考仓库示例），添加pom依赖：
+创建SpringBoot项目 `sa-token-demo-oauth2-server`（不会的同学自行百度或参考仓库示例），引入 `pom.xml` 依赖：

 <!---------------------------- tabs:start ---------------------------->
 <!-------- tab:Maven 方式 -------->
@@ -43,36 +43,37 @@ implementation 'cn.dev33:sa-token-oauth2:${sa.top.version}'


 ### 3、开放服务 
-1、新建 `SaOAuth2TemplateImpl` 
+1、自定义数据加载器：新建 `SaOAuth2DataLoaderImpl` 实现 `SaOAuth2DataLoader` 接口。
+
 ``` java
 /**
- * Sa-Token OAuth2.0 整合实现 
+ * Sa-Token OAuth2：自定义数据加载器
 */
@Component
-public class SaOAuth2TemplateImpl extends SaOAuth2Template {
+public class SaOAuth2DataLoaderImpl implements SaOAuth2DataLoader {
 	
-	// 根据 id 获取 Client 信息 
+	// 根据 clientId 获取 Client 信息
 	@Override
 	public SaClientModel getClientModel(String clientId) {
 		// 此为模拟数据，真实环境需要从数据库查询 
 		if("1001".equals(clientId)) {
 			return new SaClientModel()
-					.setClientId("1001")
-					.setClientSecret("aaaa-bbbb-cccc-dddd-eeee")
-					.setAllowUrl("*")
-					.setContractScope("userinfo")
-					.setIsAutoMode(true);
+					.setClientId("1001")    // client id
+					.setClientSecret("aaaa-bbbb-cccc-dddd-eeee")    // client 秘钥
+					.addAllowUrls("*")    // 所有允许授权的 url
+					.addContractScopes("openid", "userid", "userinfo")    // 所有签约的权限
+					.setIsAutoMode(true);    // 是否自动判断开放的授权模式 
 		}
 		return null;
 	}
 	
-	// 根据ClientId 和 LoginId 获取openid 
+	// 根据 clientId 和 loginId 获取 openid
 	@Override
 	public String getOpenid(String clientId, Object loginId) {
-		// 此为模拟数据，真实环境需要从数据库查询 
-		return "gr_SwoIN0MC1ewxHX_vfCW3BothWDZMMtx__";
+		// 此处使用框架默认算法生成 openid，真实环境建议改为从数据库查询
+		return SaOAuth2DataLoader.super.getOpenid(clientId, loginId);
 	}
-	
+
 }
 ```

@@ -97,30 +98,32 @@ public class SaOAuth2ServerController {
 	// Sa-OAuth2 定制化配置 
 	@Autowired
 	public void setSaOAuth2Config(SaOAuth2Config cfg) {
-		cfg.
-			// 配置：未登录时返回的View 
-			setNotLoginView(() -> {
-				String msg = "当前会话在OAuth-Server端尚未登录，请先访问"
-	                        + "<a href='/oauth2/doLogin?name=sa&pwd=123456' target='_blank'> doLogin登录 </a>"
-	                        + "进行登录之后，刷新页面开始授权";
-	            return msg;
-			}).
-			// 配置：登录处理函数 
-			setDoLoginHandle((name, pwd) -> {
-				if("sa".equals(name) && "123456".equals(pwd)) {
-					StpUtil.login(10001);
-					return SaResult.ok();
-				}
-				return SaResult.error("账号名或密码错误");
-			}).
-			// 配置：确认授权时返回的View 
-			setConfirmView((clientId, scope) -> {
-				String msg = "<p>应用 " + clientId + " 请求授权：" + scope + "</p>"
-                        + "<p>请确认：<a href='/oauth2/doConfirm?client_id=" + clientId + "&scope=" + scope + "' target='_blank'> 确认授权 </a></p>"
-                        + "<p>确认之后刷新页面</p>";
-				return msg;
-			})
-			;
+		
+		// 配置：未登录时返回的View 
+		cfg.notLoginView = () -> {
+			String msg = "当前会话在OAuth-Server端尚未登录，请先访问"
+						+ "<a href='/oauth2/doLogin?name=sa&pwd=123456' target='_blank'> doLogin登录 </a>"
+						+ "进行登录之后，刷新页面开始授权";
+			return msg;
+		};
+		
+		// 配置：登录处理函数 
+		cfg.doLoginHandle = (name, pwd) -> {
+			if("sa".equals(name) && "123456".equals(pwd)) {
+				StpUtil.login(10001);
+				return SaResult.ok();
+			}
+			return SaResult.error("账号名或密码错误");
+		};
+		
+		// 配置：确认授权时返回的 view 
+		cfg.confirmView = (clientId, scopes) -> {
+			String scopeStr = SaFoxUtil.convertListToString(scopes);
+			String msg = "<p>应用 " + clientId + " 请求授权：" + scopeStr + "</p>"
+					+ "<p>请确认：<a href='/oauth2/doConfirm?client_id=" + clientId + "&scope=" + scopeStr + "' target='_blank'> 确认授权 </a></p>"
+					+ "<p>确认之后刷新页面</p>";
+			return msg;
+		};
 	}

 	// 全局异常拦截  
@@ -134,7 +137,19 @@ public class SaOAuth2ServerController {
 ```
 注意：在`setDoLoginHandle`函数里如果要获取name, pwd以外的参数，可通过`SaHolder.getRequest().getParam("xxx")`来获取 

-3、创建启动类：
+3、全局异常处理
+``` java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+	@ExceptionHandler
+	public SaResult handlerException(Exception e) {
+		e.printStackTrace(); 
+		return SaResult.error(e.getMessage());
+	}
+}
+```
+
+4、创建启动类：
 ``` java
 /**
 * 启动：Sa-OAuth2 Server端 
@@ -154,28 +169,44 @@ public class SaOAuth2ServerApplication {

 1、由于暂未搭建Client端，我们可以使用Sa-Token官网作为重定向URL进行测试：
 ``` url
-http://sa-oauth-server.com:8001/oauth2/authorize?response_type=code&client_id=1001&redirect_uri=https://sa-token.cc&scope=userinfo
+http://sa-oauth-server.com:8000/oauth2/authorize?response_type=code&client_id=1001&redirect_uri=https://sa-token.cc&scope=openid
 ```

 2、由于首次访问，我们在OAuth-Server端暂未登录，会被转发到登录视图 

-![sa-oauth2-server-login-view](https://oss.dev33.cn/sa-token/doc/oauth2/sa-oauth2-server-login-view.png 's-w-sh')
+![sa-oauth2-server-login-view](https://oss.dev33.cn/sa-token/doc/oauth2-new/sa-oauth2-server-login-view.png 's-w-sh')

 3、点击doLogin进行登录之后刷新页面，会提示我们确认授权
-![sa-oauth2-server-login-view](https://oss.dev33.cn/sa-token/doc/oauth2/sa-oauth2-server-scope.png 's-w-sh')
+![sa-oauth2-server-scope](https://oss.dev33.cn/sa-token/doc/oauth2-new/sa-oauth2-server-scope.png 's-w-sh')

 4、点击确认授权之后刷新页面，我们会被重定向至 redirect_uri 页面，并携带了code参数 

-![sa-oauth2-server-code](https://oss.dev33.cn/sa-token/doc/oauth2/sa-oauth2-server-code.png 's-w-sh')
+![sa-oauth2-server-code](https://oss.dev33.cn/sa-token/doc/oauth2-new/sa-oauth2-server-code.png 's-w-sh')

 4、我们拿着code参数，访问以下地址：
 ``` url
-http://sa-oauth-server.com:8001/oauth2/token?grant_type=authorization_code&client_id=1001&client_secret=aaaa-bbbb-cccc-dddd-eeee&code={code}
+http://sa-oauth-server.com:8000/oauth2/token?grant_type=authorization_code&client_id=1001&client_secret=aaaa-bbbb-cccc-dddd-eeee&code={code}
 ```

 将得到 `Access-Token`、`Refresh-Token`、`openid`等授权信息 

-![sa-oauth2-server-token](https://oss.dev33.cn/sa-token/doc/oauth2/sa-oauth2-server-token.png 's-w-sh')
+``` js
+{
+  "code": 200,
+  "msg": "ok",
+  "data": null,
+  "token_type": "bearer",
+  "access_token": "cAls8jnBLmeo5yuCUMwb8zxaSsQPPzGINXF3NOCjCqFHplr6hagdT6A5HeR2",
+  "refresh_token": "L2rPbJ3aaOXwaB4Zu0EGWNz5EjVNpw5u2oMP9CS2IEap7rR3Hb76ZqqHS07J",
+  "expires_in": 7199,
+  "refresh_expires_in": 2591999,
+  "client_id": "1001",
+  "scope": "openid",
+  "openid": "ded91dc189a437dd1bac2274be167d50"
+}
+```
+
+<!-- ![sa-oauth2-server-token](https://oss.dev33.cn/sa-token/doc/oauth2/sa-oauth2-server-token.png 's-w-sh') -->

 测试完毕

@@ -188,7 +219,7 @@ http://sa-oauth-server.com:8001/oauth2/token?grant_type=authorization_code&clien

 依次启动`OAuth2-Server` 与 `OAuth2-Client`，然后从浏览器访问：[http://sa-oauth-client.com:8002](http://sa-oauth-client.com:8002)

-![sa-oauth2-client-index](https://oss.dev33.cn/sa-token/doc/oauth2/sa-oauth2-client-index.png 's-w-sh')
+![sa-oauth2-client-index](https://oss.dev33.cn/sa-token/doc/oauth2-new/sa-oauth2-client-index.png 's-w-sh')

 如图，可以针对OAuth2.0四种模式进行详细测试