Skip to main content

​
Overview

The Gaia-X Digital Clearing House provides registry services for verifying Gaia-X ecosystem participants. VCVerifier integrates with these services to validate that credential issuers are compliant Gaia-X participants.

​
Gaia-X Participant Requirements

Gaia-X Registry verification has specific requirements for issuer DIDs. Not all DID methods are supported.
To be verified through a Gaia-X Registry, issuers must:
  1. Use did:web method only - Other DID methods are not supported
  2. Provide valid x5u location - The DID document must include an x5u (X.509 URL) field in the publicKeyJwk
  3. Maintain accessible certificate chain - The certificate chain must be available at the x5u URL
  4. Meet Gaia-X compliance requirements - The participant must fulfill Gaia-X ecosystem standards

​
Configuration

​
Basic Configuration

Configure Gaia-X Registry verification for your credential types: 
configRepo:
  services:
    testService:
      scope:
        - VerifiableCredential
      trustedParticipants:
        VerifiableCredential:
          - type: gaia-x
            url: https://registry.lab.gaia-x.eu

​
Multiple Credential Types

Apply Gaia-X verification to different credential types: 
configRepo:
  services:
    testService:
      scope:
        - VerifiableCredential
        - GaiaXCredential
        - ParticipantCredential
      trustedParticipants:
        VerifiableCredential:
          - type: gaia-x
            url: https://registry.lab.gaia-x.eu
        GaiaXCredential:
          - type: gaia-x
            url: https://registry.lab.gaia-x.eu
        ParticipantCredential:
          - type: gaia-x
            url: https://registry.lab.gaia-x.eu

​
Verification Process

The Gaia-X verification process is more complex than EBSI TIR verification due to certificate chain validation:
1

Credential Received

VCVerifier receives a credential with a did:web issuer
2

Resolve DID Document

The issuer’s DID document is resolved using the did:web method:
did:web:example.com:issuer → https://example.com/.well-known/did.json
3

Extract Verification Method

VCVerifier extracts the verification method from the DID document and retrieves the JSON Web Key (JWK)
4

Get Certificate URL (x5u)

The x5u field from the JWK points to the certificate chain location:
{
  "kty": "RSA",
  "x5u": "https://example.com/certs/issuer.pem",
  "use": "sig",
  ...
}
5

Verify Certificate Chain

VCVerifier sends the certificate chain URL to the Gaia-X Registry:
POST /v2/api/trustAnchor/chain/file
Content-Type: application/json

{"uri": "https://example.com/certs/issuer.pem"}
6

Evaluate Response

  • HTTP 200: Certificate chain is trusted, issuer is verified
  • Other codes: Certificate chain is not trusted, verification fails

​
DID Document Requirements

A valid Gaia-X-compatible DID document must include: 
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:example.com:issuer",
  "verificationMethod": [
    {
      "id": "did:web:example.com:issuer#key-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:example.com:issuer",
      "publicKeyJwk": {
        "kty": "RSA",
        "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx...",
        "e": "AQAB",
        "alg": "RS256",
        "x5u": "https://example.com/certs/issuer.pem"
      }
    }
  ]
}
The x5u field is required for Gaia-X verification. Without it, the verification will fail as VCVerifier cannot locate the certificate chain.

​
API Endpoint

The Gaia-X Registry exposes the following endpoint for certificate chain verification: 
POST /v2/api/trustAnchor/chain/file

​
Request Format

{
  "uri": "https://example.com/certs/issuer.pem"
}

​
Response

  • 200 OK: Certificate chain is valid and rooted in a Gaia-X trust anchor
  • 400 Bad Request: Invalid request format
  • 404 Not Found: Certificate chain cannot be verified
  • 500 Internal Server Error: Registry service error
According to the Gaia-X Registry specification, all HTTP 200 responses indicate valid certificate chains. VCVerifier does not parse the response body; the status code alone determines trust.

​
Implementation Details

VCVerifier’s Gaia-X client implements the following logic: 
// 1. Resolve the DID
didDocument, err := didRegistry.Resolve(did)

// 2. Find verification method with matching ID or controller
for _, verificationMethod := range didDocument.VerificationMethod {
    if verificationMethod.ID == did || verificationMethod.Controller == did {
        // 3. Extract JWK and get x5u
        jwk := verificationMethod.JSONWebKey()
        if jwk.CertificatesURL != nil {
            x5u := jwk.CertificatesURL.String()
            
            // 4. Verify against Gaia-X Registry
            return verifyFileChain(registryEndpoint, x5u)
        }
    }
}

​
Testing Your Configuration

​
Verify DID Resolution

Test that your did:web can be resolved: 
# Resolve a did:web
curl https://example.com/.well-known/did.json

# Should return a valid DID document with verificationMethod

​
Verify Certificate Chain

Test the certificate chain verification: 
# Test Gaia-X Registry verification
curl -X POST https://registry.lab.gaia-x.eu/v2/api/trustAnchor/chain/file \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"uri": "https://example.com/certs/issuer.pem"}'

# Expected response: HTTP 200 for valid chains

​
Common Issues

Problem: Cannot resolve did:webSolutions:
  • Ensure .well-known/did.json is accessible at the correct URL
  • Check CORS headers if accessing from a browser
  • Verify the DID document is valid JSON
  • Confirm the server supports HTTPS (required for production did:web)
Problem: Verification fails with “x5u not found”Solutions:
  • Add x5u field to the publicKeyJwk in your DID document
  • Ensure the certificate chain is accessible at the x5u URL
  • Use proper PEM format for certificate chains
Problem: Registry returns non-200 responseSolutions:
  • Verify your certificate chain is rooted in a Gaia-X trust anchor
  • Check certificate validity periods
  • Ensure proper certificate chain order (leaf → intermediate → root)
  • Contact Gaia-X support to register your certificates
Problem: Using did:key, did:ethr, or other methodsSolution:
  • Gaia-X Registry only supports did:web
  • Convert your issuer to use did:web method
  • Publish a proper DID document at the web location

​
Production Considerations

​
Certificate Management

1

Obtain Gaia-X Certificates

Work with Gaia-X-approved certificate authorities to obtain compliant certificates
2

Publish Certificate Chain

Host your certificate chain at a reliable, HTTPS-accessible URL
3

Update DID Document

Add the x5u field pointing to your certificate chain
4

Monitor Expiry

Certificates expire - implement monitoring and renewal processes
5

Test Verification

Regularly test your setup against the Gaia-X Registry

​
High Availability

  • Multiple Certificate Locations: Host certificate chains redundantly
  • Registry Fallback: Consider configuring multiple Gaia-X Registry instances
  • Error Handling: Implement graceful degradation if registry is unavailable

​
Registry Endpoints

trustedParticipants:
  VerifiableCredential:
    - type: gaia-x
      url: https://registry.gaia-x.eu
Use the lab environment for development and testing. Only move to production endpoints after thorough testing and certification.

​
Comparison: Gaia-X vs EBSI TIR

FeatureGaia-X RegistryEBSI TIR
DID MethodsOnly did:webAll methods
Verification MethodCertificate chainDID registry lookup
Additional Requirementsx5u in JWKNone
Certificate ManagementRequiredNot required
Setup ComplexityHigherLower
Use CaseGaia-X ecosystemGeneral SSI

​
Next Steps

Mixed Usage

Combine Gaia-X with EBSI TIR

Overview

Back to trust anchors overview

Build docs developers (and LLMs) love

Get started for freeTalk to us