Skip to content

Migrating from 5.x to 6.0

This guide covers breaking changes introduced in EUDIPLO v6.0 and the required migration steps from any 5.x version.

Back up before upgrading

Always back up your database and your assets/config directory before performing a major version upgrade.

Summary of Breaking Changes

Area Change Impact
Issuance Authorization Servers Legacy authServers/chainedAs approach is replaced by unified authorizationServers entries (external, oid4vp, chained, built-in) High

1. Issuance Authorization Server Model (Breaking)

What Changed

Issuance authorization server configuration moves to a unified authorizationServers model.

Legacy configuration keys:

  • authServers
  • chainedAs

must be migrated to typed entries in:

  • authorizationServers[]

with type set to one of:

  • external
  • oid4vp
  • chained
  • built-in

The authorizationServers array must contain at least one entry.

Before (5.x)

{
    "authServers": ["https://auth.example.com"],
    "chainedAs": {
        "enabled": true,
        "upstream": {
            "issuer": "https://keycloak.example.com/realms/eudiplo",
            "clientId": "eudiplo-chained-as",
            "clientSecret": "secret"
        },
        "token": {
            "lifetimeSeconds": 3600,
            "signingKeyId": "default"
        },
        "requireDPoP": true
    }
}

After (6.0)

{
    "authorizationServers": [
        {
            "type": "external",
            "id": "external-corp-idp",
            "issuer": "https://auth.example.com"
        },
        {
            "type": "chained",
            "id": "chained-auth",
            "enabled": true,
            "upstream": {
                "issuer": "https://keycloak.example.com/realms/eudiplo",
                "clientId": "eudiplo-chained-as",
                "clientSecret": "secret",
                "scopes": ["openid", "profile", "email"]
            },
            "token": {
                "lifetimeSeconds": 3600,
                "signingKeyId": "default"
            },
            "requireDPoP": true
        },
        {
            "type": "oid4vp",
            "id": "pid-auth",
            "presentationConfigId": "pid-no-hook",
            "enabled": true
        }
    ]
}

Authorization Server IDs

Each authorizationServers[] entry must define an id:

  • non-empty string
  • unique across the array
  • values built-in and chained-as are reserved

For offer requests, authorization_server must contain one of these configured ids.

Migration Steps

  1. Replace authServers URLs with authorizationServers entries of type external.
  2. Replace chainedAs object with one authorizationServers entry of type chained.
  3. If you use VP-backed AS routing, define authorizationServers entries of type oid4vp with stable id values.
  4. Update offer creation payloads so authorization_server references a configured AS id.
  5. Re-run OIDF and wallet integration tests to validate authorization server selection and metadata behavior.