Eigen app connector inrichten in vogelvlucht (OAuth-token)
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.
Je kunt dit stappenplan o.a. gebruiken als een partner je vraagt om een app connector toe te voegen aan een omgeving. Wil je de app connector handmatig aanmaken (zonder automatisch een gebruikersgroep, connector-gebruiker en token aan te maken)? Lees dan deze beschrijving.
Je kunt ook een app connector aanmaken op basis van 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.
Beschrijving
Deze beschrijving bevat extra informatie over de door AFAS ondersteunde OAuth-methoden.
Waarom OAuth?
Bij een classic token gebruikt de externe applicatie bij elke aanroep dezelfde vaste sleutel (token). Zo'n sleutel blijft vaak jaren geldig. Lekt de sleutel uit, dan heeft een kwaadwillende dus lang toegang tot je omgeving.
OAuth lost dit op met tijdelijke toegang:
- De externe applicatie logt eerst in met een client id en client secret (of via de gebruiker zelf).
- De applicatie krijgt daarvoor een access-token terug. Alleen dit token gaat mee in de aanroepen naar Profit.
- Een access-token is maar 1 uur geldig. Daarna is het waardeloos. Lekt een access-token uit, dan is de schade dus beperkt.
- De vaste gegevens (client id en client secret) worden alleen gebruikt bij het aanvragen van een token, niet bij elke aanroep.
Daarnaast is OAuth een open standaard. Vrijwel elke programmeertaal en elk integratieplatform heeft kant-en-klare ondersteuning voor OAuth. Leveranciers hoeven dus geen AFAS-specifieke oplossing te bouwen.
Client credentials flow
Gebruik deze flow als twee systemen met elkaar praten, zonder dat een gebruiker zelf inlogt (machine-to-machine). Bijvoorbeeld: een koppeling die elke nacht automatisch mutaties ophaalt uit Profit.
Zo werkt de flow:
- De externe applicatie stuurt de client id en de client secret naar het token endpoint.
- Profit controleert de gegevens en stuurt een access-token terug.
- De applicatie roept met dit access-token de gekoppelde Get- en UpdateConnectoren aan. De aanroepen gebeuren namens de gebruiker die je bij de app connector hebt geselecteerd.
- Na 1 uur verloopt het access-token. De applicatie herhaalt dan stap 1 en 2.
Deze flow gebruikt geen refresh-tokens. Dat is ook niet nodig: de applicatie heeft de client id en client secret zelf en kan daarmee altijd een nieuw access-token aanvragen.
Let op: Behandel de client secret als een wachtwoord. Sla deze nooit op in broncode of in een script dat anderen kunnen inzien. Gebruik hiervoor een geheimenbeheerder (secret manager) of een beveiligde configuratie.
Authorization code flow
Gebruik deze flow als een gebruiker zelf inlogt in een externe applicatie of portal, en die applicatie namens de gebruiker gegevens uit Profit nodig heeft. De gebruiker geeft de applicatie toegang zonder zijn wachtwoord met de applicatie te delen.
Zo werkt de flow:
- De externe applicatie stuurt de gebruiker naar het authorize endpoint van AFAS.
- De gebruiker logt in bij AFAS Online. Heb je single sign-on ingericht? Dan logt de gebruiker in via je eigen identity provider.
- Profit controleert of de gebruiker lid is van de autorisatiegroep die aan de app connector gekoppeld is.
- Na het inloggen stuurt AFAS de gebruiker terug naar de redirect url van de applicatie, met een eenmalige authorization code.
- De applicatie wisselt deze code bij het token endpoint in voor een access-token en een refresh-token. Hierbij stuurt de applicatie ook de client id en client secret mee, zodat Profit zeker weet dat de code bij de juiste applicatie terechtkomt.
- De applicatie roept met het access-token de connectoren aan, namens de ingelogde gebruiker.
- Is het access-token verlopen? Dan haalt de applicatie met de refresh-token een nieuw access-token op. De gebruiker merkt hier niets van en hoeft niet opnieuw in te loggen.
Let op:
AFAS gebruikt roterende refresh-tokens. Bij elke vernieuwing krijgt de applicatie een nieuwe refresh-token en vervalt de oude. Probeert iemand een oude (bijvoorbeeld gestolen) refresh-token te gebruiken, dan valt dit direct op. De applicatie moet de nieuwste refresh-token dus steeds opslaan.
Een groot voordeel van deze flow: de aanroepen gebeuren onder de identiteit van de ingelogde gebruiker. De autorisatie en filterautorisatie van die gebruiker bepalen dus welke gegevens de applicatie ziet. Bij de Client credentials flow geldt altijd de autorisatie van de vaste gebruiker van de app connector.
Welke methode kies je?
|
Client credentials flow |
Authorization code flow |
Wie logt in |
De applicatie zelf |
De gebruiker |
Typisch gebruik |
Automatische koppelingen, geplande taken, systeem-naar-systeem |
Portals en apps waarin gebruikers zelf werken |
Autorisatie in Profit |
Op basis van één vaste gebruiker |
Op basis van de ingelogde gebruiker |
refresh-token |
Nee |
Ja (roterend) |
Redirect url nodig? |
Nee |
Ja |
Endpoints o.b.v. OAuth (Authorization code flow en/of Client credentials)
Voor OAuth gebruikt de externe applicatie deze endpoints:
Omschrijving |
Endpoint |
Authorization code flow starten en code inwisselen |
/oauth/authorize |
access_token & refresh_token ophalen |
/oauth/token |
Een volledige endpoint voor een productieomgeving is bijvoorbeeld https://12345.rest.afas.online/profitrestservices/oauth/token. Bij test- en acceptomgevingen gelden andere endpoints.
Zie ook de technische informatie.
App connector o.b.v. Authorisation code flow aanmaken
Je maakt een nieuwe app connector aan die de Authorisation code flow gebruikt. Dit type app connector is met name geschikt voor gebruikers van een externe applicatie die zelf via een portal inloggen en daarna namens zichzelf een access-token krijgen om AFAS-connectoren aan te roepen.
Een access-token is 1 uur geldig. Na verloop ververst de applicatie de token met de refresh_token-grant. AFAS gebruikt roterende refresh_tokens: bij iedere vernieuwing krijg je een nieuwe refresh-token en de oude vervalt.
De beheerder kan in de AFAS Online portal eventueel een andere identity provider selecteren. Je richt de identity provider in op het tabblad Identity provider. Vervolgens ga je naar het tabblad Single sign-on en koppel je de identity provider.
De maker van de externe applicatie heeft de volgende informatie nodig. Bij test- en accept-omgevingen moet je de url uiteraard nog aanpassen.
- Token endpoint:
https://<omgevingsnummer>.rest.afas.online/profitrestservices/oauth/token
Bijvoorbeeld:
https://12345.rest.afas.online/profitrestservices/oauth/token
- Authorize endpoint:
https://<omgevingsnummer>.rest.afas.online/profitrestservices/oauth/authorize
Bijvoorbeeld:
https://12345.rest.afas.online/profitrestservices/oauth/authorize
App connector aanmaken:
- Ga naar: Algemeen / Beheer / App connector.
- Klik op: Nieuw.
- Vul de omschrijving in.
- Selecteer OAuth bij het veld Authenticatieype.
Let op:
Na het aanmaken van een app connector kun je het authenticatietype niet meer wijzigen.
- Selecteer de autorisatiegroep waarvan de leden de app connector mogen gebruiken om zich aan te melden via de Authorisation code flow.
- Selecteer Code bij Type OAuth flow.
- Vul de url van de externe applicatie in bij Redirect url.
- Selecteer de gewenste
Get- en UpdateConnectoren in de volgende stappen. - In het laatste scherm zie je de OAuth client id en de OAuth client secret.
Kopieer beide waarden en sla deze op een veilige plaats op.
Let op:
Na het voltooien van de wizard kun je OAuth client id nog wel raadplegen via de eigenschappen van de app connector, maar niet meer wijzigen.
De OAuth client secret kun je niet meer raadplegen EN niet meer wijzigen. Wel kun je een nieuwe OAuth client secret genereren, deze vervangt dan de oude. Als je een nieuwe OAuth client secret genereert, kan de oude niet meer gebruikt worden.
- Klik op: Voltooien.
Vervolgstappen:
De app connector wordt automatisch geopend.
- 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.
App connector o.b.v. Client credentials aanmaken
Je maakt een nieuwe app connector aan die de Client Credentials Flow gebruikt. Dit betekent dat de connector-gebruiker zich bij de API authentiseert met de client-id en de client-secret. Hiermee kun je een access-token ophalen. In deze flow worden geen refresh-tokens verstrekt, omdat de applicatie zelf altijd een nieuw access-token kan aanvragen wanneer dat nodig is.
Een access-token is 1 uur geldig. Na verloop ververst de applicatie de token met de refresh_token-grant. AFAS gebruikt roterende refresh_tokens: bij iedere vernieuwing krijg je een nieuwe refresh-token en de oude vervalt.
App connector aanmaken:
- Ga naar: Algemeen / Beheer / App connector.
- Klik op: Nieuw.
- Vul de omschrijving in.
- Selecteer OAuth bij het veld Authenticatieype.
Let op:
Na het aanmaken van een app connector kun je het authenticatietype niet meer wijzigen.
- Selecteer de autorisatiegroep waarvan de leden de app connector mogen gebruiken om zich aan te melden via de Authorisation code flow.
- Selecteer Client credentials bij Type OAuth flow.
- Je selecteert de gebruiker die zich mag aanmelden bij de api.
- Selecteer de gewenste Get- en UpdateConnectoren in de volgende stappen.
- In het laatste scherm zie je de OAuth client id en de OAuth client secret.
Kopieer beide waarden en sla deze op een veilige plaats op.
Let op:
Na het voltooien van de wizard kun je OAuth client id nog wel raadplegen via de eigenschappen van de app connector, maar niet meer wijzigen.
De OAuth client secret kun je niet meer raadplegen EN niet meer wijzigen. Wel kun je een nieuwe OAuth client secret genereren, deze vervangt dan de oude. Als je een nieuwe OAuth client secret genereert, kan de oude niet meer gebruikt worden.
- Klik op: Voltooien.
Vervolgstappen:
De app connector wordt automatisch geopend.
- 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.
Combinatie van Authorisation code flow en Authorisation Client credentials aanmaken
Je maakt een app connector aan die de methoden Authorisation code flow en Authorisation Client credentials ondersteunt. Aanmelden kan op de volgende manieren:
- Gebruikers van een externe applicatie melden zich aan op basis van de Authorisation code flow.
- Eén gebruiker kan zich aanmelden via de methode Client credentials (dus aanmelden met client-id en client-secret). In de eigenschappen van de app connector vind je deze gebruiker op het tabblad Algemeen.
App connector aanmaken:
Lees de toelichtingen op deze pagina. Bij het aanmaken van de app connector gebruik je de volgende instellingen:
- Authenticatietype: OAuth
- Type OAuth flow: Beide
Combinatie van Classic token, Authorisation code flow en Authorisation Client credentials aanmaken
Je maakt een app connector aan die zowel Classic token, Authorisation code flow en Client credentials ondersteunt. Aanmelden kan op de volgende manieren:
- Gebruikers van een externe applicatie melden zich aan op basis van de Authorisation code flow. Dit is mogelijk voor alle leden van de gebruikersgroep die aan de app connector gekoppeld is.
- Gebruikers van een externe applicatie melden zich aan op basis van een Classic token. Dit is mogelijk voor alle leden van de gebruikersgroep die aan de app connector gekoppeld is EN die een classic token hebben.
- Eén gebruiker kan zich aanmelden via de methode Client credentials (dus aanmelden met client-id en client-secret). In de eigenschappen van de app connector vind je deze gebruiker op het tabblad Algemeen.
App connector aanmaken:
Lees de toelichting bij Authorisation code flow en Authorisation client flow op deze pagina. Bij het aanmaken van de app connector gebruik je de volgende instellingen:
- Authenticatietype: Hybride
- Type OAuth flow: Beide
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: