提示

jap-social 是为了方便快速的集成第三方登录而添加的增强包，依赖并完全适配 JustAuth (opens new window) 支持的平台。

常规使用

提示

如果使用该方式也可以替换掉 JustAuth

添加依赖

<dependency>
    <groupId>com.fujieid</groupId>
    <artifactId>jap-social</artifactId>
    <version>{latest-version}</version>
</dependency>

实现 JapUserService 接口

JapUserService 是 JAP 调用（操作）开发者业务系统中用户的接口，jap-social 需要实现 getByPlatformAndUid 和 createAndGetSocialUser 方法。

import com.fujieid.jap.core.JapUser;
import com.fujieid.jap.core.JapUserService;
import me.zhyd.oauth.model.AuthUser;


public class JapSocialUserServiceImpl implements JapUserService {

    /**
     * 根据第三方平台标识（platform）和第三方平台的用户 uid 查询数据库
     *
     * @param platform 第三方平台标识
     * @param uid      第三方平台的用户 uid
     * @return JapUser
     */
    @Override
    public JapUser getByPlatformAndUid(String platform, String uid) {
        return null;
    }

    /**
     * 创建并获取第三方用户，相当于第三方登录成功后，将授权关系保存到数据库（开发者业务系统中 social user -> sys user 的绑定关系）
     *
     * @param userInfo JustAuth 中的 AuthUser
     * @return JapUser
     */
    @Override
    public JapUser createAndGetSocialUser(Object userInfo) {
        AuthUser authUser = (AuthUser) userInfo;
        // 查询绑定关系，确定当前用户是否已经登录过业务系统
        JapUser japUser = this.getByPlatformAndUid(authUser.getSource(), authUser.getUuid());
        if (null == japUser) {
            // 添加用户 
            japUser = createJapUser();
            japUser.setAdditional(authUser);
        }
        return japUser;
    }
}

特别注意

上面示例代码仅作演示，具体业务逻辑需要开发者自己实现

创建 OAuth 应用

以 Gitee 为例，创建 OAuth 应用的步骤参考 Gitee 登录 - 申请应用 (opens new window)

创建完成后如下：

实现 controller

import cn.hutool.core.util.URLUtil;
import com.fujieid.jap.core.JapUserService;
import com.fujieid.jap.core.config.JapConfig;
import com.fujieid.jap.core.result.JapResponse;
import com.fujieid.jap.http.jakarta.JakartaRequestAdapter;
import com.fujieid.jap.http.jakarta.JakartaResponseAdapter;
import com.fujieid.jap.social.SocialConfig;
import com.fujieid.jap.social.SocialStrategy;
import me.zhyd.oauth.config.AuthConfig;
import me.zhyd.oauth.utils.UuidUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.ModelAndView;
import org.springframework.web.servlet.view.RedirectView;

import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@RestController
@RequestMapping("/social")
public class SocialController {

    @Resource(name = "social")
    private JapUserService japUserService;

    @RequestMapping("/login/gitee")
    public ModelAndView renderAuth(HttpServletRequest request, HttpServletResponse response) {
        SocialStrategy socialStrategy = new SocialStrategy(japUserService, new JapConfig());
        SocialConfig config = new SocialConfig();
        // platform 参考 justauth#AuthDefaultSource
        // 如果包含通过 justauth 自定义的第三方平台，则该值为实现 AuthSource 后的 getName() 值
        config.setPlatform("gitee");
        config.setState(UuidUtils.getUUID());
        config.setJustAuthConfig(AuthConfig.builder()
                .clientId("fda07d40917d6f040822d3fa01c8c75588c67d63132c3ddc5c66990342115ba9")
                .clientSecret("016f88fbff2d178263c4060c46168f4937153120a310adc21980e7838b76e833")
                .redirectUri("http://127.0.0.1:8443/social/login/gitee")
                .build());
        JapResponse japResponse = socialStrategy.authenticate(config, new JakartaRequestAdapter(request), new JakartaResponseAdapter(response));
        if (!japResponse.isSuccess()) {
            return new ModelAndView(new RedirectView("/?error=" + URLUtil.encode(japResponse.getMessage())));
        }
        if (japResponse.isRedirectUrl()) {
            return new ModelAndView(new RedirectView((String) japResponse.getData()));
        } else {
            // 登录成功，需要对用户数据进行处理
            // ...
            System.out.println(japResponse.getData());
            return new ModelAndView(new RedirectView("/"));
        }
    }
}

提示

jap-social 对整个授权流程做了优化，不再要求开发者强制区分跳转 authorizeUrl 和通过 login 获取用户数据这两个方法，jap-social 将两者整合，方便开发者调用。

在仅使用 JustAuth 时，实现第三方平台的登录，需要如下编码：

@RestController
@RequestMapping("/oauth")
public class RestAuthController {

    @RequestMapping("/render")
    public void renderAuth(HttpServletResponse response) throws IOException {
        AuthRequest authRequest = getAuthRequest();
        response.sendRedirect(authRequest.authorize(AuthStateUtils.createState()));
    }

    @RequestMapping("/callback")
    public Object login(AuthCallback callback) {
        AuthRequest authRequest = getAuthRequest();
        return authRequest.login(callback);
    }

    // 获取 request...
}

以上代码参考：Gitee 登录 (opens new window)

而 jap-social 将两者进行融合，开发者不需要再关注 render 或者 callback 的逻辑，直接一把梭即可。

测试登录

启动测试项目后访问 http://127.0.0.1:8443/social/login/gitee

因为我已经在浏览器中登录过 gitee，所以 oauth 会跳过登录认证的流程，直接跳转到授权页面。

登录成功

注意

response data 的格式为：

{
  "additional" : {},
  "userId" : "1",
  "username" : "jap"
}

其中 additional 节点为 JustAuth 的 me.zhyd.oauth.model.AuthUser (opens new window) 类

更多使用方法

加载自定义的第三方 AuthRequest

在 JustAuth 中支持 自定义第三方平台的OAuth (opens new window)，那么在 jap 中如何加载自定义的 AuthRequest 呢？

jap-social 定义了两个属性：

• ScanPackages：接受一个字符串数组，表示需要扫描的存放 AuthRequest 实现类的包名，默认为 me.zhyd.oauth.request，即默认加载 JustAuth 依赖包中的实现类。
• ExclusionClassNames：接受一个字符串数组，表示需要排除的（不需要扫描）类/接口名，比如：AuthDefaultRequest,AbstractAuthWeChatEnterpriseRequest, AuthRequest等类/接口。

如何知道需要排除哪些类/接口？

记住一条：只需要扫描实际的第三方平台实现类就可。比如：AuthWeChatEnterpriseQrcodeRequest、AuthWeChatEnterpriseThirdQrcodeRequest和 AuthWeChatEnterpriseWebRequest 这三个同一平台不同登录方式的实现类， 他们都继承自同一个抽象父类 AbstractAuthWeChatEnterpriseRequest，这个抽象父类就是需要排除掉的。

言归正传，通过以下两个属性，配置自定义的第三方平台的包名和需要排除的类：

SocialConfig config = new SocialConfig();
config.setScanPackages(new String[]{"com.fujieid.jap.xx", "com.fujieid.jap.yy"});
config.setExclusionClassNames(new String[]{"AbstractJapAuthRequest", "AbstractJapAuthRequest2"});

以上代码的含义就是：加载 com.fujieid.jap.xx 和 com.fujieid.jap.yy 包下定义的 AuthRequest 的实现类，同时排除 AbstractJapAuthRequest 和 AbstractJapAuthRequest2 两个类。

`ScanPackages` 和 `ExclusionClassNames` 是重置还是累加？

累加。jap-social 默认就会加载 JustAuth 下的内容，这一点是不能改变的，在加载完 JustAuth 下的数据后，再去加载开发者自定义的 ScanPackages 和 ExclusionClassNames 内容。

SocialConfig 配置项

参数名	参数类型	必填	解释
platform	String	√	不分大小写的第三方平台名称。例如：gitee、github、google
justAuthConfig	AuthConfig	√	JustAuth 的配置项
state	String	×	客户端用于维护请求和回调之间的状态的不透明值。授权服务器在将用户代理重定向回客户端时包含此值
scanPackages	String[]	×	接受一个字符串数组，表示需要扫描的存放 AuthRequest 实现类的包名，默认为 me.zhyd.oauth.request，即默认加载 JustAuth 依赖包中的实现类。
exclusionClassNames	String[]	×	接受一个字符串数组，表示需要排除的（不需要扫描）类/接口名，比如：AuthDefaultRequest,AbstractAuthWeChatEnterpriseRequest, AuthRequest等类/接口。

官方推荐

• 普通示例项目：jap-demo (opens new window)
• 前后端分离项目示例：jap-demo-vue (opens new window)