開發與維運

xxl-job 登入功能集成 OIDC 統一認證

2021-06-25

前言

xxl-job 是一款 java 開發的、開源的分佈式任務調度系統，自帶了登錄認證功能，不支持對接、擴展 LDAP 、OIDC 等標準認證系統，考慮到單獨維護 xxl-job 自有的用戶系統不方便，以及存在人員離職、調崗、權限變動等需要及時調整用戶權限的情況，需要接入公司統一的 OIDC 認證系統

相關鏈接

xxl-job 自身認證功能分析

xxl-job 自帶的登錄認證用戶信息維護在 mysql 的 user 表中，用戶從登錄頁提交用戶名和密碼，後端查詢用戶信息、校驗密碼，驗證成功後設置登錄信息到 cookie 中，採用 cookie 保持登錄狀態，大致的流程如下：

OIDC 的認證流程

OIDC(OpenID Connect) 是一種融合了 OpenID 、Oauth2 的身份認證協議。認證流程上和 Oauth2 基本一致，但是，OIDC 在 Oauth2 的 access\_token 基礎上新增了一個使用 jwt 生成的 idToken，idToken 中攜帶了用戶基本信息，使用私鑰驗籤成功後，可直接使用，省略了通過 access\_token 獲取用戶信息的步驟。所以 OIDC 的認證流程既和 Oauth2 類似又有區別，基本流程如下：

  1. 客戶端準備包含所需請求參數的身份驗證請求。
  2. 客戶端將請求發送到授權服務器。
  3. 授權服務器對終端用戶進行身份驗證。
  4. 授權服務器獲得終端用戶同意/授權。
  5. 授權服務器將 code 發送回客戶端 。
  6. 客戶端將 code 發送到令牌端點獲取 access_token 和 idToken。
  7. 客戶端使用私鑰驗證 idToken 拿到用戶標識 or 將 access_token 發送到授權服務器獲取用戶標識。

這裡注意最後第 6、7 點操作，這裡開始 OIDC 和 Oauth2 不一樣了

xxl-job 集成 OIDC 後的認證流程

從 OIDC 的認證流程得知，終端用戶通過授權服務器授權認證後，授權服務器會攜帶 code 重定向到客戶端服務，客戶端通過 code 可以拿到用戶唯一標識，通過這個唯一標識，可以繼續完成客戶端原本的認證流程。集成 OIDC 後，xxl-job 登錄的大致流程如下：

集成 OIDC 後，系統認證保持用戶登錄狀態的機制沒有變化，依然使用  Cookie ，需要特殊處理以及關注地方有：

  • 用戶首次登錄系統，由於不存在系統中，需要先創建用戶
  • 如果系統首次投產使用，記得設計一個可以從配置指定管理賬戶的功能，不然你得手動改數據庫了
  • 如果系統運行很久了，需要考慮好原系統用戶和 OIDC 授權用戶的映射關係
  • 退出操作時，除了清除自身的用戶登錄狀態，是否退出 OIDC 服務(實現 sso)的登錄狀態也需要考慮

xxl-job 登錄模塊重新設計

考慮開發環境使用 OIDC 服務不方便以及解耦對第三方認證授權服務的依賴，決定在集成 OIDC 時，兼容本地登錄功能，登錄流程由登錄模式來控制區分，登錄模式使用配置驅動，設計集成 OIDC 後 ，xxl-job 支持的登錄模式如下：

  • onlyLocal ：只支持 xxl-job 自身用戶系統登錄認證
  • onlyOidc : 只支持 Oidc 授權服務器授權登錄認證
  • mix ：混合模式，同時支持自身用戶系統登錄認證、Oidc 授權服務器授權登錄認證

onlyLocal 模式登錄界面：

mix 模式登錄界面：

olnyOidc 模式登錄界面：

olnyOidc 模式特殊，從設計上來說，如果需要保留用戶使用習慣，可以保留一個跳轉到 OIDC 授權服務器的鏈接按鈕給用戶點擊。如果做的乾淨利落，在 olnyOidc 模式下，訪問登錄頁可以直接 302 到 OIDC 授權服務器。

保留登錄按鈕的界面(實際這個頁面取消了)

編碼環節

配置屬性類，省略了get、set

/**
 * @author kl (http://kailing.pub)
 * @since 2021/6/21
 */
@ConfigurationProperties(prefix = "oidc")
@Configuration
public class OidcProperties {

    private static final LoginMod DEFAULT_LOGIN_MOD = LoginMod.onlyLocal;

    private LoginMod loginMod = DEFAULT_LOGIN_MOD;
    private String clientId;
    private String clientSecret;
    private String accessTokenUrl;
    private String profileUrl;
    private String redirectUri;
    private String logoutUrl;
    private String loginUrl;
    private List<String> adminLists = new ArrayList<>();

    public enum LoginMod {
        mix,
        onlyOidc,
        onlyLocal
    }
}

對應瞭如下的配置, 除了 login-mod  、redirect-uri 、admin-Lists 是 xxl-job 自身登錄功能需要，其他的配置均由 OIDC 授權服務器提供

oidc.login-mod=onlyOidc
oidc.client-id = xxl-job-dev
oidc.client-secret = xx
oidc.base-url = https://sso.security.oidc.com
oidc.access-token-url = ${oidc.base-url}/cas/oidc/accessToken
oidc.login-url = ${oidc.base-url}/cas/oidc/authorize?response_type=code&client_id=${oidc.client-id}&redirect_uri=${oidc.redirect-uri}&scope=openid
oidc.redirect-uri = http://172.26.203.103:8071/oidc/tokenLogin
oidc.logout-url =${oidc.base-url}/cas/logout?service=${oidc.redirect-uri}
oidc.admin-Lists = chenkailing

Oidc 服務類，使用這個類裡的方法和 OIDC 授權服務器交互

/**
 * @author kl (http://kailing.pub)
 * @since 2021/6/21
 */
@Service
public class OidcService {

    private final OidcProperties oidcProperties;
    private final RestTemplate restTemplate;
    
    public OidcService(OidcProperties oidcProperties, RestTemplate restTemplate) {
        this.oidcProperties = oidcProperties;
        this.restTemplate = restTemplate;
    }

    /**
     * 請求 OIDC 授權服務器，獲取 idToken
     * idToken 中包含的信息 (非標準)
     * {
     * "sub": "248289761001",
     * "name": "Jane Doe",
     * "given_name": "Jane",
     * "family_name": "Doe",
     * "preferred_username": "j.doe",
     * "email": "[email protected]",
     * "picture": "http://example.com/janedoe/me.jpg"
     * }
     */
    public String getUsernameByCode(String code) {
        URI uri = UriComponentsBuilder.fromUriString(oidcProperties.getAccessTokenUrl())
                .queryParam("client_id", oidcProperties.getClientId())
                .queryParam("client_secret", oidcProperties.getClientSecret())
                .queryParam("redirect_uri", oidcProperties.getRedirectUri())
                .queryParam("code", code)
                .queryParam("grant_type", "authorization_code")
                .build()
                .toUri();
        AuthorizationEntity auth = restTemplate.getForObject(uri, AuthorizationEntity.class);
        Assert.notNull(auth, "AccessToken is null");
        String idToken = auth.getIdToken();
        int i = idToken.lastIndexOf('.');
        String withoutSignatureToken = idToken.substring(0, i+1);
        return Jwts.parserBuilder()
                .build()
                .parseClaimsJwt(withoutSignatureToken)
                .getBody()
                .get("sub", String.class);
    }

    /**
     * @return 1 : 管理員 、0 : 普通用戶
     */
    public int getUserRole(XxlJobUser user) {
        List<String> adminLists = oidcProperties.getAdminLists();
        if (adminLists.contains(user.getUsername())) {
            return 1;
        }
        return 0;
    }

    public String getOidcLoginUrl() {
        return oidcProperties.getLoginUrl();
    }

    public OidcProperties.LoginMod getLoginMod() {
        return oidcProperties.getLoginMod();
    }

    public boolean isRedirectOidcLoginUrl() {
        return oidcProperties.getLoginMod().equals(OidcProperties.LoginMod.onlyOidc);
    }

    public String getLogoutUrl() {
        return oidcProperties.getLogoutUrl();
    }

    static class AuthorizationEntity {

        @JsonProperty("access_token")
        private String accessToken;
        @JsonProperty("id_token")
        private String idToken;
        @JsonProperty("refresh_token")
        private String refreshToken;
        @JsonProperty("expires_in")
        private String expiresIn;
        @JsonProperty("token_type")
        private String tokenType;

        private String scope;
    }

}

OIDC 登錄接口，也就是提供給 OIDC 授權服務器回調的接口

/**
 * OIDC登錄
 */
@RequestMapping(value = "/oidc/tokenLogin", method = {RequestMethod.POST, RequestMethod.GET})
@PermissionLimit(limit = false)
public ModelAndView loginByOidc(HttpServletRequest request, HttpServletResponse response, ModelAndView modelAndView) {
    if (loginService.ifLogin(request, response) != null) {
        modelAndView.setView(new RedirectView("/", true, false));
        return modelAndView;
    }
    String code = request.getParameter("code");
    if (Objects.isNull(code)) {
        return this.loginPageView();
    }
    String username = oidcService.getUsernameByCode(code);
    loginService.oidcLogin(username, response);

    modelAndView.setView(new RedirectView("/", true, false));
    return modelAndView;
}

這個接口對應了 xxl-job 集成 OIDC 後的認證流程:

  1. 判斷是否登錄，已經登錄則跳轉到登錄成功的頁面
  2. 獲取 code ，不存在則調整到登錄頁面
  3. 通過 code 請求 OIDC 授權服務器獲取 UserInfo
  4. 處理內部登錄邏輯（用戶是否存在，存在則設置 Cookie，不存在則先創建用戶在設置 Cookie）
  5. 跳轉到登錄成功的頁面

跳轉登錄頁邏輯做了封裝，因為，根據登錄模式的不同，有不同的處理邏輯：

private ModelAndView loginPageView() {
    ModelAndView modelAndView = new ModelAndView(LOGIN_PAGE);
    if (oidcService.isRedirectOidcLoginUrl()) {
        modelAndView.setView(new RedirectView(oidcService.getOidcLoginUrl(), true, false));
    } else {
        modelAndView.addObject("loginMod", oidcService.getLoginMod().name());
        modelAndView.addObject("oidcLoginUrl", oidcService.getOidcLoginUrl());
    }
    return modelAndView;
}

目前的策略，如果配置了登錄模式為 onlyOidc ，則跳轉登錄頁時，直接 302 到 OIDC 授權頁，否則，將登錄模式，和 OIDC 授權頁傳遞給前端，由前端控制展示的 UI

Leave a Reply

Your email address will not be published. Required fields are marked *