spring-projects/spring-security · error · OAuth2AuthenticationException

missing_user_name_attribute

missing_user_name_attribute

Error message

Missing required "user name" attribute name in UserInfoEndpoint for Client Registration: ${registrationId}

What it means

DefaultReactiveOAuth2UserService.loadUser requires userNameAttributeName on UserInfoEndpoint to know which claim in the UserInfo JSON response identifies the end-user. When it is missing or blank, it throws OAuth2AuthenticationException with code 'missing_user_name_attribute' before building the WebClient request.

Source

Thrown at oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DefaultReactiveOAuth2UserService.java:111

				.getUserInfoEndpoint()
				.getUri();
			if (!StringUtils.hasText(userInfoUri)) {
				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());
			}
			AuthenticationMethod authenticationMethod = userRequest.getClientRegistration()
				.getProviderDetails()
				.getUserInfoEndpoint()
				.getAuthenticationMethod();
			WebClient.RequestHeadersSpec<?> requestHeadersSpec = getRequestHeaderSpec(userRequest, userInfoUri,
					authenticationMethod);
			// @formatter:off
			Mono<Map<String, Object>> userAttributes = requestHeadersSpec.retrieve()
					.onStatus(HttpStatusCode::isError, (response) ->
						parse(response)
							.map((userInfoErrorResponse) -> {
								String description = userInfoErrorResponse.getErrorObject().getDescription();
								OAuth2Error oauth2Error = new OAuth2Error(INVALID_USER_INFO_RESPONSE_ERROR_CODE, description,
									null);
								throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
							})
					)

View on GitHub (pinned to 96852e8860)

Solutions

1. Set user-name-attribute in provider config or userInfoEndpoint().userNameAttributeName("sub") matching a claim the provider returns.
2. Inspect the actual UserInfo JSON response to choose the correct claim key.
3. If using discovery via issuer-uri, confirm the provider metadata and add the attribute manually if not inferred.
4. Add startup validation of all ClientRegistrations for required fields.

Example fix

// before
spring.security.oauth2.client.provider.myidp.user-info-uri=https://idp.example.com/userinfo

// after
spring.security.oauth2.client.provider.myidp.user-info-uri=https://idp.example.com/userinfo
spring.security.oauth2.client.provider.myidp.user-name-attribute=sub

ClientRegistration reg = reactiveRepository.findByRegistrationId("myclient").block();
if (reg != null && !StringUtils.hasText(reg.getProviderDetails().getUserInfoEndpoint().getUserNameAttributeName())) {
    throw new IllegalStateException("reactive registration myclient is missing user-name-attribute");
}

catch (OAuth2AuthenticationException ex) {
    if ("missing_user_name_attribute".equals(ex.getError().getErrorCode())) {
        // add userInfoEndpoint().userNameAttributeName(...) for this registration
    }
}

When it happens

Trigger: Reactive OAuth2 login where the ClientRegistration has a valid user-info-uri but userInfoEndpoint().userNameAttributeName() is null/empty at loadUser time.

Common situations: Manual reactive ClientRegistration setup omitting userNameAttributeName; custom provider whose name claim differs (login, uid, preferred_username) and the developer assumed defaults; Spring Boot cannot infer the attribute for an unknown provider.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• missing_user_info_uri
• missing_user_info_uri
• missing_user_name_attribute
• invalid_scope
• oidc_provider_not_configured

AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10). Data as JSON: /api/errors/fbeaa2467a63ebcd. Report an issue: GitHub.