correct: handle array values in JWT aud claim correctly

docs/references/auth.rst

@@ -166,10 +166,27 @@ PostgREST honors the following `JWT claims <https://datatracker.ietf.org/doc/htm
 - ``exp`` Expiration Time
 - ``iat`` Issued At
 - ``nbf`` Not Before
-- ``aud`` Audience, see :ref:`jwt-aud`
+- ``aud`` :ref:`Audience <jwt_aud_validation>`
 
 .. note::
-  PostgREST allows for a 30-second clock skew when validating the ``exp`` and ``iat`` claims. In other words, it gives an extra 30 seconds before the token is rejected if there is a slight discrepancy in the timestamps.
+  PostgREST allows for a 30-second clock skew when validating the ``exp``, ``iat`` and ``nbf`` claims.
+  In other words, it gives an extra 30 seconds before the token is rejected if there is a slight discrepancy in the timestamps.
+
+.. _jwt_aud_validation:
+
+JWT ``aud`` Claim Validation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+PostgREST has built-in validation of the `JWT audience claim <https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3>`_.
+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.
+- If :ref:`jwt-aud` is set to a specific audience, PostgREST will check if this audience is present in the ``aud`` claim:
+
+  + If the ``aud`` value is a JSON string, it will match it to the :ref:`jwt-aud`.
+  + If the ``aud`` value is a JSON array of strings, it will search every element for a match.
+  + 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 <pgrst303>` 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_role_claim_key_extract:
 

docs/references/configuration.rst

@@ -599,11 +599,7 @@ jwt-aud
   **In-Database** pgrst.jwt_aud
   =============== =================================
 
-  Specifies the `JWT audience claim <https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3>`_. If this claim is present in the client provided JWT then you must set this to the same value as in the JWT, otherwise verifying the JWT will fail.
-
-  .. warning::
-
-     Using this setting will only reject tokens with a different audience claim. Tokens **without** audience claim will still be accepted.
+    Specifies an audience for the JWT ``aud`` claim. See :ref:`jwt_aud_validation`.
 
 .. _jwt-role-claim-key: