HTTP 502 errors in NGINX reverse proxy when processing large Microsoft Entra ID SSO headers

Question

We are experiencing intermittent HTTP 502 errors on our NGINX reverse proxy when users authenticate through Microsoft Entra ID Single Sign-On. During the authentication process, the authorization headers and identity claims returned by Microsoft Entra ID can become significantly larger than expected, causing the proxy to reject requests or fail to forward them correctly. Initial troubleshooting suggests that the issue may be related to NGINX buffer limitations, particularly when handling oversized request headers generated during SSO transactions. Could someone please provide guidance on how to safely increase the proxy_buffer_size and proxy_buffers settings in NGINX, and recommend any best practices for supporting large Microsoft Entra ID authentication headers without impacting proxy performance or stability ?

Answer 1

Check the NGINX error log first. The right setting depends on whether the large header is in a request from the browser or in a response from the upstream application.

If the log says “client sent too large header,” try increasing the client request buffers in the relevant http or server block. For example:

client_header_buffer_size 4k;

large_client_header_buffers 4 16k;

These are starting values to test, not universal limits. Each individual request header field must fit in one large buffer, so tune the size to the header you actually see.

proxy_buffer_size and proxy_buffers are for a response header received from the upstream application. If the log says “upstream sent too big header while reading response header from upstream,” tune those directives instead; they will not fix an oversized incoming browser request.

Also check which cookies and Entra claims are making the header large. Remove claims or attributes the application does not need, and only trust authentication headers from the intended proxy. Run nginx -t before reloading.

References:

NGINX client-header buffers: https://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers

NGINX upstream proxy buffers: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size

Microsoft Entra token claims and group overage: https://learn.microsoft.com/en-us/entra/identity-platform/access-token-claims-reference#groups-overage