Softwareleveranciers kunnen via de OAuth2 koppeling aan Aanleveren Portaal gebruikers toestemming vragen om namens hen te handelen. Hieronder tref je de instructies voor het koppelen van jouw software aan Aanleveren Portaal. 

1   Client registratie

Voordat de OAuth koppeling gebruikt kan worden, moet er in Aanleveren Portaal een client worden geconfigureerd voor de externe applicatie. Hiervoor hebben we de volgende informatie nodig:

• De naam van de externe applicatie. Deze wordt aan de gebruiker getoond bij het geven van toestemmingen (stap 2 van de flow).
• De redirect URIs waar Aanleveren Portaal gebruikers naar mag redirecten. Dit voorkomt dat gebruikers naar malafide websites worden gestuurd en zorgt ervoor dat de authorization code naar het juiste adres wordt gestuurd. Dit mag ook een patroon met wildcards zijn (bijvoorbeeld "https://www.example.com/*").

Met deze gegevens kunnen we een client configureren op de test-, acceptatie- en productieomgevingen en de client ID en secrets delen.

2       Flow

We gebruiken hiervoor de OAuth 2.0 Authorizaton Code Flow: https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type. In deze flow stuurt de externe applicatie de gebruiker naar Aanleveren Portaal, waar deze een aantal toestemmingen kan accepteren. Als deze geaccepteerd worden, stuurt de Portal de gebruiker weer terug naar de externe applicatie en geeft een "authorization code" mee. Met deze code kan de externe applicatie "access tokens" opvragen waarmee de Aanleveren Portaal API kan worden aangeroepen.

De flow bestaat uit de volgende stappen:

1.  De externe applicatie stuurt de gebruiker naar de Authorization endpoint van Aanleveren Portaal met het volgende formaat (in het geval van een test client): 
   [base]/auth/realms/mdmb/protocol/openid-connect/auth?response_type=code&client_id=oauth-test-client&redirect_uri=[redirect-uri]&state=[state]&scope=offline_access
   Hierin staan de volgende gegevens. 

• de identifier van de client voor de applicatie
• de URI van de applicatie waar Aanleveren Portaal de gebruiker naar moet redirecten en de authorization code aan moet worden doorgeven
• optioneel een state string die later weer wordt teruggegeven, om CSRF aanvallen te voorkomen
• optioneel de "offline access" scope, die wordt gebruikt om aan de gebruiker te vragen of de applicatie niet alleen op dit moment namens de gebruiker mag handelen, maar ook als deze niet is ingelogd

1. De gebruiker landt op een reguliere inlogpagina. Nadat deze succesvol is ingelogd, wordt er een scherm getoond met de naam van de client en de gevraagde toestemmingen.

1. Als de gebruiker akkoord gaat, stuurt Aanleveren Portaal de gebruiker naar de redirect URI. In de query parameters worden de authorization code en de state string doorgegeven:
   [redirect-uri]?code=[authorization-code]&state=[state]
2. De externe applicatie kan nu de Token endpoint van Aanleveren Portaal aanroepen om de access tokens te verkrijgen:
   [base]/auth/realms/mdmb/protocol/openid-connect/token
   De body van de request ziet er als volgt uit:

Als response geeft Aanleveren Portaal een JSON object terug met de tokens:

1. De access token kan direct gebruikt worden om de API aan te roepen en heeft een levensduur van enkele minuten. Nieuwe access tokens kunnen worden opgevraagd door de Token endpoint aan te roepen met de refresh token. Als de gebruiker toestemming heeft gegeven voor offline toegang, kan de refresh token oneindig lang gebruikt worden zolang die niet 30 dagen lang ongebruikt is. In andere gevallen heeft ook deze een beperkte levensduur.
   De body van de request ziet er als volgt uit:

De response heeft hetzelfde formaat als in de vorige stap.

3       Gebruik van de access token

De access token is een JWT die als bearer token gebruikt kan worden in plaats van de API key. Om de gegevens van een aanlevering op te halen, kan bijvoorbeeld de volgende call worden uitgevoerd:

Belangrijk: Aanleveren Portaal vereist bij het verwerken van de call dat de gebruiker de nieuwste algemene voorwaarden accepteert. Met de OAuth-koppeling wordt dat geautomatiseerd uitgevoerd. Als dit niet het geval is, bijvoorbeeld als de gebruiker bij een eerdere Portal-login niet akkoord is gegaan met de voorwaarden, dan zal de API een 403 Forbidden response teruggeven.