nebraska: --oidc-audience is required from 4.0.0 - #698
Conversation
4960abb to
fb57baf
Compare
ervcz
changed the title
There was a problem hiding this comment.
🟡 Changes recommended
The updated doc still links to a moving blob/main migration guide and includes a JWT decode command that can be unreliable without base64url padding normalization.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Updates the Nebraska authorization documentation to reflect the Nebraska v4.0.0 OIDC change that requires configuring and passing --oidc-audience, helping operators avoid startup failures and unexpected 401s during upgrades.
Changes:
- Documented the v4.0.0 breaking requirement for
--oidc-audienceand its security motivation (GHSA-8535-v9q5-f7qp). - Added Keycloak instructions for adding an API audience (
aud) to access tokens via an Audience mapper. - Updated provider examples and the “required/optional flags” lists to include
--oidc-audience(and related migration flags).
File summaries
| File | Description |
|---|---|
| content/docs/latest/updates-releases/nebraska/authorization.md | Documents the v4.0.0 --oidc-audience requirement and adds provider-specific guidance + updated CLI examples. |
Review details
Suppressed comments (1)
content/docs/latest/updates-releases/nebraska/authorization.md:572
- This link to the OIDC Migration Guide also uses
blob/main. Since the surrounding text is specifically about upgrading for the v4.0.0 audience requirement, linking to the v4.0.0 ref avoids the guide changing underneath the docs.
- Add `--oidc-audience`. Required from v4.0.0 for every provider, not just
Auth0. Your provider has to put that value in the `aud` claim of access
tokens first, otherwise every API request returns 401.
3. See the full [OIDC Migration Guide](https://github.com/flatcar/nebraska/blob/main/docs/oidc-migration-guide.md) for detailed instructions.
- Files reviewed: 1/1 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| token really carries it before you start Nebraska: | ||
|
|
||
| ```bash | ||
| echo "<access-token>" | cut -d. -f2 | tr '_-' '/+' | base64 -d | jq .aud |
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-698.westeurope.1.azurestaticapps.net |
fb57baf to
0337ce7
Compare
There was a problem hiding this comment.
🔵 Needs a closer look
The newly added JWT decode command is likely to fail for valid JWTs due to missing base64url padding, which can mislead operators following the migration steps.
Review details
Suppressed comments (1)
content/docs/latest/updates-releases/nebraska/authorization.md:148
- The JWT decode command may fail for many valid access tokens because JWT segments are base64url-encoded without padding, while
base64 -doften expects proper=padding. Adding padding makes the example reliably work across token lengths.
echo "<access-token>" | cut -d. -f2 | tr '_-' '/+' | base64 -d | jq .aud
- Files reviewed: 1/1 changed files
- Comments generated: 0 new
- Review effort level: Lite
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-698.westeurope.1.azurestaticapps.net |
0337ce7 to
735f0a5
Compare
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-698.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
🟡 Changes recommended
The newly added JWT decoding command uses jq @base64d directly on base64url JWT payloads and can fail for common tokens unless base64url conversion/padding is applied.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Lite
| token really carries it before you start Nebraska: | ||
|
|
||
| ```bash | ||
| echo "<access-token>" | cut -d. -f2 | jq -R '@base64d | fromjson | .aud' |
4.0.0 validates the aud claim of OIDC access tokens and refuses to start without --oidc-audience. The page listed the flag as optional and Auth0 specific, and four of the five provider walkthroughs gave a start command that will not run on 4.0.0. Signed-off-by: Ervin Rácz <ervin.racz@protonmail.com>
Keycloak was documented inside the generic OIDC heading while the other four providers each had their own section, so it read as the default rather than one of five. The Required and Optional flag lists sat in Keycloak's start section, where readers following Dex, Okta, Azure AD or Auth0 never reached them. - lift the flag lists into a generic "Nebraska configuration flags" section - promote Keycloak to a top-level provider section - name every start section "Start Nebraska with <provider>" - give Auth0 a start section instead of burying the command in a numbered list - rename duplicated headings that collided as anchors Signed-off-by: Ervin Rácz <ervin.racz@protonmail.com>
735f0a5 to
4d4afcd
Compare
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-698.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
🔵 Needs a closer look
The added JWT decoding one-liner uses jq @base64d on a base64url JWT segment, which can fail or mislead operators during troubleshooting.
Review details
Suppressed comments (2)
content/docs/latest/updates-releases/nebraska/authorization.md:173
- JWT payloads are base64url-encoded (often without padding). Decoding the middle segment with
jq -R '@base64d …'can fail or produce incorrect results for many real tokens. Use a base64url-safe decode when checking theaudclaim.
echo "<access-token>" | cut -d. -f2 | jq -R '@base64d | fromjson | .aud'
content/docs/latest/updates-releases/nebraska/authorization.md:531
- Same as above: JWT payloads are base64url-encoded (often without padding), so
jq -R '@base64d …'may fail/produce incorrect output when troubleshooting 401s. Use a base64url-safe decode for theaudclaim.
echo "<access-token>" | cut -d. -f2 | jq -R '@base64d | fromjson | .aud'
- Files reviewed: 1/1 changed files
- Comments generated: 0 new
- Review effort level: Lite
Nebraska 4.0.0 requires
--oidc-audiencein OIDC mode and will not start without it, so the authorization page needs the new flag documented before operators upgrade.Background in GHSA-8535-v9q5-f7qp and the migration guide.