Docs: document the access-token vs ID-token `aud` convention #30

New issue

Closed

opened 2026-05-25 14:19:15 +00:00 by navicore · 1 comment

navicore commented

2026-05-25 14:19:15 +00:00

Owner

Background

anz uses two different aud conventions across the two JWTs it issues:

Access token → aud = "https://auth.example.com/realms/<realm>" (the realm URL, i.e. the resource-server identifier). This follows RFC 9068 (JWT Profile for OAuth 2.0 Access Tokens).
ID token → aud = "<client_id>" (the relying party). This is the standard OIDC convention.

Both are correct. Both are common. But the difference is a foot-gun for anyone configuring a resource server's audience check, because the natural assumption ("aud is just the client_id") is wrong for access tokens.

Encountered

During the navinote integration I configured the resource server with audiences=["navinote-pwa", "navinote-sync"]. Every authenticated request returned 401. The fix was changing the audience allow-list to the realm URL — the navinote-server is now configured with a single audience: https://auth.navicore.tech/realms/homelab. Cost about 30 minutes of decoding tokens to figure out.

Proposed

A two-line note in docs/ARCHITECTURE.md near the JWT contract section (or in the README under "OIDC Endpoints") clarifying:

Access tokens carry the realm URL as aud (RFC 9068 convention) — the resource server should validate against this, not the client_id. ID tokens use client_id as aud per standard OIDC.

That's enough to save the next integrator.

## Background anz uses two different `aud` conventions across the two JWTs it issues: - **Access token** → `aud = "https://auth.example.com/realms/<realm>"` (the realm URL, i.e. the resource-server identifier). This follows [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068) (JWT Profile for OAuth 2.0 Access Tokens). - **ID token** → `aud = "<client_id>"` (the relying party). This is the standard OIDC convention. Both are correct. Both are common. But the difference is a foot-gun for anyone configuring a resource server's audience check, because the natural assumption (\"aud is just the client_id\") is wrong for access tokens. ## Encountered During the navinote integration I configured the resource server with `audiences=["navinote-pwa", "navinote-sync"]`. Every authenticated request returned 401. The fix was changing the audience allow-list to the realm URL — the navinote-server is now configured with a single audience: `https://auth.navicore.tech/realms/homelab`. Cost about 30 minutes of decoding tokens to figure out. ## Proposed A two-line note in `docs/ARCHITECTURE.md` near the JWT contract section (or in the README under "OIDC Endpoints") clarifying: > Access tokens carry the realm URL as `aud` (RFC 9068 convention) — the resource server should validate against this, not the `client_id`. ID tokens use `client_id` as `aud` per standard OIDC. That's enough to save the next integrator.

navicore referenced this issue

2026-05-25 14:20:20 +00:00

Docs: add a browser SPA integration example #31

navicore added the

documentation

label

2026-05-25 14:27:05 +00:00

navicore referenced this issue from a commit

2026-05-25 14:47:38 +00:00

● The design is implemented and verified. just ci passes — fmt, clippy (warnings-as-errors), 109 tests, release

navicore referenced this issue

2026-05-25 14:47:46 +00:00