From fd127f449c97e345c0f522b0a9974b1b2b8e215d Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Wed, 30 Jul 2025 05:14:43 -0500 Subject: [PATCH] docs: correct order of jwt claims sections --- docs/references/auth.rst | 37 +++++++++++++++++-------------- docs/references/configuration.rst | 2 +- 2 files changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/references/auth.rst b/docs/references/auth.rst index e3cfb2df9..5128c7b12 100644 --- a/docs/references/auth.rst +++ b/docs/references/auth.rst @@ -168,12 +168,28 @@ It goes as follows: - If the JWT does not have a ``kid`` parameter, then PostgREST will validate the token against each JWK in the :ref:`jwt-secret`. -.. _jwt_aud_verification: +.. _jwt_claims_validation: -``aud`` verification -~~~~~~~~~~~~~~~~~~~~ +JWT Claims Validation +--------------------- -PostgREST has built-in verification of the `JWT audience claim `_. +Time-Based claims validation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The time-based JWT claims specified in `RFC 7519 `_ are validated: + +- ``exp`` Expiration Time +- ``iat`` Issued At +- ``nbf`` Not Before + +We allow a 30-second clock skew when validating the above claims. In other words, we give an extra 30 seconds before the JWT is rejected if there is a slight discrepancy in the timestamps. + +.. _jwt_aud: + +``aud`` validation +~~~~~~~~~~~~~~~~~~ + +PostgREST has built-in validation of the `JWT audience claim `_. It works this way: - If :ref:`jwt-aud` is not set (the default), PostgREST identifies with all audiences and allows the JWT for any ``aud`` claim. @@ -184,19 +200,6 @@ It works this way: + If the match fails or if the ``aud`` value is not a string or array of strings, then the token will be rejected with a :ref:`401 Unauthorized ` error. + If the ``aud`` key **is not present** or if its value is ``null`` or ``[]``, PostgREST will interpret this token as allowed for all audiences and will complete the request. -.. _jwt_claims_validation: - -JWT Claims Validation ---------------------- - -The time-based JWT claims specified in `RFC 7519 `_ are validated: - -- ``exp`` Expiration Time -- ``iat`` Issued At -- ``nbf`` Not Before - -We allow a 30-second clock skew when validating the above claims. In other words, we give an extra 30 seconds before the JWT is rejected if there is a slight discrepancy in the timestamps. - .. _jwt_caching: JWT Cache diff --git a/docs/references/configuration.rst b/docs/references/configuration.rst index d93abfd5c..fbdcfb9a3 100644 --- a/docs/references/configuration.rst +++ b/docs/references/configuration.rst @@ -603,7 +603,7 @@ jwt-aud **In-Database** pgrst.jwt_aud =============== ================================= - Specifies an audience for the JWT ``aud`` claim. See :ref:`jwt_aud_verification`. + Specifies an audience for the JWT ``aud`` claim. See :ref:`jwt_aud`. .. _jwt-role-claim-key: