Identity provider broker callback returns HTTP 502 for client-side input validation failures (missing state, missing code)

Before reporting an issue

• I have read and understood the above terms for submitting issues, and I understand that my issue may be closed without action if I do not follow them.

Area

identity-brokering

Describe the bug

When the OAuth2 broker callback endpoint (/realms/{realm}/broker/{alias}/endpoint) receives a request with a missing or unverifiable state parameter, or with neither code nor error present, Keycloak responds with HTTP 502 Bad Gateway.

Per RFC 9110, 502 means "the server, while acting as a gateway or proxy, received an invalid response from an inbound server". That is not what's happening here — Keycloak hasn't talked to the upstream IdP yet (or in the missing-state case, has no way to know which IdP to talk to). The failure is input validation on the incoming request from the user agent, which should be a 4xx (e.g. 400 Bad Request).

Affected code

services/src/main/java/org/keycloak/broker/oidc/AbstractOAuth2IdentityProvider.java

private Response errorIdentityProviderLogin(String message) {
    event.event(EventType.IDENTITY_PROVIDER_LOGIN);
    event.error(Errors.IDENTITY_PROVIDER_LOGIN_FAILURE);
    return ErrorPage.error(session, null, Response.Status.BAD_GATEWAY, message);
}

This helper is called from six sites inside Endpoint.authResponse(...). The six sites split into two semantic groups:

Line	Trigger	Cause	Correct status
716	state == null	Client-side / user-agent	400 Bad Request
739	No code and no error in callback	Client-side / user-agent	400 Bad Request
752	Token endpoint returned non-2xx	Upstream IdP failure	502 (correct)
772	IdentityBrokerException with message code	Usually upstream	502 (defensible)
775	Generic IdentityBrokerException	Usually upstream	502 (defensible)
778	Generic Exception	Unknown, could be either	500 Internal Server Error

The single helper conflates different failure modes under one status code.

Version

26.5.6

Regression

• The issue is a regression

Expected behavior

• Input validation failures should return 400 Bad Request.
• Upstream-IdP failures should continue to return 502 Bad Gateway.
• Unexpected/unhandled exceptions should return 500 Internal Server Error.

Actual behavior

• Input validation failures return 502 Bad Gateway.

How to Reproduce?

1. Configure any OIDC identity provider in a realm (alias = google, for example).
2. Issue a request directly to the broker callback endpoint without going through the login flow:

  curl -i "https://<keycloak-host>/realms/<realm>/broker/<alias>/endpoint?code=foo"

Keycloak's broker callback receives the request, finds no valid state cookie/parameter binding, and returns:

  HTTP/1.1 502 Bad Gateway

Anything else?

No response