[OID4VCI] Run OID4VCI Conformance Tests for Keycloak's OID4VC Feature

[forkimenjeckayang]

Run the official OpenID Conformance Tests for the OpenID for Verifiable Credential Issuance (OID4VCI) 1.0 Final implementation in Keycloak to validate compliance with the specification.

The objective is to verify that the OID4VC feature aligns with OpenID certification requirements and identify any interoperability or specification gaps.

ETA: 3 Days

[forkimenjeckayang]

OID4VCI Conformance – Progress Update

Test Suit: OpenID for Verifiable Credential Issuance 1.0 Final: Test an issuer (alpha version - may be incomplete or incorrect, please email certification@oidf.org)

Test Environment Context

• Plan Name: oid4vci-1_0-issuer-test-plan
• Variant: sender_constrain=dpop, client_auth_type=private_key_jwt, vci_authorization_code_flow_variant=issuer_initiated, credential_format=sd_jwt_vc, authorization_request_type=simple, vci_profile=haip, fapi_request_method=signed_non_repudiation, vci_grant_type=authorization_code, vci_credential_encryption=plain
• Proof Type Used: attestation

Resolved Issues

We have successfully addressed the following issues during conformance testing:

1. Client Configuration Issues

   • Incorrect client setup for OID4VCI flows.
   • Adjusted protocol settings and client configuration to align with conformance expectations.

2. Missing authorization_details in Token Response (Scope-based Flow)

   • Conformance suite was using OAuth2 scopes instead of Rich Authorization Requests (RAR).
   • Keycloak did not return authorization_details when only scopes were used (causing failure at /credential due to missing credential_identifier).

   Fix Implemented:

   • Added fallback logic in OID4VCAuthorizationDetailsProcessor to resolve credential_configuration_id from scopes and generate a credential_identifier.
   • This ensures full compatibility with wallets relying solely on scope-based requests.

3. Self-Signed Credential Signing Certificates (HAIP Failure)

   • Test: HAIP-6.1.1 (VCIEnsureX5cHeaderPresentForSdJwtCredential)
   • Requirement: Credential signing certificate MUST NOT be self-signed (HAIP §4.5.1).

   Fix Implemented:

   • Established a local Root CA within the deployment environment.
   • All Keycloak signing keys (ECDSA/RSA) are now signed by this Root CA instead of being self-signed.
   • The Root CA is injected into the Keycloak truststore to establish a complete trust chain.
   • Issued credentials now include a valid certificate chain in the x5c header.

4. Nonce Replay Protection (invalid_nonce vs. unknown_credential_identifier)

   • Test: OID4VCI-1FINAL-8.3.1 (VCIValidateCredentialErrorResponse)
   • Issue: Replaying a credential request with a previously used nonce resulted in unknown_credential_identifier. This occurred because the CredentialOfferState was removed immediately after the first successful issuance, causing the validation to fail on session state lookup before reaching the nonce check.

   Fix Implemented:

   • Implemented nonce pre-validation logic at the /credential endpoint.
   • The system now extracts and validates the c_nonce from the proof before attempting to resolve the credential_identifier or session state.
   • This ensures that replayed nonces trigger the correct invalid_nonce error, maintaining spec-compliant error precedence.

5. Non-standard Error Code Format (Case Sensitivity)

   • Issue: Even when the correct error type was triggered, the conformance suite rejected responses because error codes were returned in uppercase (e.g., INVALID_NONCE). The OID4VCI specification (§8.3.1.2) expects these error codes to be standard ASCII strings, which the suite interprets as lowercase.

   Fix Implemented:

   • Standardized all OID4VCI error codes in ErrorType.java to lowercase strings (e.g., invalid_nonce, invalid_credential_request).
   • Updated the ErrorResponse model and event logging to ensure precise lowercase serialization.
   • Aligned initiation endpoints with RFC 6750 (invalid_request) while maintaining specialized, spec-compliant codes for the Credential Endpoint.
   • Updated all related integration tests to verify the new standardized error responses.

6. Incorrect Error Code for Invalid Proofs and Missing Nonces (invalid_proof)

   • Test: OID4VCI-1FINAL-8.3.1 (oid4vci-1_0-issuer-fail-invalid-key-attestation-signature)
   • Requirement: OID4VCI §8.3.1.2 mandates invalid_proof when (1) proof is missing, (2) proof is invalid (e.g., signature failure), or (3) c_nonce is missing from the proof.

   Fix Implemented:

   • Comprehensive Coverage: Standardized all proof validation exceptions across JwtProofValidator, AttestationProofValidator, and AttestationValidatorUtil to throw VCIssuerException with ErrorType.INVALID_PROOF.
   • Unconditional Nonce Verification: Proof payloads are now unconditionally checked for the presence of a c_nonce. A missing nonce in the proof now strictly returns invalid_proof, while an invalid nonce value remains mapped to invalid_nonce.
   • Regression Fix: Restored the specific exception message expected by existing integration tests in OID4VCIssuerEndpoint while ensuring the underlying JSON error response contains the spec-compliant lowercase invalid_proof code.

7. Expected unknown_credential_configuration but received invalid_credential_request

   • Test: OID4VCI-1FINAL-8.3.1 (oid4vci-1_0-issuer-fail-unknown-credential-configuration)

   • Issue: The test suite expects unknown_credential_configuration when it sends an invalid credential_configuration_id. However, because the Token Response included authorization_details (RAR), OID4VCI §8.2 mandates that the request MUST use credential_identifier and MUST NOT use credential_configuration_id.

   • Analysis: Keycloak correctly enforces the protocol's structural requirements first. Since the credential_identifier was missing from the request, it returned invalid_credential_request as per §8.2. The test suite is forcing a "double failure" (missing a required parameter while providing a forbidden one) and expecting semantic validation of the forbidden parameter to take precedence over the missing required one. This is a test suite discrepancy, as Keycloak's behavior remains strictly compliant with the specification's priority.

     

Test Results

• The skipped tests are expected based on test enviroment and the failed test is actually a testsuit issue

[forkimenjeckayang]

OID4VCI Conformance Fixes (Running form the master branch on the conformance-suite repo )

Test Suit: OpenID for Verifiable Credential Issuance 1.0 Final: Test an issuer (alpha version - may be incomplete or incorrect, please email certification@oidf.org)

Test Environment

Test Plan: oid4vci-1_0-issuer-test-plan (CBk3t95rzAZe4)

Variant:

• sender_constrain=dpop,
• client_auth_type=private_key_jwt,
• vci_authorization_code_flow_variant=issuer_initiated,
• credential_format=sd_jwt_vc,
• authorization_request_type=simple && authorization_request_type=rar
• vci_profile=plain_vci,
• fapi_request_method=signed_non_repudiation,
• vci_grant_type=authorization_code
• vci_credential_encryption=plain && vci_credential_encryption=encrypted
• proof types tested: jwt && attestation

---

1. Date Header Compliance

Issue

The OID4VCI conformance test requires a mandatory Date header (RFC 7231) in all resource and discovery endpoint responses. Keycloak was missing this header in its OID4VCI-specific endpoints.

Solution

Manually implemented Date header injection using RFC 1123 format across the following components:

• OID4VCIssuerEndpoint
• OID4VCIssuerWellKnownProvider
• JWTVCIssuerWellKnownProvider

---

2. Date Header Duplication (JsonArray Error)

Issue

Adding the header to discovery providers caused it to be duplicated (appearing as a JsonArray) due to internal recursive calls within Keycloak.

Solution

Refactored OID4VCIssuerEndpoint to use getIssuerMetadata() for internal lookups. This avoids triggering side effects in the discovery provider and ensures the header is added exactly once.

---

3. Credential Offer State Persistence

Issue

The happy-flow-additional-requests test failed with unknown_credential_identifier because the CredentialOfferState was being deleted immediately after the first successful issuance.

Solution

Removed the manual cleanup call offerStorage.removeOfferState() in OID4VCIssuerEndpoint.java.

Rationale

Per OID4VCI Specification Section 14.3, the credential endpoint must support multiple accesses using the same Access Token. Persistence is now handled correctly, with cleanup being managed by the underlying storage expiration mechanism instead of manual removal.

---

4. Mandatory Proof Validation & Nonce Replay Handling

Issue

Two main issues were observed.

First, the oid4vci-1_0-issuer-fail-missing-proof conformance test failed because Keycloak did not reject credential requests that omitted proofs even when the credential configuration required cryptographic key binding.

Second, valid proofs were sometimes rejected with invalid_nonce errors indicating that the c_nonce had already been used. This occurred because the nonce pre-validation step consumed the nonce before the final proof validators executed. As a result, retries after a failed credential issuance were incorrectly treated as replay attacks.

Solution

Proof enforcement was implemented based on the credential configuration by introducing an isProofRequired() check in SupportedCredentialConfiguration. The credential endpoint now rejects requests missing required proofs with an invalid_proof error.

Nonce validation was redesigned to prevent false replay errors. Nonces are first validated without being consumed and stored in a per-request VALIDATED_NONCES set. Proof validators reuse these validated nonces instead of re-verifying them. Nonces are consumed only after a successful credential issuance using JwtCNonceHandler.verifyCNonce(..., consume=true), ensuring retries after failed issuance work correctly while still preventing real replay attacks.

---

5. Independent Request vs. Response Encryption

Issue

The OID4VCI metadata parameters credential_request_encryption and credential_response_encryption are defined by the specification as independent and optional, each with its own encryption_required flag.

Keycloak incorrectly coupled these two directions in two ways:

1. An internal "consistency rule" automatically forced credential_request_encryption.encryption_required=true whenever credential_response_encryption.encryption_required=true.
2. A single realm attribute (oid4vci.encryption.required) effectively controlled both request and response encryption.

As a result, when only response encryption was intended to be required (per the conformance test configuration), unencrypted credential requests were rejected early with invalid_encryption_parameters instead of proceeding to credential identifier validation and returning unknown_credential_identifier as expected by the test suite.

Solution

The encryption handling was refactored to align with the OID4VCI specification and decouple request and response encryption:

• Removed the automatic coupling logic that forced request encryption to be required when response encryption was required.
• Kept oid4vci.encryption.required as the realm attribute that controls only credential_response_encryption.encryption_required.
• Introduced a new, separate realm attribute oid4vci.request.encryption.required to control only credential_request_encryption.encryption_required, defaulting to false when unspecified.
• Updated OID4VCIssuerWellKnownProvider so that:
  • getCredentialResponseEncryption() reads oid4vci.encryption.required to determine whether response encryption is mandatory.
  • getCredentialRequestEncryption() reads oid4vci.request.encryption.required and leaves request encryption optional unless explicitly required.

This brings Keycloak’s behavior in line with OID4VCI Section 12.2.4: request and response encryption metadata are independent, and encryption_required applies only to the respective direction.

Test Results

• The failure is espected: The test suite expects unknown_credential_configuration when it sends an invalid credential_configuration_id. However, because the Token Response included authorization_details (RAR), OID4VCI §8.2 mandates that the request MUST use credential_identifier and MUST NOT use credential_configuration_id.
• The test skips are expected based on test enviroment tweaking

[forkimenjeckayang]

OID4VCI Conformance Fixes (Running form the master branch on the conformance-suite repo )

Test Suit: OpenID for Verifiable Credential Issuance 1.0 Final: Test an issuer (alpha version - may be incomplete or incorrect, please email certification@oidf.org)

Test Environment

Test Plan: oid4vci-1_0-issuer-test-plan (CBk3t95rzAZe4)

Variant:

• sender_constrain=dpop,
• client_auth_type=private_key_jwt,
• vci_authorization_code_flow_variant=issuer_initiated,
• credential_format=sd_jwt_vc,
• authorization_request_type=simple
• vci_profile=haip,
• fapi_request_method=signed_non_repudiation,
• vci_grant_type=authorization_code
• vci_credential_encryption=plain && vci_credential_encryption=encrypted
• proof types tested: jwt && attestation

---

1. HAIP-6.1.1: Trust Anchor Must Not Be Included in x5c Header

Issue

HAIP conformance test failed with error: HAIP-6.1.1 The trust anchor (self-signed root CA) MUST NOT be included in the x5c chain. The x5c array in SD-JWT credentials contained both the leaf certificate and the self-signed root CA certificate, violating HAIP-6.1.1 requirements.

Additionally, when only a self-signed certificate was present (no proper certificate chain), Keycloak was including it in x5c, which violates the requirement that "The X.509 certificate signing the request MUST NOT be self-signed."

Root Cause

The SdJwtCredentialSigner.addX5cHeader() method was including all certificates from the certificate chain without filtering out self-signed trust anchors. It also did not validate that the signing certificate itself was not self-signed.

Solution

Modified SdJwtCredentialSigner.addX5cHeader() to:

1. Validate signing certificate: Check if the first certificate (signing certificate) is self-signed. If so, skip x5c header entirely per HAIP-6.1.1 requirement that signing certificates must not be self-signed.

2. Filter trust anchors: Remove trailing self-signed certificates (trust anchors) from the certificate chain before adding to x5c. This ensures compliance with HAIP-6.1.1: "The X.509 certificate of the trust anchor MUST NOT be included in the x5c JOSE header."

3. Skip x5c if invalid: If all certificates are self-signed (trust anchors) after filtering, skip the x5c header entirely rather than including invalid data.

HAIP Compliance

• "The X.509 certificate signing the request MUST NOT be self-signed" - Enforced by validation check
• "The X.509 certificate of the trust anchor MUST NOT be included in the x5c JOSE header" - Enforced by filtering logic
• "The SD-JWT VC MUST contain the credential issuer's signing certificate along with a trust chain" - Satisfied when valid chain exists

Test Results

• The failure is espected: The test suite expects unknown_credential_configuration when it sends an invalid credential_configuration_id. However, because the Token Response included authorization_details (RAR), OID4VCI §8.2 mandates that the request MUST use credential_identifier and MUST NOT use credential_configuration_id.
• The test skips are expected based on test enviroment tweaking

[forkimenjeckayang]

OID4VCI Conformance Fixes (Running form the master branch on the conformance-suite repo )

Test Suit: OpenID for Verifiable Credential Issuance 1.0 Final: Test an issuer (alpha version - may be incomplete or incorrect, please email certification@oidf.org)

Test Environment

Test Plan: oid4vci-1_0-issuer-test-plan (CBk3t95rzAZe4)

Variant:

• sender_constrain=dpop,
• client_auth_type=private_key_jwt,
• vci_authorization_code_flow_variant=issuer_initiated,
• credential_format=sd_jwt_vc,
• authorization_request_type=simple && authorization_request_type=rar
• vci_profile=plain_vci,
• fapi_request_method=signed_non_repudiation,
• vci_grant_type=pre_authorization_code
• vci_credential_encryption=plain && vci_credential_encryption=encrypted
• proof types tested: jwt && attestation

---

Test Results

• The failure is espected: The test suite expects unknown_credential_configuration when it sends an invalid credential_configuration_id. However, because the Token Response included authorization_details (RAR), OID4VCI §8.2 mandates that the request MUST use credential_identifier and MUST NOT use credential_configuration_id.
• The test skips are expected based on test enviroment tweaking

[forkimenjeckayang]

I’ve paused work on the following HAIP conformance test, because it requires “client attestation” as a client authentication method, which Keycloak does not support yet:

• Test suite: OpenID for Verifiable Credential Issuance 1.0 Final / HAIP: Test an issuer (alpha version – may be incomplete or incorrect)
• Scenario: Variant that requires OAuth client authentication via “client attestation”

In our Keycloak fork we do have support for attestation as a proof type in OID4VCI (e.g. key-attestation+jwt, oid4vc.attestation.trusted_keys, oid4vc.attestation.trusted_key_ids, AttestationProofValidator, AttestationValidatorUtil, etc.), but that is used to validate credential proofs, not to authenticate OAuth clients at the token endpoint.

On the client authentication side, Keycloak currently only supports the standard methods:
client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, and mTLS variants (tls_client_auth, self_signed_tls_client_auth, …). There is no dedicated “client attestation” client authenticator implemented in Keycloak.

Because of this mismatch (the test expects a client-auth method that Keycloak does not implement), running this HAIP test would not be meaningful at the moment. If/when Keycloak adds a dedicated client attestation authentication method, I can revisit and enable this test.

[Ogenbertrand]

Draft PR: #246