Eigen app connector inrichten o.b.v. OAuth-token (vanaf Profit 9)
Je kunt Profit-connectoren aanroepen op basis van OAuth 2.1. OAuth is de wereldwijde standaard om externe applicaties veilig toegang te geven tot een ander systeem, zonder dat je wachtwoorden of vaste sleutels uitwisselt. AFAS ondersteunt twee methoden: de Client credentials flow en de Authorization code flow.
Een app connector kan gebaseerd zijn op classic tokens in plaats van OAuth, maar deze methode wordt uitgefaseerd. Heb je nog eigen app connectoren op basis van classic tokens? Stap voor 31 augustus 2027 over op een app connector gebaseerd op OAuth. Gebruik hiervoor vanaf Profit 9 de migratiewizard.
Let op:
Deze pagina is volledig gericht op Profit 9.
Werk je met Profit 8? Zie dan deze beschrijving van de Oauth-inrichting.
Je kunt een public client inrichten via de app connector (de bestaande app connector ging altijd uit van een confidential client). Wat is het verschil tussen een public client en een confidential client? Een confidential client kan een geheim (een client secret of een private key) veilig opslaan, een public client kan dit niet. Om je te helpen bij de inrichting selecteer je bij een nieuwe app connector eerst wat voor soort applicatie je wilt inrichten. Op basis hiervan bepaalt de wizard of je een confidential of public client nodig hebt.
De authenticatie is uitgebreid met ondersteuning van DPoP (dit is verplicht voor public clients).
Andere uitbreidingen:
- Signaal op verlopen laatste clientauthenticatie
Met een signaal op de verloopdatum van de laatste clientauthenticatie kun je automatisch een workflow starten of een e-mail versturen. Hiervoor gebruik je een signaal dat gebaseerd is op de nieuwe gegevensverzameling App connectoren: clientauthenticatie.
- Zie verder de uitbreidingen die hieronder beschreven zijn bij confidential client.
|
Inhoud |
App connector inrichten voor public client
Je maakt een app connector aan voor een public client. Dit is een client waarop geen geheim wordt opgeslagen, omdat dit door een kwaadwillende achterhaald kan worden.
Voorbeelden van een public client:
- Single-page application (SPA) die volledig in de browser draait.
- Mobiele app
- Desktopapplicatie of commandline-tool die op de computer van de gebruiker wordt geïnstalleerd.
Een public client heeft geen client secret en voert dus geen client authenticatie uit. In plaats daarvan zorgen deze maatregelen voor de beveiliging:
- De gebruiker logt zelf in bij Profit op basis van een Authorisation code flow in combinatie met PKCE. Dit voorkomt dat een onderschepte authorisation code door iemand anders kan worden ingewisseld.
- De tokenbeveiliging is altijd op basis van DPoP.
DPoP (Demonstrating Proof of Possession) koppelt een token aan een sleutelpaar dat deze applicatie zelf aanmaakt. Bij elke aanroep stuurt de applicatie een ondertekend bewijs mee dat zij de bijbehorende private sleutel bezit. Profit accepteert het token alleen samen met een geldig bewijs, waardoor een onderschept token niet in een andere applicatie of op een ander apparaat werkt.
Technische informatie en endpoints:
Verwijs je koppelpartner of de ontwikkelaar van je applicatie naar de API Docs voor een overzicht van de endpoints, codevoorbeelden, etc.
App connector aanmaken:
- Ga naar: Algemeen / Beheer / App connector.
- Klik op: Nieuw.
- Vul de omschrijving in.
- Selecteer OAuth bij het veld Type authenticatie.
- Selecteer Mobiele en desktopapplicatie of Single-page-application (SPA) bij het veld Type applicatie.
Let op:
Door de bovenstaande keuzen maak je een app connector van het type Public client aan. DPOP wordt hierbij verplicht ingeschakeld. Dit kun je achteraf niet meer wijzigen.
- Selecteer de autorisatiegroep waarvan de leden de app connector mogen gebruiken.
- Vul de url van de externe applicatie in bij Redirect url.
- Klik op: Voltooien.
- De eigenschappen van de app connector worden geopend. Je kunt de OAuth client id kopiëren.
Let op:
Je OAuth client id wel raadplegen via de eigenschappen van de app connector, maar niet wijzigen.
App connector inrichten voor confidential client
Je maakt een app connector aan voor een confidential client. Een confidential client kan een client secret veilig opslaan. De app connector biedt echter ook technieken waarbij dit niet nodig is.
Je kon een app connector op basis van OAuth inrichten met de methoden Client credentials flow en Authorisation code flow. Hieronder zie je de uitbreidingen voor Profit 9.
Als je begint met een nieuwe app connector, dan baseer je deze op een Webapplicatie of Systeemservice. Deze keuze bepaalt je mogelijkheden bij de inrichting van de app connector. Een Systeemservice is altijd gebaseerd op de Client credentials flow, bij een Webapplicatie heb je de keuze tussen Client credentials flow en Authorisation code flow.
Bij de Webapplicatie of Systeemservice maak je een keuze:
- Je gebruikt client secrets (al bekend van Profit 8)
Vanaf Profit 9 heeft de client secret een vaste geldigheidsduur van maximaal 2 jaar. Je kunt nu gebruik maken van een roterend client secret (je kunt meerdere client secrets per app connector opslaan).
Als de laatste geldige client secret binnen 14 dagen verloopt, dan wordt dit gemeld op Profit Home. Als er nog een andere client secret is met een langere geldigheidsduur, dan is er geen melding op Profit Home.
- Je kunt de geldigheid van client secrets opvragen via de api. Als je de metainfo van een App Connector ophaalt, dan krijg je ook de client secret metadata terug inclusief de verloopdatum.
- Je gebruikt JWT in plaats van een client secret (nieuw in Profit 9)
Hierbij doe je een tokenaanvraag op basis van een eenmalige, kortlevende Json Web Token.
Toepassing van DPoP (Demonstrating Proof of Possession) is optioneel, Hierbij wordt een token aan een sleutelpaar gekoppeld dat deze applicatie zelf aanmaakt. Bij elke aanroep stuurt de applicatie een ondertekend bewijs mee dat zij de bijbehorende private sleutel bezit. Profit accepteert het token alleen samen met een geldig bewijs, waardoor een onderschept token niet in een andere applicatie of op een ander apparaat werkt.
Technische informatie en endpoints:
Verwijs je koppelpartner of de ontwikkelaar van je applicatie naar de API Docs voor een overzicht van de endpoints, codevoorbeelden, etc.
App connector aanmaken voor een Systeemservice:
Een Systeemservice is altijd gebaseerd op de Client credentials flow.
- Ga naar: Algemeen / Beheer / App connector.
- Klik op: Nieuw.
- Vul de omschrijving in.
- Selecteer OAuth bij het veld Type authenticatie.
- Selecteer Systeemservice bij het veld Type applicatie.
- Bepaal of je DPOP wilt gebruiken.
- Bepaal de Clientauthenticatiemethode: op basis van een client secret of JWK (Jason web token.
Let op:
Je kunt de bovenstaande keuzen niet meer wijzigen, behalve het veld DPoP. Dit veld kun je na het aanmaken van de app connector nog aan -of uitvinken.
Na het aanmaken van de app connector maakt Profit automatisch een gebruikersgroep en een systeemgebruiker aan met de naam van de app connector.
- Klik op: Voltooien.
- De eigenschappen van de app connector worden geopend. Je kunt de OAuth client id kopiëren.
Let op:
Je OAuth client id wel raadplegen via de eigenschappen van de app connector, maar niet wijzigen.
App connector aanmaken voor een Webapplicatie:
- Ga naar: Algemeen / Beheer / App connector.
- Klik op: Nieuw.
- Vul de omschrijving in.
- Selecteer OAuth bij het veld Type authenticatie.
- Selecteer Webapplicatie bij het veld Type applicatie.
- Bepaal of je DPOP wilt gebruiken.
- Bepaal of je de Client credentials flow en Authorisation code flow wilt gebruiken.
- Bij de Authorisation code flow selecteer je de Profit-gebruikersgroep en vul je de redirect url in.
- Bij de Client credentials flow maakt Profit automatisch een gebruikersgroep en een systeemgebruiker aan met de naam van de app connector.
- Bepaal de Clientauthenticatiemethode: op basis van een client secret of JWK (Jason web token.
Let op:
Je kunt de bovenstaande keuzen niet meer wijzigen, behalve het veld DPoP. Dit veld kun je na het aanmaken van de app connector nog aan -of uitvinken.
Na het aanmaken van de app connector maakt Profit automatisch een gebruikersgroep en een systeemgebruiker aan met de naam van de app connector. Je
- Klik op: Voltooien.
- De eigenschappen van de app connector worden geopend. Je kunt de OAuth client id kopiëren.
Let op:
Je OAuth client id wel raadplegen via de eigenschappen van de app connector, maar niet wijzigen.
Vervolgstappen
Na het aanmaken van een app connector wordt deze automatisch geopend. Voer in ieder geval de volgende stappen uit:
- Selecteer de
Get- en UpdateConnectoren die via de app connector mogen worden aangeroepen. - Op het tabblad Connectoren vind je enkele speciale connectoren. De meestgebruikte is AppConnectorSubject, deze is nodig voor het openen van bijlagen bij dossieritems.
- Kijk of je nog IP-restricities moet vastleggen.
- Ga naar de Autorisatie tool en richt de filterautorisatie voor de gebruikersgroep in.
Filterautorisatie instellen voor het ophalen van gegevens
De GetConnectoren die je de app connector gaat opnemen, kunnen alleen records ophalen voor zover dit is toegestaan op basis van de filterautorisatie. Wil je bijvoorbeeld medewerkergegevens ophalen via een app connector, dan moet dit zijn toegestaan op basis van filterautorisatie op medewerker.
Autoriseer de gebruikersgroep NIET voor functies (menu-items), tabbladen en acties. Het is immers niet de bedoeling dat via deze gebruikersgroep in Profit gewerkt wordt.
Filterautorisatie uitdelen:
- Ga naar het tabblad: Onderhoud groepen.
- Selecteer de gebruikersgroep. Als je automatisch een gebruikersgroep hebt aan laten maken, dan heeft deze dezelfde naam als de naam van de app connector.
- Ga naar het tabblad: Autorisatie.
- Deel rechten uit op de juiste filters.
Zie ook: