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
Credential Offer by Reference	`credential_offer_uri` (offer-by-reference) is now single-use and cannot be resolved repeatedly	Medium
Refresh Token Policy	Refresh-token settings moved from top-level issuance config to `authorizationServers[].token`	Medium
Pre-Authorized Offer Routing	Pre-authorized issuance flow defaults to built-in AS when no `authorization_server` is explicitly selected	Low

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¶

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

2. Credential Offer URI Is Single-Use (Behavioral Change)¶

What Changed¶

When using offer-by-reference (credential_offer_uri), the referenced offer can now be consumed only once.

After the first successful wallet resolution, subsequent attempts to resolve the same URI are expected to fail.

Impact¶

Wallet retry flows that re-fetch the same credential_offer_uri will no longer work.
Integrations that shared one URI across multiple devices/sessions must now issue one offer per consumption.

Migration Steps¶

Ensure each wallet/user session gets its own freshly generated credential_offer_uri.
If a flow fails mid-journey, generate a new offer instead of retrying the old URI.
Update automated tests to assert that a second resolve attempt on the same URI is rejected.

3. Refresh Token Policy Moved Under Authorization Servers¶

What Changed¶

Refresh-token behavior is no longer configured via legacy issuance-level refresh-token fields.

Configure refresh-token policy per authorization server in:

authorizationServers[].token.refreshTokenEnabled
authorizationServers[].token.refreshTokenExpiresInSeconds

Built-in AS defaults remain:

refreshTokenEnabled: true
refreshTokenExpiresInSeconds: 2592000 (30 days)

Migration Steps¶

Remove any reliance on legacy top-level refresh-token flags in issuance config.
Add explicit token settings to each managed authorization server where you need non-default refresh-token behavior.
Validate token endpoint behavior for both authorization_code and refresh_token grant types after upgrade.

4. Pre-Authorized Flow Defaults to Built-In AS¶

What Changed¶

For pre-authorized code offers, when authorization_server is omitted, EUDIPLO now defaults routing to the built-in authorization server.

Migration Steps¶

If you require a specific AS (for example chained or oid4vp), set authorization_server explicitly in offer creation.
Re-test pre-authorized wallet flows that previously depended on implicit AS selection behavior.