> 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/configuratie/keycloak/keycloak-token-exchange-v1.md).

# Legacy token exchange (v1)

**Deze variant wordt uitgefaseerd.** Keycloak heeft de legacy token exchange als verouderd gemarkeerd en verwijdert hem in een toekomstige versie. Draai je Keycloak 26.2 of nieuwer, richt dan [Standard token exchange (v2)](/3.x/configuratie/keycloak/keycloak-token-exchange-v2.md) in.

Deze pagina beschrijft de configuratie zoals die tot en met 3.0.x de enige mogelijkheid was. In 3.1.0 blijft v1 de standaardwaarde, dus een bestaande omgeving hoeft niets te veranderen.

Houd er wel rekening mee dat deze variant `admin-fine-grained-authz:v1` afdwingt voor de hele Keycloak server, en daarmee Fine-Grained Admin Permissions v2 blokkeert voor alle realms op die server. Zie [Keycloak configuratie](/3.x/configuratie/keycloak.md) voor de gevolgen.

## Vereiste server features

NL Portal gebruikt bij deze variant de legacy token exchange van Keycloak in combinatie met fine-grained admin permissions. Beide features moeten expliciet aangezet worden via de `KC_FEATURES` environment variabele van Keycloak. De juiste waarde verschilt per Keycloak versie:

| Keycloak versie | KC\_FEATURES                                    |
| --------------- | ----------------------------------------------- |
| ≤ 24            | `token-exchange,admin-fine-grained-authz`       |
| ≥ 26            | `token-exchange:v1,admin-fine-grained-authz:v1` |

**Let op:** vanaf Keycloak 26 activeert de vlag `token-exchange` zónder suffix de v2-variant; de `:v1` suffix is daarom verplicht.

## Realm en clients

Bij deze variant zijn drie clients nodig:

| Client (voorbeeldnaam)     | Type                                       | Doel                                                                                           |
| -------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `nl-portal`                | public, standard flow                      | Login van de frontend (SPA). Draagt de `middel` mapper.                                        |
| `nl-portal-m2m`            | confidential, service accounts, met secret | Voert de token exchange uit namens de backend.                                                 |
| `nl-portal-token-exchange` | public, geen flows                         | Doelclient (audience) van de token exchange. Bevat de `aanvrager.bsn`/`aanvrager.kvk` mappers. |

De derde client bestaat alleen om die twee mappers te dragen. Keycloak bouwt de nieuwe token bij v1 op basis van de doelclient, en dus vuren de mappers van die client.

## Backend configuratie

```yaml
nl-portal:
    authentication:
        keycloak:
            token-exchange-version: v1
            resource: nl-portal-m2m
            audience: nl-portal-token-exchange
            credentials:
                secret: <secret van de m2m client>
```

Of met de environment variabelen van de app image:

```
KEYCLOAK_CLIENT_ID=nl-portal-m2m
KEYCLOAK_CLIENT_SECRET=<secret van de m2m client>
KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE=nl-portal-token-exchange
```

`KEYCLOAK_TOKEN_EXCHANGE_VERSION` hoeft niet gezet te worden, `v1` is de standaardwaarde. De audience is bij deze variant verplicht en moet de doelclient noemen. Ontbreekt hij, dan meldt de applicatie dat bij het opstarten en faalt de eerste token exchange met een melding die de property benoemt.

## Hoe moet je Keycloak instellen

Maak een nieuwe client aan voor de backend.

![tokenexchange1](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-d9e4fdbd67015973603d50f8388c02607b1a9f74%2Ftokenexchange-1.png?alt=media)

![tokenexchange2](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-d2fce5b401f7b56f7c392a8ab0bc74919baa312d%2Ftokenexchange-2.png?alt=media)

Op de credentials tab vind je de secret key die je in de application yaml moet zetten.

![tokenexchange3](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-d21a95521148c36c80d776968bd7d0520e4cfded%2Ftokenexchange-clientSecret.png?alt=media) ![tokenexchange4](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-5830bab79a5087d5a55bd559db0110f88a699397%2Ftokenexchange-yamlconfig.png?alt=media)

LET OP: niet zomaar op regenarate klikken dan veranderd de key en kan je niet de oude meer terug zetten.

Hierna creëer je nog een client deze is voor de token exchange. ![generalsettings1](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-7e27f8e6055db0fb813aabeaa5f8a23bc3da3a23%2Ftokenexchange-generalsettings-1.png?alt=media) ![generalsettings2](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-b6937c23c3ce93561c22838344f85711c63af8cb%2Ftokenexchange-generalsettings-2.png?alt=media)

Navigeer naar de ‘Client scopes’ tab. Hier klik je op de 1e client scope.

![clientscopes](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-0808bd6100e0c70782ef2be06fdbafc6faf7c576%2Ftokenexchange-clientscopes.png?alt=media)

In ons geval met de naam ‘gzac-portal-token-exchange-dedicated’.

Hierin komen de mappers van de bsn en kvk.

![mappers](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-de7d59751899f61b4fc73e56862ba14ecbd5cbff%2Ftokenexchange-mappers.png?alt=media)

Ga terug naar client details en navigeer nu naar de tab ‘Permissions’.

Zorg dat de ‘permissions enabled’ op ‘on’ staat.

Je krijgt een permissions list te zien. Navigeer naar ‘token exchange’.

![permission-list](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-4523566717e7e3f443d22a0d641e1266fd653fd2%2Ftokenexchange-permissionslist.png?alt=media)

Hierin moet je een nieuwe polici maken om de backend client toegang te geven tot een token exchange.

![policy-config](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-78cf43c9c0909fefedf43d39837eecd89e611ee1%2Ftokenexchange-policy-config.png?alt=media)

De policy.

![policy](https://1550375435-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQdi04LeIpn6e3s4P9IUP%2Fuploads%2Fgit-blob-b28a92841721f080b65eb91e45af6766122a40d5%2Ftokenexchange-policy.png?alt=media)

Hierna moet je nog naar de ‘oude’ al bestaande client om de mappers(kvk en bsn) weg te gooien bij de al bestaande client die nu alleen nog gebruikt zal worden door de frontend.

In de backend moet je nu per omgeving een parameter zetten die de secret en de resource heeft om de token exchange succesvol te kunnen runnen.

## Foutmeldingen

| Melding van Keycloak                                              | Oorzaak                                                                                                               |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Standard token exchange is not enabled for the requested client` | De `KC_FEATURES` vlaggen ontbreken of missen de `:v1` suffix, waardoor Keycloak het verzoek naar de v2 engine stuurt. |