How to Configure OIDC for OpenSearch in Your Homelab

TL;DR

This guide addresses a common issue when integrating OpenSearch with OpenID Connect (OIDC) and Single Sign-On (SSO) providers, such as Authentik. The primary bottleneck is often the default header size limit in OpenSearch, which chokes on large JWT access tokens.

The Setup: What’s in my Homelab

I run a small K3S cluster in my home office. The lab serves as a testing ground for new tech I want to try out. It also provides my family with a media server, photo backups, and a personal document cloud. The setup consists mostly of declarative Kubernetes manifests, with the Helm controller manifests managing all of my apps. 

Over the last year, I’ve added a network observability stack built around Mermin (Elastiflow’s network observability tooling). I use OpenSearch for storage and OpenSearch Dashboards as my UI. At first, I used a typical admin user/password setup, but I’ve been wanting to log in to OpenSearch with my SSO tooling just like all of my other services in my homelab. 

Most homelab OIDC users tend to pick tools like Authelia, Authentik, or Keycloak for their IDP. I wanted something that could plug-and-play with my existing Kubernetes manifests setup, so Authentik was an easy choice. I added the Helm chart, deployed it, and then added all of my applications and providers as needed.

The Challenge with OpenSearch + OIDC

I wasn’t expected to face a challenge when setting up OICD for OpenSearch. In my mind, I thought “this is easy, just point OpenSearch dashboards at Authentik’s discovery URL, hand it a client ID and secret, set a redirect URL, and I’ll be done!” But, no matter what I did, I couldn’t complete the login flow. 

OpenSearch sits behind OpenSearch Dashboards for the security plugin flow. With OpenID Connect, I learned it’s possible to send Authorization headers much larger than I had originally expected. JWT access tokens can get pretty long. Unbeknownst to me, OpenSearch’s HTTP layer enforces a default max header size out of the box. If your token is longer than the default size, you get a generic-looking bad request page from Authentik. Unfortunately, neither Authentik nor OpenSearch Dashboards displays a friendly error message indicating that your header is too large.

The Fix: 

After troubleshooting, I noticed the token appeared incomplete during the login flow. The OpenSearch documentation provides a link towards the bottom of the page that states 

1
If the ID token from the IdP is especially large, OpenSearch may throw a server log authentication error indicating that the HTTP header is too large. In this case, you can increase the value for the http.max_header_size setting in the opensearch.yml file.

I increased the default (16kb) to 256kb, and that did the trick:

1
2
3
yaml
# OIDC Bearer tokens can exceed default header limits
http.max_header_size: 256kb

Raising the limit stopped the backend from choking on otherwise normal OIDC traffic. I completed the login flow. The glorious “Login with Authentik” Button was mine!

Checklist: OpenSearch Dashboard Configuration

Along my journey in OpenSearch OIDC, I found a few OpenSearch Dashboard settings that are easy to skip when you first turn on OIDC. I had to ensure the following items were set before everything worked the way I expected:

• Allowlisting headers. OpenSearch Dashboards has to forward security-related headers to OpenSearch (opensearch.requestHeadersAllowlist).

• Multiple auth types. I left basic auth on next to OIDC while I was still iterating (`multiple_auth_enabled`, `auth.type: [basicauth, openid]`). Useful for break-glass and testing access with your existing local user and password. Once you have OIDC working, though, I’d advise turning off multi-auth and using only the OIDC login flow.

• OIDC storage/cookies. Some setups need extra cookie space or prefix tuning (`openid.extra_storage.*`). I didn’t hit any of the cookie-size failures after fixing headers, but those knobs exist for a reason!

Closing Thoughts

I had Authentik working on my other services without drama, so I assumed OpenSearch would behave the same way. It mostly does, with one exception. The path through Dashboards means that large JWTs hit OpenSearch’s HTTP layer, and the stock header limit is easy to trip before anyone prints a useful error. Raising http.max_header_size was the unlock for me. If you’re working through a similar setup, I hope it helps you too.