Het opnemen van versie-informatie in JWT-claims is een gangbare praktijk om je API-versies te beheren en te beveiligen. Hieronder vind je beste praktijken en strategieën: 1. Versie-informatie in de claims: - Voeg een aangepaste claim toe, bijvoorbeeld `"api_version"` of `"ver": "v1"` of `"version": 2`. - Plaats deze claim in de payload van de JWT, zodat de API de versie kan controleren bij elk verzoek. 2. Beveiliging en integriteit: - Gebruik altijd een sterke geheime sleutel (secret) voor het ondertekenen van de JWT, bijvoorbeeld met HS256 of een asymmetrisch algoritme zoals RS256. - Valideer de handtekening bij elke API-aanroep om de integriteit te waarborgen. - Controleer niet alleen de handtekening maar ook de geldigheidstermijn (`exp`) en andere relevante claims. 3. Beheer van meerdere versies: - Overweeg om verschillende API-versie-endpoints te gebruiken (bijvoorbeeld `/v1/`, `/v2/`) en de versie-informatie in de JWT te gebruiken voor extra controle. - Houd versie-informatie consistent tussen token-uitgifte en API-endpoints. - Indien nodig, implementeer een mechanisme om tokens te herroepen of te vernieuwen bij grote wijzigingen. 4. Strategieën om ongeautoriseerde toegang te voorkomen: - Controleer de `api_version` claim in de JWT en stem deze af op de versie die het endpoint ondersteunt. - Implementeer role-based access control (RBAC) of scope-claims die per versie verschillen. - Gebruik verschillende secret keys of ondertekeningen voor verschillende API-versies indien je dat wilt isoleren. - Voorkom dat tokens voor één versie worden gebruikt om toegang te krijgen tot andere versies door versie-specifieke validaties. 5. Extra tips: - Documenteer duidelijk welke versies ondersteund worden en onder welke voorwaarden tokens geldig zijn. - Overweeg het gebruik van "claims" zoals `aud` (audience) om te specificeren voor welke API of versie de token bedoeld is. - Zorg voor een goede levensduur van tokens en implementeer token-verversing indien nodig. Samenvattend: voeg de API-versie toe als een veilige claim, onderteken de JWT met een sterke sleutel, en controleer de versie bij elke API-aanroep om ongeautoriseerde toegang en version-mismatch te voorkomen.

Bij het opzetten van een versiesysteem voor je REST API met JWT zijn hier de aanbevolen stappen en best practices: ## 1. JWT Claims voor Versiebeheer ### Aanbevolen claim-structuur: ```json { "sub": "gebruiker123", "iss": "jouw-api", "exp": 1735689600, "api_version": "v1", "scope": ["read:data", "write:data"], "version_access": ["v1", "v2"] } ``` ### Veilige implementatie: - Gebruik een aangepaste claim zoals `api_version` of `version_access` - Beperk tokens tot specifieke versies via `version_access` array - Versleutel gevoelige claims indien nodig ## 2. Beste Praktijken voor API Versiebeheer ### Versie-strategieën: - **URL-paden**: `https://api.jouwdomein.nl/v1/resource` - **Request headers**: `Accept: application/vnd.jouwnaam.v1+json` - **Query parameters**: `?version=v1` (minder aanbevolen) ### Aanbevolen aanpak: ```http GET /v1/gebruikers HTTP/1.1 Authorization: Bearer <JWT_TOKEN> Accept: application/vnd.jouwdomein.v1+json ``` ## 3. Beveiligingsmaatregelen ### Token Validatie: ```javascript // Voorbeeld validatie logica function validateTokenAccess(token, requestedVersion) { const decoded = jwt.verify(token, secret); if (!decoded.version_access.includes(requestedVersion)) { throw new Error('Toegang tot deze API-versie niet toegestaan'); } return decoded; } ``` ### Beveiligingspraktijken: 1. **Korte token levensduur**: 15-30 minuten voor access tokens 2. **Strikte scope beperkingen**: ```json { "scope": ["v1:read", "v2:write"], "version_restrictions": {"v1": ["read"], "v2": ["write"]} } ``` 3. **Token intrekkingsmechanisme**: Zwartlijst ingetrokken tokens 4. **Sterke signing keys**: Gebruik RS256 of HS256 met sterke secrets ## 4. Implementatie Strategieën ### Middleware voor versie-controle: ```javascript app.use('/api/:version/*', (req, res, next) => { const token = req.headers.authorization?.replace('Bearer ', ''); const requestedVersion = req.params.version; try { const decoded = validateTokenAccess(token, requestedVersion); req.user = decoded; next(); } catch (error) { return res.status(403).json({ error: 'Versie-toegang geweigerd' }); } }); ``` ### Versie-deprecatie strategie: - **Deprecation headers**: `Deprecation: true`, `Sunset: Mon, 01 Jan 2024 00:00:00 GMT` - **Documenteer einddata** voor elke versie - **Migration guides** aanbieden ## 5. Ongeautoriseerde Toegang Preventie ### Beperk toegang per versie: - **Role-Based Access Control** (RBAC) per API-versie - **API Gateway** met versie-routing - **Rate limiting** per versie en gebruiker ### Monitoring en logging: - Log alle versie-toegang pogingen - Monitor voor verdachte patronen - Implementeer alerting bij misbruik ## 6. Aanvullende Aanbevelingen 1. **Backward compatibility** voor minstens 6 maanden 2. **Automatische tests** voor alle versies 3. **Documentatie** per versie 4. **Client libraries** versie-beheer Door deze strategieën te volgen, behoud je veilige toegangscontrole terwijl je flexibel meerdere API-versies kunt beheren.