Spring Security OAuth2 源码分析（三） TokenServices

TokenGranter 获取 Token 的最后一步中, 调用了 tokenServices 的 createAccessToken 方法，源码如下:

protected OAuth2AccessToken getAccessToken(ClientDetails client, TokenRequest tokenRequest) {
    return tokenServices.createAccessToken(getOAuth2Authentication(client, tokenRequest));
}

为了进一步地了解 OAuth2AccessToken 的获取过程，本文将详细介绍
AuthorizationServerTokenServices 和 ResourceServerTokenServices。

1. AuthorizationServerTokenServices 接口

接口定义了三个方法: createAccessToken (创建访问令牌)、refreshAccessToken (刷新访问令牌)、getAccessToken (获取访问令牌)。接口源码如下:

/**
 * @author Ryan Heaton
 * @author Dave Syer
 */
public interface AuthorizationServerTokenServices {

    /**
     * Create an access token associated with the specified credentials.
     * @param authentication The credentials associated with the access token.
     * @return The access token.
     * @throws AuthenticationException If the credentials are inadequate.
     */
    OAuth2AccessToken createAccessToken(OAuth2Authentication authentication) throws AuthenticationException;

    /**
     * Refresh an access token. The authorization request should be used for 2 things (at least): to validate that the
     * client id of the original access token is the same as the one requesting the refresh, and to narrow the scopes
     * (if provided).
     * 
     * @param refreshToken The details about the refresh token.
     * @param tokenRequest The incoming token request.
     * @return The (new) access token.
     * @throws AuthenticationException If the refresh token is invalid or expired.
     */
    OAuth2AccessToken refreshAccessToken(String refreshToken, TokenRequest tokenRequest)
            throws AuthenticationException;

    /**
     * Retrieve an access token stored against the provided authentication key, if it exists.
     * 
     * @param authentication the authentication key for the access token
     * 
     * @return the access token or null if there was none
     */
    OAuth2AccessToken getAccessToken(OAuth2Authentication authentication);
}

它的实现类有 DefaultTokenServices, 下文将详细展开介绍。

2. ResourceServerTokenServices 接口

接口定义了两个方法: loadAuthentication (加载凭据)、readAccessToken (获取 access token 的详情)。接口源码如下:

public interface ResourceServerTokenServices {

    /**
     * Load the credentials for the specified access token.
     *
     * @param accessToken The access token value.
     * @return The authentication for the access token.
     * @throws AuthenticationException If the access token is expired
     * @throws InvalidTokenException if the token isn't valid
     */
    OAuth2Authentication loadAuthentication(String accessToken) throws AuthenticationException, InvalidTokenException;

    /**
     * Retrieve the full access token details from just the value.
     * 
     * @param accessToken the token value
     * @return the full access token with client id etc.
     */
    OAuth2AccessToken readAccessToken(String accessToken);
}

它的实现类有 RemoteTokenServices、DefaultTokenServices。

3. DefaultTokenServices

3.1 DefaultTokenServices 的配置

以下是 DefaultTokenServices 的关键属性:

属性	note
refreshTokenValiditySeconds	refresh_token 的有效时长 (秒), 默认 30 天
accessTokenValiditySeconds	access_token 的有效时长 (秒), 默认 12 小时
supportRefreshToken	是否支持 refresh token, 默认为 false
reuseRefreshToken	是否复用 refresh_token, 默认为 true (如果为 false, 每次请求刷新都会删除旧的 refresh_token, 创建新的 refresh_token)
tokenStore	token 储存器 (持久化容器) (下篇文章会介绍)
clientDetailsService	提供 client 详情的服务 (clientDetails 可持久化到数据库中或直接放在内存里)
accessTokenEnhancer	token 增强器, 可以通过实现 TokenEnhancer 以存放 additional information
authenticationManager	Authentication 管理者, 起到填充完整 Authentication的作用

在认证服务的 Endpoints 中, 使用的正是 DefaultTokenServices, 它为 DefaultTokenServices 提供了默认配置, 源码如下:

public final class AuthorizationServerEndpointsConfigurer {
    // 省略部分代码, 只看默认配置相关 ...
    private DefaultTokenServices createDefaultTokenServices() {
        DefaultTokenServices tokenServices = new DefaultTokenServices();
        tokenServices.setTokenStore(tokenStore());
        tokenServices.setSupportRefreshToken(true);
        tokenServices.setReuseRefreshToken(reuseRefreshToken);
        // 如果未配置, 则配置为 InMemoryClientDetailsService
        tokenServices.setClientDetailsService(clientDetailsService());
        tokenServices.setTokenEnhancer(tokenEnhancer());
        addUserDetailsService(tokenServices, this.userDetailsService);
        return tokenServices;
    }

    private TokenStore tokenStore() {
        // 如果未配置, 则创建
        if (tokenStore == null) {
            // 如果配置了 JwtAccessTokenConverter, 则创建 JwtTokenStore
            if (accessTokenConverter() instanceof JwtAccessTokenConverter) {
                this.tokenStore = new JwtTokenStore((JwtAccessTokenConverter) accessTokenConverter());
            }
            // 否则, 创建 InMemoryTokenStore
            else {
                this.tokenStore = new InMemoryTokenStore();
            }
        }
        return this.tokenStore;
    }

    private TokenEnhancer tokenEnhancer() {
        // 如果未配置 tokenEnhancer, 但配置了 JwtAccessTokenConverter, 则将这个 convert 返回
        if (this.tokenEnhancer == null && accessTokenConverter() instanceof JwtAccessTokenConverter) {
            tokenEnhancer = (TokenEnhancer) accessTokenConverter;
        }
        return this.tokenEnhancer;
    }
    // ...
}

实际业务场景研发可以通过配置 AuthorizationServerEndpointsConfigurer 以自定义 token 的持久化策略、token 的刷新机制等等。(下一篇文章将会具体介绍 TokenStore, 使我们更好地了解 token 的自定义存储)。

3.2 DefaultTokenServices - createAccessToken

如何创建 OAuth2AccessToken? 我们来读读它的源码:

    @Transactional
    public OAuth2AccessToken createAccessToken(OAuth2Authentication authentication) throws AuthenticationException {
        // 从 tokenStore 中获取现存的 accessToken
        OAuth2AccessToken existingAccessToken = tokenStore.getAccessToken(authentication);
        OAuth2RefreshToken refreshToken = null;
        // 如果 existingAccessToken 存在
        if (existingAccessToken != null) {
            // 看是否过期
            if (existingAccessToken.isExpired()) {
                // 既然 existingAccessToken 已经过期了, 则将对应的 refresh_token 和自己删掉
                if (existingAccessToken.getRefreshToken() != null) {
                    refreshToken = existingAccessToken.getRefreshToken();
                    tokenStore.removeRefreshToken(refreshToken);
                }
                tokenStore.removeAccessToken(existingAccessToken);
            }
            // 如果没过期则重新存到 tokenStore
            else {
                // Re-store the access token in case the authentication has changed
                tokenStore.storeAccessToken(existingAccessToken, authentication);
                return existingAccessToken;
            }
        }
        // 如果 existingAccessToken 不存在或者存在但是已经过期了, 往下走

        // 如果 existingAccessToken 不存在或过期了但它里边没有 refresh_token 信息, 则创建新的 refresh_token
        if (refreshToken == null) {
            refreshToken = createRefreshToken(authentication);
        }
        // 如果 existingAccessToken 过期了, 并且存在 refresh_token, 并且这个 refresh_token 也过期了, 则新创建一个 refresh_token
        else if (refreshToken instanceof ExpiringOAuth2RefreshToken) {
            ExpiringOAuth2RefreshToken expiring = (ExpiringOAuth2RefreshToken) refreshToken;
            if (System.currentTimeMillis() > expiring.getExpiration().getTime()) {
                refreshToken = createRefreshToken(authentication);
            }
        }
        // 创建新的 accessToken 并存到 tokenStore 中
        OAuth2AccessToken accessToken = createAccessToken(authentication, refreshToken);
        tokenStore.storeAccessToken(accessToken, authentication);
        // 将 accessToken 中的 refreshToken 也存到 tokenStore 中
        refreshToken = accessToken.getRefreshToken();
        if (refreshToken != null) {
            tokenStore.storeRefreshToken(refreshToken, authentication);
        }
        return accessToken;
    }

一个新的 OAuth2AccessToken 和 OAuth2RefreshToken 是如何创建的? 它的源码如下:

     private OAuth2RefreshToken createRefreshToken(OAuth2Authentication authentication) {
        // 如果属性 supportRefreshToken 为 false, 则返回 null
        if (!isSupportRefreshToken(authentication.getOAuth2Request())) {
            return null;
        }
        // token 的值其实是一个 UUID, 通过实例化 DefaultExpiringOAuth2RefreshToken 创建有时效性的 token
        int validitySeconds = getRefreshTokenValiditySeconds(authentication.getOAuth2Request());
        String value = UUID.randomUUID().toString();
        if (validitySeconds > 0) {
            return new DefaultExpiringOAuth2RefreshToken(value, new Date(System.currentTimeMillis()
                    + (validitySeconds * 1000L)));
        }
        return new DefaultOAuth2RefreshToken(value);
    }

    private OAuth2AccessToken createAccessToken(OAuth2Authentication authentication, OAuth2RefreshToken refreshToken) {
        DefaultOAuth2AccessToken token = new DefaultOAuth2AccessToken(UUID.randomUUID().toString());
        int validitySeconds = getAccessTokenValiditySeconds(authentication.getOAuth2Request());
        if (validitySeconds > 0) {
            token.setExpiration(new Date(System.currentTimeMillis() + (validitySeconds * 1000L)));
        }
        token.setRefreshToken(refreshToken);
        token.setScope(authentication.getOAuth2Request().getScope());
        // 如果属性 accessTokenEnhancer 不为空, 则拓展 token 的信息 (原理是给这个 token setAdditionalInformation)
        return accessTokenEnhancer != null ? accessTokenEnhancer.enhance(token, authentication) : token;
    }

看完这个新建 token 的过程, 我们大概知道刚刚那些配置属性的去处了。

3.3 DefaultTokenServices - getAccessToken

刚刚我们创建了 OAuth2AccessToken, 这时我们要怎么把它拿出来呢? 我们继续读源码:

    public OAuth2AccessToken getAccessToken(OAuth2Authentication authentication) {
        return tokenStore.getAccessToken(authentication);
    }

它是根据参数 OAuth2Authentication (身份验证令牌, 包含着用户信息, 下篇文章会着重介绍, 这里简单了解即可) 直接读取。

3.4 DefaultTokenServices - refreshAccessToken

我们创建的 token 是有时效性的, 所以为了让它不过期得刷新。我们通过源码看看 spring security 是如何刷新 token 的:

    @Transactional(noRollbackFor={InvalidTokenException.class, InvalidGrantException.class})
    public OAuth2AccessToken refreshAccessToken(String refreshTokenValue, TokenRequest tokenRequest)
            throws AuthenticationException {
        // 如果 supportRefreshToken 为 false, 则直接抛出异常
        if (!supportRefreshToken) {
            throw new InvalidGrantException("Invalid refresh token: " + refreshTokenValue);
        }
        // 根据 value 获取 OAuth2RefreshToken
        OAuth2RefreshToken refreshToken = tokenStore.readRefreshToken(refreshTokenValue);
        if (refreshToken == null) {
            throw new InvalidGrantException("Invalid refresh token: " + refreshTokenValue);
        }
        // 获取 OAuth2RefreshToken 中的 OAuth2Authentication
        OAuth2Authentication authentication = tokenStore.readAuthenticationForRefreshToken(refreshToken);
        if (this.authenticationManager != null && !authentication.isClientOnly()) {
            // The client has already been authenticated, but the user authentication might be old now, so give it a
            // chance to re-authenticate.
            Authentication user = new PreAuthenticatedAuthenticationToken(authentication.getUserAuthentication(), "", authentication.getAuthorities());
            user = authenticationManager.authenticate(user);
            Object details = authentication.getDetails();
            authentication = new OAuth2Authentication(authentication.getOAuth2Request(), user);
            authentication.setDetails(details);
        }
        // 从 OAuth2Authentication 中拿 clientId 看是否和 tokenRequest 中的一致, 如果不一致, 抛异常
        String clientId = authentication.getOAuth2Request().getClientId();
        if (clientId == null || !clientId.equals(tokenRequest.getClientId())) {
            throw new InvalidGrantException("Wrong client for this refresh token: " + refreshTokenValue);
        }

        // 通过 refreshToken 删除 accessToken (它们之间通过共同的 refreshTokenValue 联系着)
        tokenStore.removeAccessTokenUsingRefreshToken(refreshToken);
        // 如果 refresh_token 过期了, 则删掉并抛出异常
        if (isExpired(refreshToken)) {
            tokenStore.removeRefreshToken(refreshToken);
            throw new InvalidTokenException("Invalid refresh token (expired): " + refreshToken);
        }
        // 如果 refreshToken 没过期, 则创建新的 OAuth2Authentication
        authentication = createRefreshedAuthentication(authentication, tokenRequest);
        // 如果设置了属性 reuseRefreshToken 为false, 则删除旧的 refreshToken, 然后根据新的 OAuth2Authentication 创建新的 refreshToken
        if (!reuseRefreshToken) {
            tokenStore.removeRefreshToken(refreshToken);
            refreshToken = createRefreshToken(authentication);
        }
        // 创建新的 accessToken 并储存至 tokenStore (刷新)
        OAuth2AccessToken accessToken = createAccessToken(authentication, refreshToken);
        tokenStore.storeAccessToken(accessToken, authentication);
        // 如果选择不复用, 则储存新的 refreshToken
        if (!reuseRefreshToken) {
            tokenStore.storeRefreshToken(accessToken.getRefreshToken(), authentication);
        }
        return accessToken;
    }

3.5 DefaultTokenServices - readAccessToken

从 tokenStore 中直接读取 accessToken, 源码如下:

    public OAuth2AccessToken readAccessToken(String accessToken) {
        return tokenStore.readAccessToken(accessToken);
    }

3.6 DefaultTokenServices - loadAuthentication

接下来我们看看它是如何加载凭证信息的？

    public OAuth2Authentication loadAuthentication(String accessTokenValue) throws AuthenticationException,
            InvalidTokenException {
        // 根据 token value 从 tokenStore 中获取 OAuth2AccessToken
        OAuth2AccessToken accessToken = tokenStore.readAccessToken(accessTokenValue);
        // 校验 accessToken, 如果为空则抛异常, 如果过期了则删除并抛出异常
        if (accessToken == null) {
            throw new InvalidTokenException("Invalid access token: " + accessTokenValue);
        }
        else if (accessToken.isExpired()) {
            tokenStore.removeAccessToken(accessToken);
            throw new InvalidTokenException("Access token expired: " + accessTokenValue);
        }
        // 如果 accessToken 没问题, 则从中读取 OAuth2Authentication
        OAuth2Authentication result = tokenStore.readAuthentication(accessToken);
        if (result == null) {
            // in case of race condition
            throw new InvalidTokenException("Invalid access token: " + accessTokenValue);
        }
        // 校验 OAuth2Authentication 无误则将之返回 (根据 result 中 clientId 是否能获取到 client 信息, 如果不能则抛出异常)
        if (clientDetailsService != null) {
            String clientId = result.getOAuth2Request().getClientId();
            try {
                clientDetailsService.loadClientByClientId(clientId);
            }
            catch (ClientRegistrationException e) {
                throw new InvalidTokenException("Client not valid: " + clientId, e);
            }
        }
        return result;
    }

4. RemoteTokenServices

远程令牌服务, 它通过配置的 checkTokenEndpointUrl 请求得到凭证信息。源码如下:

    @Override
    public OAuth2Authentication loadAuthentication(String accessToken) throws AuthenticationException, InvalidTokenException {

        MultiValueMap<String, String> formData = new LinkedMultiValueMap<String, String>();
        formData.add(tokenName, accessToken);
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", getAuthorizationHeader(clientId, clientSecret));
        Map<String, Object> map = postForMap(checkTokenEndpointUrl, formData, headers);

        if (map.containsKey("error")) {
            logger.debug("check_token returned error: " + map.get("error"));
            throw new InvalidTokenException(accessToken);
        }

        // gh-838
        if (!Boolean.TRUE.equals(map.get("active"))) {
            logger.debug("check_token returned active attribute: " + map.get("active"));
            throw new InvalidTokenException(accessToken);
        }

        return tokenConverter.extractAuthentication(map);
    }

我们可以通过这种设计方法灵活地获取用户凭证信息。