Refuse access tokens at UserInfo and the credential endpoint as RFC 6750 section 3 has it

- Both protected resources answered every token problem with access_denied,
  and UserInfo's 401 carried no WWW-Authenticate challenge. A token which
  arrived and fails a check is now invalid_token (401) with the challenge
  ; a request which carried no token gets 401,
  the bare  challenge and no body (RFC 6750 section 3.1). A failure of
  the OP's own while it checks the token is server_error (500), on the split
  the introspection endpoint already makes; a claim the library can not read
  after the checks no longer escapes as an uncaught exception.
- An Authorization header under another scheme counts as no token instead of
  being read as one and refused as invalid, and the Bearer scheme name is
  matched case-insensitively (RFC 9110 section 11.1).
- The challenge and the body-less response belong to OidcServerException, so
  both error renderers carry them (forExceptionJson now returns a Response);
  the credential endpoint's own invalid_token answers carry the same
  challenge. The upgrade guide says what changes for UserInfo.

Author: cicnavi

docs/6-oidc-upgrade.md

@@ -702,6 +702,21 @@ answers any unexpected failure while processing a request in the token error
 format (`{"error": "server_error", ...}`, HTTP 500, with the cause in the OP
 log rather than in the response) instead of with SimpleSAMLphp's HTML error
 page.
+- The UserInfo endpoint now refuses an access token as RFC 6750 section 3 has
+it (OpenID Connect Core 1.0 section 5.3.3). A token which is expired, revoked,
+malformed or otherwise not accepted is answered with `invalid_token` instead of
+`access_denied`, still with HTTP 401, and the response now carries the
+`WWW-Authenticate: Bearer error="invalid_token"` challenge it lacked. A request
+which carries no access token is answered with HTTP 401, the bare
+`WWW-Authenticate: Bearer` challenge and no body, instead of an `access_denied`
+JSON error. An `Authorization` header under a scheme other than `Bearer`
+(`Basic`, say) now counts as no token, where it used to be read as one and
+refused as invalid, and the `Bearer` scheme name is now matched
+case-insensitively. A failure of the OP while it checks the token, such as a
+database which does not answer, is answered with `server_error` (HTTP 500)
+instead of a 401. A client which acts on the 401 status is unaffected; one
+which compares the `error` member with `access_denied` finds `invalid_token` for
+a refused token, and no body at all for a request which carried none.
 - The token introspection endpoint now tells an access token from a refresh
 token by the token itself, and no longer by `token_type_hint`. Previously a
 hint naming the other type answered `active: false` for a valid token, and an

src/Controllers/VerifiableCredentials/CredentialIssuerCredentialController.php

@@ -103,8 +103,9 @@ public function __construct(
      *
      * Every 401 this endpoint answers carries a Bearer challenge, whichever check made it a 401: HTTP
      * requires a challenge of any 401 (RFC 9110 section 15.5.2), and RFC 6750 section 3 has a protected
-     * resource send one when the access token is missing or does not authorize the request. The challenge
-     * names the scheme only; the error code is in the JSON body.
+     * resource send one when the access token is missing or does not authorize the request. A refused token
+     * is named in it (`error="invalid_token"`), and a request which carried none gets the scheme alone and no
+     * body (RFC 6750 section 3.1); both come with the refusal. A 401 from anywhere else gets the scheme alone.
      *
      * @throws \SimpleSAML\OpenID\Exceptions\JwsException
      * @throws \ReflectionException
@@ -119,13 +120,28 @@ public function credential(Request $request): Response
         }
 
         if ($response->getStatusCode() === 401 && !$response->headers->has('WWW-Authenticate')) {
-            $response->headers->set('WWW-Authenticate', 'Bearer');
+            $response->headers->set('WWW-Authenticate', OidcServerException::CHALLENGE_BEARER);
         }
 
         return $response;
     }
 
 
+    /**
+     * Refuses an access token which passed the resource server but can not buy a credential, as the resource
+     * server refuses one (RFC 6750 section 3.1): `invalid_token`, with the error named in the challenge too.
+     */
+    protected function invalidTokenResponse(string $description): Response
+    {
+        return $this->routes->newJsonErrorResponse(
+            'invalid_token',
+            $description,
+            401,
+            ['WWW-Authenticate' => OidcServerException::CHALLENGE_INVALID_TOKEN],
+        );
+    }
+
+
     /**
      * @throws \League\OAuth2\Server\Exception\OAuthServerException
      * @throws \SimpleSAML\Module\oidc\Server\Exceptions\OidcServerException
@@ -157,20 +173,12 @@ protected function issueCredential(Request $request): Response
 
         if (! $accessToken instanceof AccessTokenEntity) {
             $this->loggerService->error('Access token not found in repository.');
-            return $this->routes->newJsonErrorResponse(
-                'invalid_token',
-                'Access token not found.',
-                401,
-            );
+            return $this->invalidTokenResponse('Access token not found.');
         }
 
         if ($accessToken->isRevoked()) {
             $this->loggerService->error('Access token is revoked.', ['accessTokenId' => $accessToken->getIdentifier()]);
-            return $this->routes->newJsonErrorResponse(
-                'invalid_token',
-                'Access token is revoked.',
-                401,
-            );
+            return $this->invalidTokenResponse('Access token is revoked.');
         }
 
         if (
@@ -181,11 +189,7 @@ protected function issueCredential(Request $request): Response
                 'Access token is not intended for Verifiable Credential Issuance.',
                 ['flowType' => $flowType?->value, 'accessTokenId' => $accessToken->getIdentifier()],
             );
-            return $this->routes->newJsonErrorResponse(
-                'invalid_token',
-                'Access token is not intended for verifiable credential issuance.',
-                401,
-            );
+            return $this->invalidTokenResponse('Access token is not intended for verifiable credential issuance.');
         }
 
         // A token which can not buy a credential is refused as RFC 6750 section 3 has it (OpenID4VCI 1.0 section
@@ -201,11 +205,7 @@ protected function issueCredential(Request $request): Response
                 'to a client which is not registered.',
                 ['accessTokenState' => $accessToken->getState()],
             );
-            return $this->routes->newJsonErrorResponse(
-                'invalid_token',
-                'Issuer state missing in access token.',
-                401,
-            );
+            return $this->invalidTokenResponse('Issuer state missing in access token.');
         }
 
         // An issuer state on the token is not checked again here. The token endpoint spent it when it exchanged

src/Server/Exceptions/OidcServerException.php

@@ -16,6 +16,25 @@
 
 class OidcServerException extends OAuthServerException
 {
+    /**
+     * The challenge a protected resource sends with its refusal of the access token a request carried (RFC 6750
+     * section 3).
+     */
+    public const string CHALLENGE_INVALID_TOKEN = 'Bearer error="invalid_token"';
+
+    /**
+     * The challenge a protected resource sends to a request which carried no access token: the scheme alone, with
+     * no error code (RFC 6750 section 3.1).
+     */
+    public const string CHALLENGE_BEARER = 'Bearer';
+
+    /**
+     * The error type of a refusal for want of an access token. RFC 6750 defines no code for it, so it is never
+     * sent; it names the refusal in the log.
+     */
+    public const string ERROR_TYPE_MISSING_TOKEN = 'missing_token';
+
+
     /**
      * @var null|string
      */
@@ -26,6 +45,16 @@ class OidcServerException extends OAuthServerException
      */
     protected ?ResponseModeInterface $responseMode = null;
 
+    /**
+     * The WWW-Authenticate challenge the error response carries, or null for none.
+     */
+    protected ?string $wwwAuthenticate = null;
+
+    /**
+     * Whether the error response has a body.
+     */
+    protected bool $hasBody = true;
+
 
     private static function create(
         string $message,
@@ -204,6 +233,60 @@ public static function accessDenied(
     }
 
 
+    /**
+     * A protected resource refusing the access token a request carried: one which is expired, revoked, malformed
+     * or invalid for another reason (RFC 6750 section 3.1). The challenge names the error too, so that a client
+     * which reads only the header learns that its token was refused.
+     *
+     * @param string|null $hint
+     * @param \Throwable|null $previous
+     * @return static
+     */
+    public static function invalidToken(?string $hint = null, ?Throwable $previous = null): static
+    {
+        $e = self::create(
+            'The access token is expired, revoked, malformed, or invalid for other reasons.',
+            16,
+            'invalid_token',
+            401,
+            $hint,
+            null,
+            $previous,
+        );
+
+        $e->wwwAuthenticate = self::CHALLENGE_INVALID_TOKEN;
+
+        return $e;
+    }
+
+
+    /**
+     * A protected resource refusing a request which carried no access token. RFC 6750 section 3.1 answers it with
+     * the bare challenge and no error code: nothing the client sent was found wanting, and a client told that its
+     * token was refused, when it sent none, may throw away a working one. So the response has no body, and the
+     * error type and the message are for the log only.
+     *
+     * @param string|null $hint
+     * @return static
+     */
+    public static function missingToken(?string $hint = null): static
+    {
+        $e = self::create(
+            'The request carried no access token.',
+            17,
+            self::ERROR_TYPE_MISSING_TOKEN,
+            401,
+            $hint,
+        );
+
+        $e->wwwAuthenticate = self::CHALLENGE_BEARER;
+        $e->hasBody = false;
+        $e->setPayload([]);
+
+        return $e;
+    }
+
+
     /**
      * The authenticated client is not authorized to use this authorization grant type or response type
      * (RFC 6749 sections 4.1.2.1 / 5.2).
@@ -480,6 +563,46 @@ public function setPayload(array $payload): void
     }
 
 
+    /**
+     * The WWW-Authenticate challenge the error response carries, or null for none.
+     */
+    public function getWwwAuthenticate(): ?string
+    {
+        return $this->wwwAuthenticate;
+    }
+
+
+    /**
+     * Whether the error response has a body. Only a refusal for want of an access token has none.
+     */
+    public function hasBody(): bool
+    {
+        return $this->hasBody;
+    }
+
+
+    /**
+     * The headers of the error response: League's, the challenge when there is one, and no JSON content type for
+     * a response which has no body.
+     *
+     * @return array<string, string>
+     */
+    public function getHttpHeaders(): array
+    {
+        $headers = parent::getHttpHeaders();
+
+        if ($this->wwwAuthenticate !== null) {
+            $headers['WWW-Authenticate'] = $this->wwwAuthenticate;
+        }
+
+        if (!$this->hasBody) {
+            unset($headers['Content-type']);
+        }
+
+        return $headers;
+    }
+
+
     /**
      * @param string|null $redirectUri Set to string, or unset it with null
      */
@@ -562,9 +685,11 @@ public function generateHttpResponse(
             $response = $response->withHeader($header, $content);
         }
 
-        $responseBody = json_encode($payload, $jsonOptions) ?: 'JSON encoding of payload failed';
+        if ($this->hasBody) {
+            $responseBody = json_encode($payload, $jsonOptions) ?: 'JSON encoding of payload failed';
 
-        $response->getBody()->write($responseBody);
+            $response->getBody()->write($responseBody);
+        }
 
         return $response->withStatus($this->getHttpStatusCode());
     }