From c92eabfc39f8ef1913be5baa5bd956b1babbf066 Mon Sep 17 00:00:00 2001 From: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com> Date: Wed, 22 Apr 2026 17:23:49 +0200 Subject: [PATCH] Document JWT claim requirements for selfhosted OAuth applications Adapted from mike/jwt-claim-requirements: adds warning about sub claim being critical for all OAuth apps, with specific x-user-subject error message. Most content from the original PR was already incorporated in the Entra ID auth rewrite (mike/selfhosted-auth-docs-v2). Co-Authored-By: Claude Opus 4.6 (1M context) --- content/deployment/selfhosted/authentication.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/deployment/selfhosted/authentication.md b/content/deployment/selfhosted/authentication.md index 795bde0ba..713fd36cd 100644 --- a/content/deployment/selfhosted/authentication.md +++ b/content/deployment/selfhosted/authentication.md @@ -130,6 +130,9 @@ Your IdP must emit a claim that maps to the `identitytype` concept, with values > [!WARNING] > The `sub` claim value must be **stable and unique** per principal. If your IdP returns different `sub` values for the same user across token refreshes, authorization and ownership tracking will break. +> [!WARNING] +> The `sub` claim is critical for **all** OAuth applications, including service-to-service (App 3), operator (App 4), and EAGER (App 5). If your IdP does not include `sub` in client credentials tokens, service-to-service authentication will fail with `x-user-subject header not found`. Verify that all five applications produce tokens with a `sub` claim before deploying. + **Your IdP must emit a `sub` claim in all access tokens.** If your IdP's client_credentials tokens use a different claim for the caller identity (or omit `sub` entirely), configure `subjectClaimNames` to specify a fallback chain: ```yaml