> For the complete documentation index, see [llms.txt](https://www.nl-portal.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.nl-portal.nl/3.x/release-notes/3.1.x/app/3.1.0.md).

# 3.1.0

Deze release bevat NL-Portal Backend Libraries 3.1.0 en NL-Portal Frontend Libraries 3.1.0.

## Nieuwe Functionaliteit

De volgende functionaliteiten zijn nieuw toegevoegd:

* **Keycloak Standard Token Exchange (v2) te kiezen met een environment variabele.** De nieuwe variabele `KEYCLOAK_TOKEN_EXCHANGE_VERSION` accepteert `v1` of `v2`. De standaardwaarde is `v1`, dus een bestaande deployment werkt zonder aanpassing verder. Met `v2` gebruikt de app image de Standard Token Exchange van Keycloak 26.2 en nieuwer, en heeft de Keycloak waarop de portal draait de features `token-exchange:v1` en `admin-fine-grained-authz:v1` niet meer nodig. Daardoor komt Fine-Grained Admin Permissions v2 op die Keycloak beschikbaar.

  De variant bepaalt ook welke clients je in Keycloak nodig hebt: v2 heeft er twee, v1 drie. Zie [Standard token exchange (v2)](/3.x/configuratie/keycloak/keycloak-token-exchange-v2.md) en [Migratie van v1 naar v2](/3.x/configuratie/keycloak/keycloak-token-exchange-v2.md#migratie-van-v1-naar-v2).
* **`KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE` is niet meer verplicht.** Bij `v2` laat je de variabele leeg of weg. Bij `v1` blijft hij nodig en moet hij de doelclient noemen. Tot 3.0.x startte de app image niet zonder deze variabele; vanaf 3.1.0 start hij wel, logt bij `v1` een waarschuwing dat de audience ontbreekt, en faalt de eerste token exchange met een melding die de property benoemt.
* **Optionele audience validatie.** Met `SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_AUDIENCES` laat je de backend controleren voor welke client een token is uitgegeven. Zonder die variabele accepteert de backend elke token die door hetzelfde realm is ondertekend, ongeacht de client. De variabele staat standaard leeg en werkt alleen wanneer de Keycloak configuratie de bijbehorende audience mappers heeft. Zie [Audience validatie](/3.x/configuratie/keycloak/keycloak-token-exchange-v2.md#audience-validatie-aanbevolen).
* **Helm chart 3.2.0.** De `nl-portal-backend` chart 3.2.0 sluit hierop aan:

  | Waarde                                   | Betekenis                                    |
  | ---------------------------------------- | -------------------------------------------- |
  | `settings.keycloak.tokenExchangeVersion` | `v1` of `v2`. Standaard `v1`                 |
  | `settings.keycloak.audience`             | Alleen nog verplicht bij `v1`                |
  | `settings.keycloak.acceptedAudiences`    | Optionele audience validatie. Standaard leeg |

  De chart weigert `v2` te renderen wanneer de gedeployde versie ouder is dan 3.1.0, en meldt dat bij het renderen in plaats van bij het opstarten.

## Bugfixes

De volgende bugs zijn opgelost:

* Wanneer Keycloak een token exchange weigert, wordt de foutmelding van Keycloak nu gelogd, samen met de actieve variant. Voorheen verdween die tekst en bleef alleen een HTTP status over.
* Modules die andere modules nodig hebben, controleerden dat niet volledig. Zette je `zakenapi`, `berichten`, `openproduct` of `product` aan zonder al hun vereisten, dan startte de applicatie niet op en faalde hij met een `NoSuchBeanDefinitionException`, in Kubernetes een crash loop. Deze modules blijven nu inactief wanneer een vereiste module uitstaat, in plaats van het opstarten te blokkeren.

  | Module        | Aanvullend vereist                                      |
  | ------------- | ------------------------------------------------------- |
  | `zakenapi`    | `documentenapis`, `besluitenapi`                        |
  | `berichten`   | `objectenapi`                                           |
  | `openproduct` | `catalogiapi`, `documentenapis`, `besluitenapi`         |
  | `product`     | `catalogiapi`, `documentenapis`, `besluitenapi`, `taak` |

  Dit speelt vooral bij configuratie via het [Configuration Panel](/3.x/configuratie/configuration-panel.md), waar je per wijziging opslaat en de applicatie tussentijds herstart. Een configuratie die eerder werkte verandert hier niet door. Zie [Module afhankelijkheden](/3.x/configuratie/module-dependency-guide.md) voor de volledige vereisten per module.
* De OpenKlant 2 module hield zich niet aan zijn eigen schakelaar. De client en de service van de module werden altijd aangemaakt, ook zonder `NLPORTAL_CONFIG_OPENKLANT2_ENABLED=true`. De GraphQL queries van de module keken al wel naar die variabele, dus functioneel was de module toen ook uit. De module respecteert de variabele nu volledig. Voor een deployment van de app image verandert er niets: zonder die variabele werkte OpenKlant 2 ook voorheen al niet.

## Breaking changes

Er zijn geen breaking changes.

## Deprecations

De legacy token exchange (v1) blijft in 3.x de standaard, maar is door Keycloak als verouderd gemarkeerd en wordt in een toekomstige Keycloak versie verwijderd. Keycloak voegt geen ondersteuning voor token exchange permissions toe aan Fine-Grained Admin Permissions v2, dus v1 blijft FGAP v1 vereisen.

De variabele `KEYCLOAK_TOKEN_EXCHANGE_VERSION` is nieuw in 3.1.0. In 4.x kan deze een andere naam krijgen of de standaardwaarde `v2` worden.

## Bekende problemen

Er zijn geen bekende problemen.