Wat is data scoping op Exact Online?

Data scoping is het beperken van de mogelijk toegankelijke groepen van data voor een publiceerbare applicatie op Exact Online. Data scoping is naast het toekennen van rechten aan gebruikers, division scoping en het licentiëren van modules binnen Exact Online een van de manieren om de rechten te controleren, alhoewel informatiebeveiligingstechnisch de waarde nog beperkt is. Het totaalplaatje voor het bepalen van de rechten van een Exact Online API aanroep is te vinden in Exact Online API rechten van een user op specifieke endpoint.

Zoek je naar het beperken van rechten op administraties in zijn geheel voor een applicatie? Lees dan meer over “division scoping” in Wat is division scoping?.

Hoe werkt data scoping?

De uitgever van een applicatie (ook “app” of “client”) kan bij Exact Online in het App Center aangeven dat deze applicatie toegang nodig heeft tot bepaalde zogenaamde “scopes”. Het opvoeren van een applicatie is onderdeel van het maken van een API koppeling.

Het invullen zit achter de knop “Bewerken” bij “Stap 1: Beoordeling: gegevens en beveiliging” in het tabblad “Laten Beoordelen”:

Een scope is een groep van data elementen uit een API. Voorbeelden van scopes zijn: (lezen van) klantgegevens en (aanmaken van) memoriaalboekingen.

De technische namen van scopes zijn opgebouwd uit een groepering, een decimale punt (’.’) en een naam binnen de groepering. Voorbeelden van de technische namen van dergelijke scopes op Exact Online zijn:

  • financial.accounting
  • financial.generalledgers
  • logistics.items
  • organization.administration
  • purchase.orders
  • sales.invoices
  • sales.orders

Aan elke scope zijn een aantal Exact Online REST API’s gekoppeld. Daarnaast maakt Exact Online onderscheid tussen enerzijds “alleen lezen” en anderzijds “lees- en schrijftoegang”.

Data scoping geldt uitsluitend voor publiceerbare en gepubliceerde applicaties. Zelfgeregistreerde applicaties kennen geen data scoping; zelfgeregistreerde applicaties hebben alleen toegang tot administraties binnen het abonnement of waar rechten op gegeven zijn aan een accountant door een gekoppelde ondernemer.

Bij het eerste gebruik van een applicatie wordt aan de gebruiker toestemming gevraagd via het zogenaamde “consent form” of de applicatie gekoppeld mag worden. Hierbij ziet de gebruiker een lijst van de gevraagde scopes en kan de gebruiker rechten op administraties toekennen.

De gebruiker kan niet zelfstandig afwijken van de scopes; hij accepteert de scopes als geheel of hij accepteer ze niet. Op andere platformen zoals Facebook of Teamleader kan programmatuur ook een deel van de scopes aanvragen die een applicatieregistratie biedt.

Bij het ophalen uit en schrijven van data naar Exact Online horen alle acties via de Exact Online REST API gecontroleerd te worden tegen de scopes.

Merk op dat scopes op Exact Online alleen gelden voor de REST API’s. Onder andere de XML API’s worden momenteel niet beveiligd via scopes.

Beperkingen

Data scoping kan uiteindelijk gebruikt worden om de beveiliging te verbeteren. Toch zijn er een aantal beperkingen en/of bugs waardoor de toegevoegde waarde qua beveiliging momenteel nog nihil is uitgaande van een kwaadwillende toepassing:

  • Data scoping geldt niet voor XML API’s.
  • Data scoping geldt ook voor een geleende applicatie, waarbij publieke informatie voldoende is.
  • Data scoping lijkt soms niet gecontroleerd te worden.
  • Data scoping lijkt soms te vaak gecontroleerd te worden.

Data scoping omzeilen via XML API’s

Data scoping is momenteel niet van toepassing voor de Exact Online XML API’s.

Een aanroep naar de lijst van administraties via de Exact Online REST API faalt bijvoorbeeld op basis van de scopes:

https://start.exactonline.nl/api/v1/123456/system/Divisions

met resultaat:

{
    "error": {
        "code": "",
        "message": {
            "lang": "",
            "value": "Forbidden - Application Scope Violated. Cannot read 'organization.administration' scope"
        }
    }
}

Via de XML API lukt het echter wel om de gegevens op te vragen:

https://start.exactonline.nl/docs/XMLDownload.aspx?topic=Administrations&Division=123456

<?xml version="1.0" encoding="utf-8"?>
<eExact xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="eExact-XML.xsd">
	<Administrations>
		<Administration code="760970" number="2">
			<Name>DEMO</Name>
...
		</Administration>
	</Administrations>
	<Topics>
		<Topic code="Administrations" ts_d="0x00000000C35288E3" count="221" pagesize="1000" />
	</Topics>
	<Messages />
</eExact>

Scoping omzeilen via een andere applicatie

Data scoping wordt per applicatie ingesteld en geldt alleen (behoudens bugs) voor gepubliceerde applicaties. Om gegevens uit te wisselen namens een applicatie kan volstaan worden met openbaar verkrijgbare informatie; het is niet nodig om het zogenaamde “client secret” te kennen.

Niet controleren op toegekende scopes of juist te vaak controleren

Alhoewel sommige applicaties last hebben van onterechte controles op scoping, geldt ook dat sommige applicaties ondanks restrictieve rechten toch toegang houden tot Exact Online REST API’s die buiten de toegekende scopes vallen.

De applicatie met client ID 843…ce8 heeft op basis van de scopes geen toegang tot artikelen of relaties, maar kan toch artikelen en relaties ophalen.