document the "aud" and "iss" token verification options

The expected audience and issuer values became configurable in liboauth2
("aud="/"iss=" on OAuth2TokenVerify), but nothing here said so. Add them to the
options list and to the per-type option columns, and note that configuring a
value defaults the matching "verify.<claim>" to "required" - the "verify.*"
options only ever expressed *how* strictly a claim is validated, so without an
expected value there is nothing to match against and the claim is not checked.

Also document "verify.aud", which was missing from the list entirely, and record
that the "metadata" type now defaults "verify.iss" to "required" since it takes
its expected issuer from the metadata document.

Add a sample and a note recommending that a resource server bind tokens to
itself with "aud" whenever the Authorization Server signs tokens for more than
one resource with the same key set: without it any validly signed token is
accepted, including one issued for a different resource server.

Author: zandbelt

oauth2.conf

@@ -73,6 +73,11 @@
 #
 #   OAuth2TokenVerify introspect https://pingfed:9031/as/introspect.oauth2 introspect.ssl_verify=false&introspect.auth=client_secret_basic&client_id=rs0&client_secret=2Federate
 #   OAuth2TokenVerify jwks_uri https://pingfed:9031/ext/one jwks_uri.ssl_verify=false
+#   OAuth2TokenVerify jwks_uri https://pingfed:9031/ext/one aud=https://my-api.example.com&iss=https://pingfed:9031
+#
+# Binding the token to this resource server with "aud" is strongly recommended whenever the Authorization
+# Server signs tokens for more than one resource with the same key (set): without it any validly signed
+# token is accepted, including one issued for a different resource server entirely. See "aud" below.
 #
 # Types:
 #
@@ -82,29 +87,39 @@
 #                                                                 introspect.params, type, introspect.http_retries, introspect.http_retry_interval
 # jwks_uri   <url>      JWKS URI that serves the public keys      jwks_uri.ssl_verify, jwks_uri.cache, jwks_uri.expiry, type, jwks_uri.http_retries, 
 #                                                                 jwks_uri.http_retry_interval,
-#                                                                 verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after
-# jwk        <json>     JWK JSON representation of a symmetric    kid (overrides kid in JWK), verify.iss, verify.exp, verify.iat, type,
+#                                                                 aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after
+# jwk        <json>     JWK JSON representation of a symmetric    kid (overrides kid in JWK), aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, type,
 #                       key or a public key                       verify.iat.slack_before, verify.iat.slack_after
 # metadata   <url>      RFC8414 Authorization Server Metadata     metadata.ssl_verify, introspect.*, jwks_uri.*
-#                       URL that contains a JWKs URI in jwks_uri
-# plain      <string>   symmetric key (password) in plain text    kid, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
-# base64     <string>   base64-encoded symmetric key              kid, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
-# base64url  <string>   base64url-encoded symmetric key           kid, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
-# hex        <string>   hex-encoded symmetric key                 kid, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
-# pem        <string>   PEM formatted X.509 certificate           kid, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
+#                       URL that contains a JWKs URI in jwks_uri  NB: the expected issuer is taken from the metadata document, so verify.iss
+#                                                                 defaults to "required" for this type; an explicit verify.iss still wins
+# plain      <string>   symmetric key (password) in plain text    kid, aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
+# base64     <string>   base64-encoded symmetric key              kid, aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
+# base64url  <string>   base64url-encoded symmetric key           kid, aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
+# hex        <string>   hex-encoded symmetric key                 kid, aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
+# pem        <string>   PEM formatted X.509 certificate           kid, aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
 #                       that contains an RSA public key
-# pubkey     <string>   PEM formatted RSA public key              kid, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
+# pubkey     <string>   PEM formatted RSA public key              kid, aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after, type
 # eckey_uri  <url>      URL on wich the Elliptic Curve key is     eckey_uri.ssl_verify, eckey_uri.cache, eckey_uri.expiry,
-#                       published as a PEM (Amazon ALB specific)  verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after
+#                       published as a PEM (Amazon ALB specific)  aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after
 # aws_alb    <string>   ALB ARN                                   alb_base_url, aws_alb.ssl_verify, aws_alb.auth, aws_alb.cache, aws_alb.expiry
-#                                                                 verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after
+#                                                                 aud, iss, verify.aud, verify.iss, verify.exp, verify.iat, verify.iat.slack_before, verify.iat.slack_after
 #
 # OAuth2TokenVerify Options:
 #
 # <name>                   <value>                   <description>
 #
 # kid                      <string>                  JWK kid value to be found in JWT header
+# aud                      <string>                  the expected "aud" (audience) claim value: an identifier of this resource server. A JWT access token that
+#                                                    the Authorization Server issued for a different resource is then rejected, as required by RFC 9068 section 4.
+#                                                    Setting it defaults verify.aud to "required"; without it there is nothing to match against and the audience
+#                                                    is not checked at all
+# iss                      <string>                  the expected "iss" (issuer) claim value: the Authorization Server that must have issued the token.
+#                                                    Setting it defaults verify.iss to "required". For the "metadata" type it takes precedence over the issuer
+#                                                    discovered from the AS metadata document, and a mismatch between the two is logged as a warning
 # verify.iss               skip|optional|required    how to validate the "iss" claim in the JWT: skip it, verify if present, require claim to be present and validate
+# verify.aud               skip|optional|required    how to validate the "aud" claim in the JWT: skip it, verify if present, require claim to be present and validate;
+#                                                    only enforced when an expected audience is configured, see "aud" above
 # verify.exp               skip|optional|required    how to validate the "exp" claim in the JWT: skip it, verify if present, require claim to be present and validate
 # verify.iat               skip|optional|required    how to validate the "iat" claim in the JWT: skip it, verify if present, require claim to be present and validate
 # verify.iat.slack_before  <number>                  acceptable clock drift in seconds for the "iat" claim: anything issued before now-number will be rejected