Master Spring Security OAuth2: How OAuth2AuthorizationCodeAuthenticationProvider Retrieves Tokens

1. Introduction

In the previous Spring Security tutorial we covered how the redirectUri is called after a third‑party grants authorization and how the server exchanges the intermediate credential for a Token . That exchange is performed by OAuth2LoginAuthenticationProvider, which delegates the actual token request to OAuth2AuthorizationCodeAuthenticationProvider. This article clarifies the inner workings of that provider.

Note: The OAuth2 sections of this Spring Security series target Spring Security 5.x.

2. OAuth2AuthorizationCodeAuthenticationProvider

This class implements AuthenticationProvider for the OAuth 2.0 Authorization Code Grant flow. Understanding the provider is essential because it is the extension point for custom authentication mechanisms.

2.1 OAuth2AccessTokenResponseClient

The provider contains an OAuth2AccessTokenResponseClient that abstracts the details of calling the token endpoint ( tokenUri) to obtain a Token . Different OAuth 2.0 grant types can be supported by providing appropriate implementations.

In Spring Security 5 the default client is DefaultAuthorizationCodeTokenResponseClient. To use a custom implementation you can configure it via HttpSecurity:

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.oauth2Login()
        .tokenEndpoint()
        // inject custom OAuth2AccessTokenResponseClient
        .accessTokenResponseClient(authorizationCodeTokenResponseClient);
    // other configuration omitted
}

The default client retrieves the token with the following logic:

@Override
public OAuth2AccessTokenResponse getTokenResponse(OAuth2AuthorizationCodeGrantRequest authorizationCodeGrantRequest) {
    Assert.notNull(authorizationCodeGrantRequest, "authorizationCodeGrantRequest cannot be null");
    // 1. Build RequestEntity for tokenUri
    RequestEntity<?> request = this.requestEntityConverter.convert(authorizationCodeGrantRequest);
    ResponseEntity<OAuth2AccessTokenResponse> response;
    try {
        // 2. Use RestOperations to exchange request for token response
        response = this.restOperations.exchange(request, OAuth2AccessTokenResponse.class);
    } catch (RestClientException ex) {
        OAuth2Error oauth2Error = new OAuth2Error(INVALID_TOKEN_RESPONSE_ERROR_CODE,
            "An error occurred while attempting to retrieve the OAuth 2.0 Access Token Response: " + ex.getMessage(), null);
        throw new OAuth2AuthorizationException(oauth2Error, ex);
    }
    // 3. Parse response into OAuth2AccessTokenResponse
    OAuth2AccessTokenResponse tokenResponse = response.getBody();
    if (CollectionUtils.isEmpty(tokenResponse.getAccessToken().getScopes())) {
        // restore original scopes requested by the client
        tokenResponse = OAuth2AccessTokenResponse.withResponse(tokenResponse)
            .scopes(authorizationCodeGrantRequest.getClientRegistration().getScopes())
            .build();
    }
    return tokenResponse;
}

The process consists of three steps:

Assemble request parameters into a RequestEntity.

Send the request with RestOperations.

Parse the ResponseEntity and construct the token response.

If your OAuth 2.0 provider requires a special token‑retrieval flow, you can implement a custom OAuth2AccessTokenResponseClient.

3. Summary

The OAuth2AccessTokenResponseClient is the core component of OAuth2AuthorizationCodeAuthenticationProvider. Understanding its role and mechanism completes the OAuth 2.0 login flow. The authentication process can be summarized as:

Validate the unauthenticated OAuth2AuthorizationCodeAuthenticationToken.

Use OAuth2AccessTokenResponseClient to request the token from the OAuth 2.0 authorization server.

Assemble an authenticated OAuth2AuthorizationCodeAuthenticationToken and return it.