[Integratie] Authenticatie en authorisatie
De MyOrganizer API gebruikt zoveel mogelijk standaarden op gebied van authenticatie en authorisatie.
Zo maken we gebruiken van OAuth2 en meer bepaald de authorization code grant om te authenticeren.
Voor u start, heeft u steeds van ons een Client ID en Secret nodig alsook de API logingegevens van de MyOrganizer gebruiker.. U kan deze aanvragen via support@ringphone.be
Integrators communiceren met onze API steeds in naam van (on behalf of) een van onze klanten. Zo zal u dus in uw applicatie iets moeten inbouwen waarmee de klant een eerste keer inlogt met zijn MyOrganizer API account. Nadien kan u via (refresh)tokens in naam van de klant in de achtergrond blijven communiceren met de API. U heeft dan uiteraard enkel toegang tot gegevens van de agenda en/of groepspraktijk van de klant. Indien de klant op een bepaald moment geen toegang meer heeft tot Myorganizer, zal ook uw applicatie niet meer kunnen communiceren met de API.
Bij de aanvraag tot toegang is het belangrijk ons mee te sturen welke calls uw applicatie wil uitvoeren op onze API. Het is niet omdat u kan authenticeren dat u automatisch ook toegang heeft tot al onze API’s. Iedere API wordt geassocieerd met scopes en als integrator krijgt uw applicatie enkel toegang tot de API acties die wij voor uw applicatie toelaten.
Zo kan het goed mogelijk zijn dat u afspraken kan ophalen, maar geen nieuwe afspraken kan aanmaken. Ook moet de klant u toegang verlenen om in zijn naam deze acties te kunnen uitvoeren.
In het kort:
Toegang tot de api gebeurt via 2 security lagen.
Uw applicatie zal altijd communiceren in naam van een van onze klanten. (authenticatie)
Uw applicatie krijgt toegang tot bepaalde API acties via scopes (authorisatie)
De combinatie van bovenstaande zorgt dus uiteindelijk tot welke data u toegang heeft op onze API.
Opgelet: Onderstaande documentatie is eerder technisch en wordt beschouwd voor uw ontwikkelingsteam
JWT (Json web token)
Wie u bent en wat u allemaal mag doen zit uiteindelijk bevat in een Json web token (JWT) of access token. U dient dit token op te vragen bij onze Identity provider en mee te sturen bij iedere call naar onze API.
Uiteraard is deze JWT slechts voor een bepaalde tijd geldig. Om nadien als applicatie opnieuw toegang te krijgen tot onze api hoeft de klant niet meer opnieuw in te loggen. U kan een nieuwe access token ophalen via de refresh token die in de eerste response bevat zat.
Onderstaande flows beschrijven het authenticatie mechanisme op de meest eenvoudige manier
Hieronder een voorbeeld inclusief het refresh token mechanisme zonder dat de klant dus telkens opnieuw moet gaan inloggen
MyOrganizer gebruikt Microsoft Azure als identity provider. Uitgebreide developer documentatie kan u vinden op deze pagina met een eenvoudige illustratie in volgende afbeelding.
Scopes die u kan meesturen bij het ophalen van de tokens:
offline_access → zodat u een refresh token kan terug krijgen
Application scopes:
Opgelet: het kan zijn dat u geen toegang heeft tot alle application scopes. Vraag dit na via support@ringphone.be
How to:
Ophalen van de authorisatie token:
Authenticatie url:
https://ringphonesso.b2clogin.com/ringphonesso.onmicrosoft.com/B2C_1_MyOrganizer_Login/oauth2/v2.0/authorize
Probeer het zelf via volgende url in uw adresbalk te plakken:
GET https://ringphonesso.b2clogin.com/ringphonesso.onmicrosoft.com/B2C_1_MyOrganizer_Login/oauth2/v2.0/authorize?response_type=code&state=&client_id={uwclientId}&scope=offline_access {scopes gescheiden via spatie}&redirect_uri={redirect url naar uw applicatie}
2. Ophalen van de access token:
Access token url:
https://ringphonesso.b2clogin.com/ringphonesso.onmicrosoft.com/B2C_1_MyOrganizer_Login/oauth2/v2.0/token
Probeer het zelf via:
POST
https://ringphonesso.b2clogin.com/ringphonesso.onmicrosoft.com/B2C_1_MyOrganizer_Login/oauth2/v2.0/token
body:
grant_type=authorization_code&code={de ontvangen authorisatie code of refresh token}&redirect_uri={redirect url naar uw applicatie}&client_id={uwclientId}&client_secret={uwclientsecret}
De ontvangen jwt dient bij iedere call naar onze api meegestuurd te worden via the basic authorisation header.
We hebben ook een postman file die onmiddellijk de juiste url’s voor u invult als voorbeeld. Contacteer ons hiervoor via support@ringphone.be