File API - OAuth 2.0 Demonstrating Proof-of-Possession (DPoP)

[#1]

Deze releasenotes zijn technisch van aard en bedoeld voor File API-ontwikkelaars die direct met de File API integreren of bekend zijn met de technische werking ervan.

Deel deze release notes graag met de IT-afdeling van jullie organisatie.

Inleiding

De file API maakt op dit moment gebruik van het veilige OAUTH 2.0 protocol om gebruikers te authenticeren en bestanden uit te wisselen. Dit OAUTH 2.0 protocol is een wereldwijde standaard voor gegevensuitwisseling via API’s en wordt beschouwd als zeer veilig. Een 100% veiligheid is in onze huidige IT wereld echter moeilijk te garanderen. We proberen dan ook steeds de kansen op gegevensverlies nog verder  te minimaliseren. Zo is er ook voor het OAUTH 2.0 protocol een uitbreiding bedacht die deze kansen nog verder minimaliseert, de DPOP-token implementatie.

Het implementeren van het DPoP token vereist een programmatische aanpassing aan de klantzijde. Daarom is deze optie vooral bedoeld voor klanten die zelf software ontwikkelen/hebben ontwikkeld voor gebruik met de File API.

Neem zo nodig contact op met je IT afdeling of dit voor jullie een optie is.

Gebruiken jullie op dit moment de powershell scripts om met de File API te communiceren, houd dan dit kanaal in de gaten. In de nabije toekomst zullen we het DPoP-token ook in de powershell scripts implementeren.

Huidige situatie

Momenteel ondersteunt de File API geen DPoP-tokens als OAuth-bewijstype.

Nieuwe situatie

Vanaf vandaag, 26 februari 2025, worden DPoP-tokens ook ondersteund.

Jouw actie:

Indien je er zorg voor wilt dragen dat uitsluitend de rechtmatige ‘client’ een specifiek toegangstoken kan gebruiken, kun je de DPoP-stroom implementeren in je File API applicatie. Zodra de wijzigingen aan jullie kant zijn geïmplementeerd, kan je de onderstaande toggle activeren in het Visma Developer Portal → My Applications → Details. Deze wijziging zorgt voor een nog betere beveiliging van jouw File AP integratie.

Officiële specificatie:

RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession (DPoP)

Ondersteunde cryptografische algoritmen:

Onze implementatie hanteert strikte beveiligingsmaatregelen en ondersteunt uitsluitend de volgende cryptografische algoritmen:

RSA: RS256, RS384, RS512, PS256, PS384, PS512

ECDSA: ES256, ES384, ES512

Het gebruik van het algoritme 'none' wordt expliciet geweigerd.

Unieke identificator voor de DPoP-proof JWT:

Deze implementatie bevat een validatie om reply-aanvallen te voorkomen. Hiervoor worden de waarden die in de jti-claim worden verzonden gedurende het geldigheidsvenster opgeslagen, zodat wordt gewaarborgd dat deze waarde uniek is en slechts één keer wordt gebruikt. Zorg ervoor dat je bij elke aanvraag een unieke GUID opgeeft in de jti-claim.

[Lieke Sterk Huis]

Hallo @Cristo Amezcua, ik weet niet of dit voor onze organisatie geldt. Kan ik ergens zien waarvoor wij de File API gebruiken? 

[Cristo Amezcua]

Hi @Lieke Sterk Huis , Ja, in de Visma Developer Portal kun je zien dat jouw organisatie 3 applicaties heeft om te integreren met de file API.

• Voor Bint-bestanden: Deze applicatie is geïntegreerd met de File API, maar er zijn de afgelopen 30 dagen geen bestanden uitgewisseld. Misschien is deze applicatie niet meer nodig.
• Voor DataFeed-bestanden:  is geïntegreerd met de File API en wordt gebruikt.
• Voor SIVI-bestanden:  is geïntegreerd met de File API en wordt gebruikt.

Met vriendelijke groet.

[Lieke Sterk Huis]

@Cristo Amezcua, dank voor je melding. Als functioneel beheerder weet ik nu niet of er voor ons dan een actie in zit. Kun jij mij hierin verder helpen?

[AngelaHeins]

@Cristo Amezcua , heb dezelfde vraag als Lieke.

Ik zie wel een FileAPI in het developer portaal, maar weet niet of wij nu een actie dienen uit te voeren. verneem dit graag. 

[Cristo Amezcua]

Hoi @Lieke Sterk Huis en @AngelaHeins 

Kunnen jullie deze release-opmerkingen delen met de IT-afdeling? Dit is een beveiligingsverbetering voor jullie File API-integraties. Het is niet verplicht, dus jullie organisatie moet beslissen of jullie dit willen implementeren.

Ik heb zojuist het artikel bijgewerkt en een "Inleiding"-sectie toegevoegd om het duidelijker te maken. Laat het me weten als er nog verduidelijking nodig is!

[R Gorissen]

@Cristo Amezcua Inmiddels de releasenote gedeeld met onze ict afdeling, maar ik krijg een heleboel vragen terug.

Jullie geven aan dat het  een beveiligingsverbetering voor de File API-integraties. Dat het niet verplicht is en een eigen keuze van de organisatie of je het implementeert.

Ondanks de toegevoegde inleiding is het voor onze ict afdeling niet duidelijk of het voor onze organisatie geldt en wat de nut, noodzaak en gevolg is van het aanzetten.

Hoe zie je of het voor jouw organisatie geldt?

Wat zijn de specifieke acties die ze moeten ondernemen? Is alleen het omzetten van het schuifje 'Require Demonstrating Proof-of Possesion' voldoende per API of moet er dan nog aanvullend iets gebeuren? Bijvoorbeeld richting de andere partij waarmee de API loopt (denk aan SIVI).

Hoop dat je dat nog kunt verduidelijken.

[Ronald Kramers]

@R Gorissen  Excuus voor de verlate reactie. 

Het OAUTH 2.0 protocol wordt, zoals in de inleiding genoemd, het meest gebruikt en is ook zeer veilig in gebruik.

De DPoP beveiliging is een extra uitbreiding bovenop het OAUTH 2.0 protocol die een heel specifiek hacker mechanisme beveiligd. Heel simpel gezegd zorgt het er voor dat als een hacker jouw File Api request 'vangt', en vervolgens zelf probeert te gebruiken richting File API, de DPoP beveiliging er voor zorgt dat zijn request wordt afgekeurd. 

De IT-afdeling van sommige van onze klanten stelden als eis dat wij deze beveiligingsoptie implementeerden voordat zij gebruik zouden gaan maken van de FileApi. Of het voor jullie organisatie noodzakelijk is om dit gebruiken, is afhankelijk van de eisen die jullie IT-afdeling aan dit soort API verbindingen stelt. Voor de meeste klanten is de standaard OATH 2.0 veilig genoeg. Het is dus een keuze van jullie organisatie of je hiervan gebruik wilt maken.

Op dit moment is deze optie alleen beschikbaar voor klanten die zelf software hebben ontwikkeld voor communicatie met de File API. Behalve dat je het schuifje om moet zetten in de Portal, moet jouw software namelijk ook het DPoP-token gaan ondersteunen.

Als jullie gebruik maken van onze Powershell scripts om met de File API te communiceren houd dan dit kanaal in de gaten. Binnen afzienbare tijd zullen we nieuwe scripts beschikbaar stellen die ook deze DPoP beveiliging ondersteunen.

Het configureren van DPoP heeft alleen impact op de API's en de software die deze API's gebruikt waarvoor je het schuifje om hebt gezet. Het heeft dus geen gevolgen voor de ontvangers en/of inzenders van jullie bestanden.