Align the Credential Endpoint's requests and errors with OpenID4VCI 1.0

Closes gaps G12, G14, G17 and G2 of the issuer compliance matrix.

- A Credential Request names its credential by credential_identifier or
  credential_configuration_id only, each a non-empty string. The
  pre-final resolution from format with a credential type or vct is
  removed, with its ModuleConfig lookup; a request naming neither gets
  invalid_credential_request instead of the pre-final
  unsupported_credential_type. The two members are read by name, so one
  sent as null next to the other is refused.
- A token which does not grant the credential asked for gets its 403
  insufficient_scope with a WWW-Authenticate challenge naming the error
  under the scheme the token came under (RFC 6750 section 3). A token
  naming no user, or a user who no longer exists, is refused as
  invalid_token (401, with its challenge) before the request is read,
  instead of 400 invalid_request.
- Key proofs: the kid, jwk, x5c, key_attestation and trust_chain header
  parameters and the iss claim are refused when written as null rather
  than read as absent. A key_attestation, and each statement of a
  trust_chain (a JSON array, as sent), must be a JWT in compact
  serialization (a JSON object for its claims, no b64) whose alg is
  advertised in proof_signing_alg_values_supported (Appendix F.1); what
  they attest is not evaluated (HAIP, H-G4).
- error_description keeps only the characters OpenID4VCI 1.0 section
  8.3.1.2 and RFC 6749 section 5.2 allow: Routes::newJsonErrorResponse()
  drops the rest, and the endpoint's descriptions no longer quote names
  in double quotes or echo the requested configuration id.

The proof validator tests build real proofs with the openid library for
the type, issue time, null members and attached JWTs, and both endpoint
test classes check every description their refusals produce.

Author: cicnavi

conformance-tests/openid4vci-1_0-compliance.md

@@ -164,7 +164,9 @@ Currently implemented OpenID4VCI features:
   - Credential Issuer Metadata | `.well-known/openid-credential-issuer` -
   Advertises supported credentials, algorithms, and endpoints.
   - Credential Endpoint | `credential-issuer/credential` - Handles credential
-  requests with proof of possession.
+  requests with proof of possession. A request names its credential by
+  `credential_identifier` or `credential_configuration_id`, as OpenID4VCI 1.0
+  has it; the pre-final `format` with a credential type or `vct` is not read.
   - Nonce Endpoint | `credential-issuer/nonce` - Provides nonces (`c_nonce`).
   - Credential Offer (API) | `api/vci/credential-offer` - Allows triggering
   credential offers via administrative API.
@@ -219,6 +221,10 @@ Currently implemented OpenID4VCI features:
   `c_nonce` is a JWS of a type of its own (`c-nonce+jwt`), so nothing else this
   issuer signs with the same key, a credential or a Status List Token, passes as
   one.
+  - A key proof's `key_attestation` and `trust_chain` headers are accepted when
+  signed with an algorithm advertised for key proofs
+  (`proof_signing_alg_values_supported`). What they attest is not evaluated,
+  so neither changes the key a credential is bound to.
   - Holder binding is stated in a `cnf` claim, in every credential format.
   - Each credential configuration decides for itself whether a key proof is
   required and which identifier rules apply to it. See

docs/1-oidc.md

@@ -109,7 +109,8 @@ public function __construct(
      * section 7.2 recommends (OidcServerException::buildResourceChallenges()). A refused token is named in the
      * challenge of the scheme it was presented under (`error="invalid_token"`), and a request which carried none
      * gets both challenges with no error and no body (RFC 6750 section 3.1); these come with the refusal. A 401
-     * from anywhere else gets both challenges with no error.
+     * from anywhere else gets both challenges with no error. The 403 for a token which does not grant the
+     * credential asked for carries its challenge too, `error="insufficient_scope"` (tokenErrorResponse()).
      *
      * @throws \SimpleSAML\OpenID\Exceptions\JwsException
      * @throws \ReflectionException
@@ -145,14 +146,30 @@ public function credential(Request $request): Response
      */
     protected function invalidTokenResponse(string $description, AccessTokenTypesEnum $scheme): Response
     {
+        return $this->tokenErrorResponse('invalid_token', $description, 401, $scheme);
+    }
+
+
+    /**
+     * A refusal for the access token as RFC 6750 section 3 has a protected resource answer one: the error, its
+     * status, and the `WWW-Authenticate` challenge it MUST carry when the token "does not contain an access token
+     * that enables access to the protected resource", naming the error under the scheme the token was presented
+     * under (OidcServerException::buildResourceChallenges()).
+     */
+    protected function tokenErrorResponse(
+        string $error,
+        string $description,
+        int $httpCode,
+        AccessTokenTypesEnum $scheme,
+    ): Response {
         return $this->routes->newJsonErrorResponse(
-            'invalid_token',
+            $error,
             $description,
-            401,
+            $httpCode,
             [
                 'WWW-Authenticate' => OidcServerException::buildResourceChallenges(
                     $scheme,
-                    'invalid_token',
+                    $error,
                     $this->moduleConfig->getDpopSigningAlgorithms(),
                 ),
             ],
@@ -242,9 +259,35 @@ protected function issueCredential(Request $request): Response
         // the code carrying it for this token (AuthCodeGrant), so the token can be used for as many credential
         // requests as its lifetime allows, like one which followed no offer (OpenID4VCI 1.0 section 14.3).
 
+        // The user a credential would be about, checked with the rest of the token and before anything the
+        // request asks for: a token naming no user, or one who no longer exists, buys no credential whatever is
+        // asked with it, which no change to the request would mend.
+        $userId = $accessToken->getUserIdentifier();
+        if (!is_string($userId)) {
+            $this->loggerService->error(
+                'CredentialIssuerCredentialController::credential: Access token names no user.',
+                ['accessTokenId' => $accessToken->getIdentifier()],
+            );
+            return $this->invalidTokenResponse('The access token names no user.', $scheme);
+        }
+        $userEntity = $this->userRepository->getUserEntityByIdentifier($userId);
+        if ($userEntity === null) {
+            $this->loggerService->error('User entity not found.', ['userId' => $userId]);
+            return $this->invalidTokenResponse(
+                'The user the access token was issued for no longer exists.',
+                $scheme,
+            );
+        }
+
+        // A request names its credential by `credential_identifier` when the token response returned authorization
+        // details, by `credential_configuration_id` otherwise, and never by both (OpenID4VCI 1.0 section 8.2).
+        // Which members it carries is read by name rather than by value, so a member sent as null still counts as
+        // sent: next to the other one the request names its credential both ways, and alone it names nothing.
+        $hasCredentialIdentifier = array_key_exists(ClaimsEnum::CredentialIdentifier->value, $requestData);
+
         if (
-            isset($requestData[ClaimsEnum::CredentialConfigurationId->value]) &&
-            isset($requestData[ClaimsEnum::CredentialIdentifier->value])
+            $hasCredentialIdentifier &&
+            array_key_exists(ClaimsEnum::CredentialConfigurationId->value, $requestData)
         ) {
             $this->loggerService->error(
                 'CredentialIssuerCredentialController::credential: Credential configuration ID ' .
@@ -259,9 +302,6 @@ protected function issueCredential(Request $request): Response
             );
         }
 
-        // Resolve the requested credential identifier.
-        $resolvedCredentialIdentifier = null;
-
         /** @psalm-suppress MixedAssignment */
         $credentialIdentifier = $requestData[ClaimsEnum::CredentialIdentifier->value] ?? null;
 
@@ -271,14 +311,14 @@ protected function issueCredential(Request $request): Response
         // section 8.2), so one sent for a flow which used no `authorization_details`, and so was issued none,
         // is unknown rather than ignored.
         $authorizationDetails = $accessToken->getAuthorizationDetails();
-        if ($authorizationDetails !== null || $credentialIdentifier !== null) {
-            if (!is_string($credentialIdentifier)) {
+        if ($authorizationDetails !== null || $hasCredentialIdentifier) {
+            if (!is_string($credentialIdentifier) || $credentialIdentifier === '') {
                 $this->loggerService->error(
                     'CredentialIssuerCredentialController::credential: Credential identifier missing in request.',
                 );
                 return $this->routes->newJsonErrorResponse(
                     'invalid_credential_request',
-                    'Can not resolve credential identifier.',
+                    'The credential_identifier parameter is missing, or is not a non-empty string.',
                     400,
                 );
             }
@@ -333,118 +373,29 @@ protected function issueCredential(Request $request): Response
                 ['resolvedCredentialIdentifier' => $resolvedCredentialIdentifier],
             );
         } else {
-            $this->loggerService->debug(
-                'No authorization details in the access token and no credential identifier in the request. ' .
-                'Skipping resolution from "credential_identifier".',
-            );
-        }
-
-        if (!is_string($resolvedCredentialIdentifier)) {
-            $this->loggerService->debug('Resolving credential identifier from "credential_configuration_id".');
-
+            // The one other way a request names its credential. What came before OpenID4VCI 1.0, a `format`
+            // with a credential type or a `vct`, is not read: a request naming neither identifier is malformed.
             /** @psalm-suppress MixedAssignment */
             $credentialConfigurationId = $requestData[ClaimsEnum::CredentialConfigurationId->value] ?? null;
 
-            if (is_string($credentialConfigurationId)) {
-                /** @psalm-suppress MixedAssignment */
-                $resolvedCredentialIdentifier = $credentialConfigurationId;
-
-                $this->loggerService->debug(
-                    'Resolved credential identifier from "credential_configuration_id" parameter.',
-                    ['resolvedCredentialIdentifier' => $resolvedCredentialIdentifier],
+            if (!is_string($credentialConfigurationId) || $credentialConfigurationId === '') {
+                $this->loggerService->error(
+                    'CredentialIssuerCredentialController::credential: The request names its credential by ' .
+                    'neither credential_identifier nor credential_configuration_id.',
                 );
-            } else {
-                $this->loggerService->warning('Credential identifier not provided in request parameters.');
-            }
-        }
-
-        if (!is_string($resolvedCredentialIdentifier)) {
-            $this->loggerService->warning(
-                'CredentialIssuerCredentialController::credential: No credential identifier found in request. ' .
-                'Falling back to resolution from format and credential type.',
-            );
-
-            $requestedCredentialFormatId = $requestData[ClaimsEnum::Format->value] ?? null;
-
-            if (!is_string($requestedCredentialFormatId)) {
-                $this->loggerService->error('Credential format missing in request (fallback resolution failed).');
                 return $this->routes->newJsonErrorResponse(
                     'invalid_credential_request',
-                    'Can not resolve credential format.',
+                    'The request must name the credential it asks for in the credential_configuration_id ' .
+                    'parameter.',
                     400,
                 );
             }
 
-            if (
-                !in_array($requestedCredentialFormatId, [
-                    CredentialFormatIdentifiersEnum::JwtVcJson->value,
-                    CredentialFormatIdentifiersEnum::DcSdJwt->value,
-                    CredentialFormatIdentifiersEnum::VcSdJwt->value,
-                ])
-            ) {
-                $this->loggerService->error(
-                    'CredentialIssuerCredentialController::credential: Unsupported credential format.',
-                    ['requestedCredentialFormatId' => $requestedCredentialFormatId],
-                );
-                return $this->routes->newJsonErrorResponse(
-                    'unsupported_credential_type',
-                    sprintf('Credential format ID "%s" is not supported.', $requestedCredentialFormatId),
-                    400,
-                );
-            }
+            $resolvedCredentialIdentifier = $credentialConfigurationId;
 
             $this->loggerService->debug(
-                'Resolved requested credential format.',
-                ['format' => $requestedCredentialFormatId],
-            );
-
-            $fallbackCredentialConfigurationId = null;
-
-            // TODO mivanci Update this to newest draft.
-            // Check per draft 14 (Sphereon wallet case).
-            /** @psalm-suppress MixedAssignment */
-            if (
-                $requestedCredentialFormatId === CredentialFormatIdentifiersEnum::JwtVcJson->value &&
-                is_array(
-                    $credentialDefinitionType =
-                        $requestData[ClaimsEnum::CredentialDefinition->value][ClaimsEnum::Type->value] ?? null,
-                )
-            ) {
-                $this->loggerService->debug(
-                    'Resolving configuration from credential definition types.',
-                    ['types' => $credentialDefinitionType],
-                );
-                $fallbackCredentialConfigurationId =
-                $this->moduleConfig->getVciCredentialConfigurationIdForCredentialDefinitionType(
-                    $credentialDefinitionType,
-                );
-            } elseif (
-                in_array($requestedCredentialFormatId, self::SD_JWT_FORMAT_IDS, true) &&
-                is_string($vct = $requestData[ClaimsEnum::Vct->value] ?? null)
-            ) {
-                $this->loggerService->debug(
-                    'Resolving configuration from VCT parameter.',
-                    ['vct' => $vct],
-                );
-                $fallbackCredentialConfigurationId = $vct;
-            }
-
-            if (!is_string($fallbackCredentialConfigurationId)) {
-                $this->loggerService->error('Fallback resolution failed to find a valid credential configuration.');
-            } else {
-                $this->loggerService->debug(
-                    'Resolved credential identifier via fallback mechanism.',
-                    ['resolvedCredentialIdentifier' => $fallbackCredentialConfigurationId],
-                );
-
-                $resolvedCredentialIdentifier = $fallbackCredentialConfigurationId;
-            }
-        }
-        if (!is_string($resolvedCredentialIdentifier)) {
-            return $this->routes->newJsonErrorResponse(
-                'invalid_credential_request',
-                'Can not resolve credential configuration ID.',
-                400,
+                'Resolved credential identifier from "credential_configuration_id" parameter.',
+                ['resolvedCredentialIdentifier' => $resolvedCredentialIdentifier],
             );
         }
 
@@ -458,7 +409,7 @@ protected function issueCredential(Request $request): Response
         if (!is_array($resolvedCredentialConfiguration)) {
             return $this->routes->newJsonErrorResponse(
                 'unknown_credential_configuration',
-                sprintf('Credential ID "%s" is not supported.', $resolvedCredentialIdentifier),
+                'The credential configuration the request names is not supported.',
                 400,
             );
         }
@@ -477,10 +428,11 @@ protected function issueCredential(Request $request): Response
                     'accessTokenId' => $accessToken->getIdentifier(),
                 ],
             );
-            return $this->routes->newJsonErrorResponse(
+            return $this->tokenErrorResponse(
                 'insufficient_scope',
                 'The access token does not grant the requested credential.',
                 403,
+                $scheme,
             );
         }
 
@@ -496,15 +448,6 @@ protected function issueCredential(Request $request): Response
             );
         }
 
-        $userId = $accessToken->getUserIdentifier();
-        if (!is_string($userId)) {
-            throw OidcServerException::invalidRequest('User identifier not available in Access Token.');
-        }
-        $userEntity = $this->userRepository->getUserEntityByIdentifier($userId);
-        if ($userEntity === null) {
-            $this->loggerService->error('User entity not found.', ['userId' => $userId]);
-            throw OidcServerException::invalidRequest('User not found.');
-        }
         $this->loggerService->info('Issuing credential for user.', ['userId' => $userId]);
 
         // Every key proof is validated before anything at all is issued. Validating and issuing in one

src/Controllers/VerifiableCredentials/CredentialIssuerCredentialController.php

@@ -13,7 +13,9 @@
  * choice with the check that made it, rather than flattening every refusal to one code at the boundary.
  *
  * The message is returned to the wallet as `error_description`, so it says what is wrong with the
- * request without repeating back anything the request itself supplied.
+ * request without repeating back anything the request itself supplied, in the characters OpenID4VCI 1.0
+ * section 8.3.1.2 allows there: printable ASCII without the double quote and the backslash. Parameter names
+ * are written bare for that reason.
  */
 class CredentialRequestException extends OidcException
 {

src/Exceptions/CredentialRequestException.php

@@ -3096,33 +3096,6 @@ public function getVciScopes(): array
     }
 
 
-    public function getVciCredentialConfigurationIdForCredentialDefinitionType(array $credentialDefinitionType): ?string
-    {
-        foreach (
-            $this->getVciCredentialConfigurationsSupported() as $credentialConfigurationId => $credentialConfiguration
-        ) {
-            if (!is_array($credentialConfiguration)) {
-                continue;
-            }
-
-            $credentialDefinition = $credentialConfiguration[ClaimsEnum::CredentialDefinition->value] ?? null;
-
-            if (!is_array($credentialDefinition)) {
-                continue;
-            }
-
-            /** @psalm-suppress MixedAssignment */
-            $configuredType = $credentialDefinition[ClaimsEnum::Type->value] ?? null;
-
-            if ($configuredType === $credentialDefinitionType) {
-                return (string)$credentialConfigurationId;
-            }
-        }
-
-        return null;
-    }
-
-
     /**
      * Extract and parse the claims path definition from the credential configuration supported.
      * Returns an array of valid paths for the claims.

src/ModuleConfig.php

@@ -65,14 +65,25 @@ public function newJsonResponse(
     }
 
 
+    /**
+     * An error response of the OAuth 2.0 shape, `error` and `error_description`.
+     *
+     * The description keeps only the characters RFC 6749 section 5.2 allows in one, %x20-21 / %x23-5B / %x5D-7E:
+     * printable ASCII without the double quote and the backslash. OpenID4VCI 1.0 section 8.3.1.2 has the same
+     * rule for Credential Request errors. Several callers pass an exception message, so what arrives here is not
+     * fixed where it is written, and the rest are dropped rather than escaped, since no escape is allowed either.
+     */
     public function newJsonErrorResponse(
         string $error,
         string $description,
         int $httpCode = 500,
         array $headers = [],
     ): JsonResponse {
         return $this->newJsonResponse(
-            ['error' => $error, 'error_description' => $description],
+            [
+                'error' => $error,
+                'error_description' => (string)preg_replace('/[^\x20\x21\x23-\x5B\x5D-\x7E]/', '', $description),
+            ],
             $httpCode,
             $headers,
         );