sa-token/sa-token-doc/oauth2/oauth2-custom-scope.md

OAuth2-自定义 Scope 权限及处理器

---

1、需求场景

一般情况下，对于第三方 oauth2-client 来讲，仅仅拿到用户的 access_token 是不够的，还需要拿到更多的信息，比如用户昵称、头像等资料。

sa-token-oauth2 提供两种模式，让 access_token 可以得到更多信息。

• 自定义接口模式：在 oauth2-server 端开放一个资料查询接口，在 oauth2-client 得到 access_token 后，再次调用这个接口来获取 userinfo 信息。
• 自定义权限处理器模式：自定义一个 ScopeHandler，直接在返回 access_token 时追加字段，将 userinfo 信息和 access_token 一并返回到 oauth2-client。

2、自定义接口模式

1、新建查询接口

在 oauth2-server 新建接口，查询指定 access_token 代表的 userId 其 userinfo：

// 获取 userinfo 信息：昵称、头像、性别等等
@RequestMapping("/oauth2/userinfo")
public SaResult userinfo() {
	// 获取 Access-Token 对应的账号id
	String accessToken = SaOAuth2Manager.getDataResolver().readAccessToken(SaHolder.getRequest());
	Object loginId = SaOAuth2Util.getLoginIdByAccessToken(accessToken);
	System.out.println("-------- 此Access-Token对应的账号id: " + loginId);
	
	// 校验 Access-Token 是否具有权限: userinfo
	SaOAuth2Util.checkAccessTokenScope(accessToken, "userinfo");
	
	// 模拟账号信息 （真实环境需要查询数据库获取信息）
	Map<String, Object> map = new LinkedHashMap<>();
	// map.put("userId", loginId);  一般原则下，oauth2-server 不能把 userId 返回给 oauth2-client
	map.put("nickname", "林小林");
	map.put("avatar", "http://xxx.com/1.jpg");
	map.put("age", "18");
	map.put("sex", "男");
	map.put("address", "山东省 青岛市 城阳区");
	return SaResult.ok().setMap(map);
}

2、申请 code 时指定权限

oauth2-client 申请 code 时，一定需要加上 userinfo 权限

http://sa-oauth-server.com:8000/oauth2/authorize
	?response_type=code
	&client_id=1001
	&redirect_uri=http://sa-oauth-client.com:8002/
	&scope=userinfo

3、code 换 access_token

访问上述链接后，得到 code 授权码，然后我们拿着 code 换 access_token

http://sa-oauth-server.com:8000/oauth2/token
    ?grant_type=authorization_code
    &client_id=1001
    &client_secret=aaaa-bbbb-cccc-dddd-eeee
    &code=${code}

4、access_token 取 userinfo

使用返回的 access_token 再次访问接口 /oauth2/userinfo

http://sa-oauth-server.com:8000/oauth2/userinfo?access_token=${access_token}

返回以下结果：

{
  "code": 200,
  "msg": "ok",
  "data": null,
  "nickname": "林小林",
  "avatar": "http://xxx.com/1.jpg",
  "age": "18",
  "sex": "男",
  "address": "山东省 青岛市 城阳区"
}

拿到 userinfo。

3、自定义权限处理器模式

1、新建权限处理器

在 oauth2-server 新建 UserinfoScopeHandler.java 实现 SaOAuth2ScopeHandlerInterface 接口：

@Component
public class UserinfoScopeHandler implements SaOAuth2ScopeHandlerInterface {

    @Override
    public String getHandlerScope() {
        return "userinfo";
    }

    @Override
    public void workAccessToken(AccessTokenModel at) {
        System.out.println("--------- userinfo 权限，加工 AccessTokenModel --------- ");
        // 模拟账号信息 （真实环境需要查询数据库获取信息）
        Map<String, Object> map = new LinkedHashMap<String, Object>();
        map.put("userId", "10008");
        map.put("nickname", "shengzhang_");
        map.put("avatar", "http://xxx.com/1.jpg");
        map.put("age", "18");
        map.put("sex", "男");
        map.put("address", "山东省 青岛市 城阳区");
        at.extraData.putAll(map);
    }

    @Override
    public void workClientToken(ClientTokenModel ct) {
    }

}

如上所述，所有写入到 extraData 中的数据，都将追加返回到 oauth2-client 端。

2、申请 code 时指定权限

oauth2-client 申请 code 时，一定需要加上 userinfo 权限

http://sa-oauth-server.com:8000/oauth2/authorize
	?response_type=code
	&client_id=1001
	&redirect_uri=http://sa-oauth-client.com:8002/
	&scope=userinfo

3、code 换 access_token

访问上述链接后，得到 code 授权码，然后我们拿着 code 换 access_token

http://sa-oauth-server.com:8000/oauth2/token
    ?grant_type=authorization_code
    &client_id=1001
    &client_secret=aaaa-bbbb-cccc-dddd-eeee
    &code=${code}

返回结果如下

{
  "code": 200,
  "msg": "ok",
  "data": null,
  "token_type": "bearer",
  "access_token": "LQ24xI0hX25vIzvciHPA0PNsnGCweSFM1Bzl8783li07VAXpw8sEfn9xsta2",
  "refresh_token": "rKB8mby1Mw8yZXHbWzliHx6lmatcLcULLw5C5cUMBhMMRx72DFg5u0owZgrA",
  "expires_in": 7199,
  "refresh_expires_in": 2591999,
  "client_id": "1001",
  "scope": "openid,userid,userinfo",
  "userinfo": {
    "userId": "10008",
    "nickname": "shengzhang_",
    "avatar": "http://xxx.com/1.jpg",
    "age": "18",
    "sex": "男",
    "address": "山东省 青岛市 城阳区"
  }
}

拿到 userinfo。

总结

相比于自定义接口模式，自定义权限处理器模式可以少一次网络请求，让 oauth2-client 端提前拿到 userinfo 信息。

4、最终权限处理器

当一个自定义权限处理器，监听的 scope 字符串为 _FINALLY_WORK_SCOPE 时，则代表这个权限处理器为“最终权限处理器”。

最终权限处理器会永远在所有权限处理器工作完成之后执行一次，即使 oauth2-client 端没有申请任何 scope，最终权限处理器也会固定执行。

示例：

/**
 * 最终权限处理器：在所有权限处理器工作完成之后，执行此权限处理器
 */
@Component
public class FinallyWorkScopeHandler implements SaOAuth2ScopeHandlerInterface {

    @Override
    public String getHandlerScope() {
        return SaOAuth2Consts._FINALLY_WORK_SCOPE;
    }

    @Override
    public void workAccessToken(AccessTokenModel at) {
        // 在所有权限处理器工作完成之后，执行此处方法加工 AccessToken
        // System.out.println(123);
    }

    @Override
    public void workClientToken(ClientTokenModel ct) {
        // System.out.println(456);
    }
}