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

DefaultOAuth2UserService.getUserNameAttributeName requires a user name attribute name configured on UserInfoEndpoint; this attribute selects which claim in the UserInfo JSON response becomes the principal name and is used to build the OAuth2UserAuthority. When it is missing/blank, the service throws OAuth2AuthenticationException with code 'missing_user_name_attribute' because it cannot determine the user's name key.

Source

Thrown at oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DefaultOAuth2UserService.java:189

	private String getUserNameAttributeName(OAuth2UserRequest userRequest) {
		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());
		}
		return userNameAttributeName;
	}

	private Collection<GrantedAuthority> getAuthorities(OAuth2AccessToken token, Map<String, Object> attributes,
			String userNameAttributeName) {
		Collection<GrantedAuthority> authorities = new LinkedHashSet<>();
		authorities.add(new OAuth2UserAuthority(attributes, userNameAttributeName));
		for (String authority : token.getScopes()) {
			authorities.add(new SimpleGrantedAuthority("SCOPE_" + authority));
		}
		return authorities;
	}

	/**
	 * Sets the {@link Converter} used for converting the {@link OAuth2UserRequest} to a
	 * {@link RequestEntity} representation of the UserInfo Request.
	 * @param requestEntityConverter the {@link Converter} used for converting to a

View on GitHub (pinned to 96852e8860)

Solutions

1. Set the user name attribute to a claim the UserInfo response actually returns: spring.security.oauth2.client.provider.<id>.user-name-attribute=sub (or programmatically userInfoEndpoint().userNameAttributeName("sub")).
2. Check the provider's UserInfo response (curl with a token) and pick an existing top-level claim key such as sub, email, preferred_username, login, or id.
3. If using issuer-uri discovery, verify the discovered end_session/userinfo metadata includes user_name_attribute_name; otherwise set it manually.
4. Add a startup check of ClientRegistrations to fail fast on missing userNameAttributeName.

Example fix

// before
ClientRegistration.withRegistrationId("myidp")
    .userInfoEndpoint() // no userNameAttributeName
    .and()...

// after
ClientRegistration.withRegistrationId("myidp")
    ...
    .userInfoEndpoint()
        .uri("https://idp.example.com/userinfo")
        .userNameAttributeName("sub")
        .and()
    .build();

Map<String,Object> claims = fetchUserInfoOnce(token); // one-off check
if (!claims.containsKey("sub")) {
    throw new IllegalStateException("Provider does not return 'sub'; pick an existing claim for user-name-attribute");
}

catch (OAuth2AuthenticationException ex) {
    if ("missing_user_name_attribute".equals(ex.getError().getErrorCode())) {
        // set user-name-attribute for this registration before redeploying
    }
}

When it happens

Trigger: ClientRegistration has a valid user-info-uri but userInfoEndpoint().userNameAttributeName() is null/empty when loadUser runs for the user-info flow.

Common situations: Spring Boot autoconfig can't infer user-name-attribute for unknown providers, leaving it unset; manual ClientRegistration code omits userNameAttributeName; providers using non-standard keys (e.g. 'login', 'email', 'sub') where the developer assumed a default exists.

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
• invalid_user_info_response
• missing_user_info_uri
• missing_user_name_attribute
• invalid_user_info_response

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