Spring Security - OAuth2 Process

Let us walk throught OAuth2 Authorization Process. Have some basic understanding the classes mentioned in Spring Security OAuth2 Core Classes will help you understanding OAuth2 process in this post.

When the user logs in using Github using auhtorization code grant flow. The following three classes are responsible for handling the user login.

• OAuth2LoginAuthenticationFilter
• OAuth2LoginAuthenticationProvider
• DefaultOAuth2UserService

OAuth2LoginAuthenticationFilter

• This authentication Filter handles the processing of an OAuth 2.0 Authorization Response for the authorization code grant flow and delegates an OAuth2LoginAuthenticationToken to the AuthenticationManager to log in the End-User.
• javadoc
• Source Code

attemptAuthentication code

@Override
public Authentication attemptAuthentication(HttpServletRequest request, HttpServletResponse response)
		throws AuthenticationException {

	MultiValueMap<String, String> params = OAuth2AuthorizationResponseUtils.toMultiMap(request.getParameterMap());
	if (!OAuth2AuthorizationResponseUtils.isAuthorizationResponse(params)) {
		OAuth2Error oauth2Error = new OAuth2Error(OAuth2ErrorCodes.INVALID_REQUEST);
		throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
	}

	OAuth2AuthorizationRequest authorizationRequest =
			this.authorizationRequestRepository.removeAuthorizationRequest(request, response);
	if (authorizationRequest == null) {
		OAuth2Error oauth2Error = new OAuth2Error(AUTHORIZATION_REQUEST_NOT_FOUND_ERROR_CODE);
		throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
	}

	String registrationId = authorizationRequest.getAttribute(OAuth2ParameterNames.REGISTRATION_ID);
	ClientRegistration clientRegistration = this.clientRegistrationRepository.findByRegistrationId(registrationId);
	if (clientRegistration == null) {
		OAuth2Error oauth2Error = new OAuth2Error(CLIENT_REGISTRATION_NOT_FOUND_ERROR_CODE,
				"Client Registration not found with Id: " + registrationId, null);
		throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
	}
	String redirectUri = UriComponentsBuilder.fromHttpUrl(UrlUtils.buildFullRequestUrl(request))
			.replaceQuery(null)
			.build()
			.toUriString();
	OAuth2AuthorizationResponse authorizationResponse = OAuth2AuthorizationResponseUtils.convert(params, redirectUri);

	Object authenticationDetails = this.authenticationDetailsSource.buildDetails(request);
	OAuth2LoginAuthenticationToken authenticationRequest = new OAuth2LoginAuthenticationToken(
			clientRegistration, new OAuth2AuthorizationExchange(authorizationRequest, authorizationResponse));
	authenticationRequest.setDetails(authenticationDetails);

	OAuth2LoginAuthenticationToken authenticationResult =
		(OAuth2LoginAuthenticationToken) this.getAuthenticationManager().authenticate(authenticationRequest);

	OAuth2AuthenticationToken oauth2Authentication = new OAuth2AuthenticationToken(
		authenticationResult.getPrincipal(),
		authenticationResult.getAuthorities(),
		authenticationResult.getClientRegistration().getRegistrationId());
	oauth2Authentication.setDetails(authenticationDetails);

	OAuth2AuthorizedClient authorizedClient = new OAuth2AuthorizedClient(
		authenticationResult.getClientRegistration(),
		oauth2Authentication.getName(),
		authenticationResult.getAccessToken(),
		authenticationResult.getRefreshToken());

	this.authorizedClientRepository.saveAuthorizedClient(authorizedClient, oauth2Authentication, request, response);

	return oauth2Authentication;
}

Process

1. Create OAuth2LoginAuthenticationToken as authentication request
2. Delegate authentication to AuthenticationManager. OAuth2LoginAuthenticationToken is passed as parameter
3. Create OAuth2AuthenticationToken from the AuthenticationManager.authenticate(…) method call result
4. Create OAuth2AuthorizedClient
5. Save OAuth2AuthorizedClient to authorizedClientRepository
6. Return OAuth2AuthenticationToken

There are providers used by AuthenticationManager for OAuth2

• OAuth2LoginAuthenticationProvider
• OidcAuthorizationCodeAuthenticationProvider

If the scope contains “openid” then OidcAuthorizationCodeAuthenticationProvider will be used to process the authentication. If not, then OAuth2LoginAuthenticationProvider will be used.

We will analyze OAuth2LoginAuthenticationProvider class only.

OAuth2LoginAuthenticationProvider

• An implementation of an AuthenticationProvider for OAuth 2.0 Login, which leverages the OAuth 2.0 Authorization Code Grant Flow.
• Javadoc
• Source Code

OAuth2LoginAuthenticationProvider.authenticate() method

@Override
public Authentication authenticate(Authentication authentication) throws AuthenticationException {
	OAuth2LoginAuthenticationToken authorizationCodeAuthentication =
		(OAuth2LoginAuthenticationToken) authentication;

	// Section 3.1.2.1 Authentication Request - https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
	// scope
	// 		REQUIRED. OpenID Connect requests MUST contain the "openid" scope value.
	if (authorizationCodeAuthentication.getAuthorizationExchange()
		.getAuthorizationRequest().getScopes().contains("openid")) {
		// This is an OpenID Connect Authentication Request so return null
		// and let OidcAuthorizationCodeAuthenticationProvider handle it instead
		return null;
	}

	OAuth2AccessTokenResponse accessTokenResponse;
	try {
		OAuth2AuthorizationExchangeValidator.validate(
				authorizationCodeAuthentication.getAuthorizationExchange());

		accessTokenResponse = this.accessTokenResponseClient.getTokenResponse(
				new OAuth2AuthorizationCodeGrantRequest(
						authorizationCodeAuthentication.getClientRegistration(),
						authorizationCodeAuthentication.getAuthorizationExchange()));

	} catch (OAuth2AuthorizationException ex) {
		OAuth2Error oauth2Error = ex.getError();
		throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
	}

	OAuth2AccessToken accessToken = accessTokenResponse.getAccessToken();
	Map<String, Object> additionalParameters = accessTokenResponse.getAdditionalParameters();

	OAuth2User oauth2User = this.userService.loadUser(new OAuth2UserRequest(
			authorizationCodeAuthentication.getClientRegistration(), accessToken, additionalParameters));

	Collection<? extends GrantedAuthority> mappedAuthorities =
		this.authoritiesMapper.mapAuthorities(oauth2User.getAuthorities());

	OAuth2LoginAuthenticationToken authenticationResult = new OAuth2LoginAuthenticationToken(
		authorizationCodeAuthentication.getClientRegistration(),
		authorizationCodeAuthentication.getAuthorizationExchange(),
		oauth2User,
		mappedAuthorities,
		accessToken,
		accessTokenResponse.getRefreshToken());
	authenticationResult.setDetails(authorizationCodeAuthentication.getDetails());

	return authenticationResult;
}

• this.accessTokenResponseClient.getTokenResponse(...) will take the Authorization Code and exchange with Authorization Server to get the access token.
• UserService(DefaultOAuth2UserService in this case) will call UserInfo endpoint and then create the user and put it in Authentication object.

DefaultOAuth2UserService

• DefaultOAuth2UserService is an implementation of UserService. Its loadUser method calls UserInfo Endpoint and retrieve user info. Finally create a new OAuth2User and return it.
• Javadoc
• Source Code

DefaultOAuth2UserService.loadUser method

@Override
public OAuth2User loadUser(OAuth2UserRequest userRequest) throws OAuth2AuthenticationException {
	Assert.notNull(userRequest, "userRequest cannot be null");

	if (!StringUtils.hasText(userRequest.getClientRegistration().getProviderDetails().getUserInfoEndpoint().getUri())) {
		OAuth2Error oauth2Error = new OAuth2Error(
			MISSING_USER_INFO_URI_ERROR_CODE,
			"Missing required UserInfo Uri in UserInfoEndpoint for Client Registration: " +
				userRequest.getClientRegistration().getRegistrationId(),
			null
		);
		throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
	}
	String userNameAttributeName = userRequest.getClientRegistration().getProviderDetails()
			.getUserInfoEndpoint().getUserNameAttributeName();
	if (!StringUtils.hasText(userNameAttributeName)) {
		OAuth2Error oauth2Error = new OAuth2Error(
			MISSING_USER_NAME_ATTRIBUTE_ERROR_CODE,
			"Missing required \"user name\" attribute name in UserInfoEndpoint for Client Registration: " +
				userRequest.getClientRegistration().getRegistrationId(),
			null
		);
		throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
	}

	RequestEntity<?> request = this.requestEntityConverter.convert(userRequest);

	ResponseEntity<Map<String, Object>> response;
	try {
		response = this.restOperations.exchange(request, PARAMETERIZED_RESPONSE_TYPE);
	} catch (OAuth2AuthorizationException ex) {
		OAuth2Error oauth2Error = ex.getError();
		StringBuilder errorDetails = new StringBuilder();
		errorDetails.append("Error details: [");
		errorDetails.append("UserInfo Uri: ").append(
				userRequest.getClientRegistration().getProviderDetails().getUserInfoEndpoint().getUri());
		errorDetails.append(", Error Code: ").append(oauth2Error.getErrorCode());
		if (oauth2Error.getDescription() != null) {
			errorDetails.append(", Error Description: ").append(oauth2Error.getDescription());
		}
		errorDetails.append("]");
		oauth2Error = new OAuth2Error(INVALID_USER_INFO_RESPONSE_ERROR_CODE,
				"An error occurred while attempting to retrieve the UserInfo Resource: " + errorDetails.toString(), null);
		throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString(), ex);
	} catch (RestClientException ex) {
		OAuth2Error oauth2Error = new OAuth2Error(INVALID_USER_INFO_RESPONSE_ERROR_CODE,
				"An error occurred while attempting to retrieve the UserInfo Resource: " + ex.getMessage(), null);
		throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString(), ex);
	}

	Map<String, Object> userAttributes = response.getBody();
	Set<GrantedAuthority> authorities = new LinkedHashSet<>();
	authorities.add(new OAuth2UserAuthority(userAttributes));
	OAuth2AccessToken token = userRequest.getAccessToken();
	for (String authority : token.getScopes()) {
		authorities.add(new SimpleGrantedAuthority("SCOPE_" + authority));
	}

	return new DefaultOAuth2User(authorities, userAttributes, userNameAttributeName);
}