Technische informatie omtrent OAuth kun u vinden in onze API Documentatie onder Authenticatie sectie OAuth. Onderstaande, wordt daar ook in uitgelegd, alleen vanuit een wat meer technisch oogpunt. Daar wordt u onder andere verwezen naar een technisch simpele uitleg. Let wel, beide zijn in het Engels.
Dit artikel is bedoeld om een beter beeld te geven in wat voor process dit betekend.
Er zijn 3 verschillende stappen te herkennen:
Daarnaast zijn er 3 partijen te herkennen:
- Partner -> de partner die met vPlan integreert, in dit voorbeeld is dat Bold Beard.
- Gebruiker -> de klant gebruiker, die beide systemen gebruikt, en wil integreren
- vPlan
Registreren applicatie
Om via OAuth met vPlan verbinding te maken moet de partner zich als eerste bekend maken bij vPlan.
- Partner: gaat naar https://developer.vplan.nl/
- Partner: klikt op de knop Sign-up
- Partner: vult de alle velden in.
Let op: App Base Redirect URI en App Logo URL worden gebruikt in het OAuth proces bij het verbinding maken. - Partner: klikt op de knop Signup en krijgt een blokje zoals hieronder.
Let op: bovenstaande betreft een voorbeeld, dat niet bruikbaar is. - Partner: zorgt ervoor dat de client_id en client_secret ergens intern goed opgeslagen wordt.
Client_secret het liefst encrypted opslaan, dit is namelijk het identificatie code voor deze app, en wordt maar eenmalig verstrekt.
Eenmalig verbinding maken (per klant)
Bij OAuth wordt er vaak vanuit gegaan dat er 2 applicaties zijn, die met elkaar integreren. Om deze reden is het niet voldoende om alleen een app te registreren, maar zal een gebruiker de applicatie moeten autoriseren in zijn vPlan omgeving.
Let op: in theorie kan een gebruiker van de partner, meerdere omgevingen van vPlan hebben. Dit zal in praktijk niet vaak voorkomen, maar in dat geval, zullen onderstaande stappen voor elke vPlan omgeving uitgevoerd moeten worden.
Let op: als een klant gebruiker voor de 2e keer een verbinding maakt, met hetzelfde account, dan worden alle voorgaande gestuurde tokens ongeldig gemaakt.
- Partner: geeft binnen de applicatie ergens een knop om te koppelen met vPlan.
- Gebruiker: klikt op de knop, waarna de gebruiker verwezen wordt naar:
https://developer.mostwanted.io/api/v1/oauth/authorize?client_id=90e1af5b-40ee-4d15-9b15-643b0360c581&redirect_uri=http:%2F%2Flocalhost:8080%2Foauth&response_type=code
De opbouw van de url is beschreven in Get authorization in de api doc.
In het kort moet de client_id en redirect_uri aangepast worden naar hetgeen er eerder is verkregen bij het registreren van de App. De redirect_uri mag eventueel verlengt worden met details die handig kunnen zijn voor latere oppak door de partner. - vPlan: stuurt de gebruiker door naar het inlog scherm.
- Gebruiker: logt nu in met zijn vPlan credentials.
- Gebruiker: geeft antwoord op de vraag of deze de integratie (in dit geval Bold Beard) wil autoriseren voor vPlan.
Let op: hier wordt de afbeelding gebruikt die bij APP Logo URL is opgeven bij het registreren. - vPlan: er wordt nu doorverwezen naar de redirect pagina eerder opgegeven. Er zijn dan 2 opties:
- Cancel: de query parameter error wordt meegegeven, met een korte tekst met een reden
- Authorize: de query parameter code wordt meegegeven, met de authorization_code
- Partner: aangezien de authorization_code +/- 10 minuten geldig is, wisselt de partner deze code in voor een token.
Voor details kijk naar Token Exchange in de api doc. - Partner: slaat de refresh_token encrypted op bij de klant, deze refresh_token is op dit moment 1 jaar geldig.
Herhalende verbinding
Nu de refresh_token is opgeslagen, kan deze gebruikt wordt om een access token op te halen. En de normale koppeling te laten verlopen.
Er zijn een aantal momenten denkbaar wanneer er verbinding gemaakt zal worden:
- Gebruiker: voert een actie uit, die informatie van vPlan vereist, of informatie naar vPlan stuurt
- Partner: via een scheduler wordt er elk X moment data naar vPlan gestuurd of van vPlan opgehaald.
Vanuit vPlan kan er geen verbinding opgestart worden met de partner. Er is geen zogenaamde 2 wegs verbinding, en er is op dit moment geen ondersteuning voor webhooks in vPlan.
Door de refresh token is er geen gebruiker interactie meer nodig om de verbinding met vPlan op te zetten.
Wanneer er data van of naar vPlan nodig is, zijn er de volgende stappen:
- Partner: wisselt de refresh_token in voor een access token
Voor details kijk naar Token Exchange in de api doc.
Let op: een refresh_token is maar 1 keer bruikbaar - vPlan: stuurt een access token en een nieuwe refresh token
- Partner: slaat nieuwe refresh token encrypted op bij de klant.
- Partner: maakt verbinding met de vPlan API om de benodigde acties uit te voeren.