Softwareleveranciers kunnen via de OAuth2 koppeling aan MDMB gebruikers toestemming vragen om namens hen te handelen. Hieronder tref je de instructies voor het koppelen van jouw software aan MDMB.
1 Client registratie
Voordat de OAuth koppeling gebruikt kan worden, moet er in MDMB 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 MDMB 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 MDMB, waar deze een aantal toestemmingen kan accepteren. Als deze geaccepteerd worden, stuurt MDMB 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 MDMB API kan worden aangeroepen.
De flow bestaat uit de volgende stappen:
- De externe applicatie stuurt de gebruiker naar de Authorization endpoint van MDMB 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 MDMB 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
- 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.
- Als de gebruiker akkoord gaat, stuurt MDMB 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] - De externe applicatie kan nu de Token endpoint van MDMB 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:
grant_type: "authorization_code" code: "[authorization-code]" redirect_uri: "[redirect-uri]" client_id: "oauth-test-client" client_secret: "[client-secret]" |
Als response geeft MDMB een JSON object terug met de tokens:
{ "access_token": "[access-token]", "expires_in": 300, "not-before-policy": 1651679326, "refresh_token": "[refresh-token]", "refresh_expires_in": 0, "scope": "offline_access mdmb", "session_state": "[session-state]", "token_type": "Bearer" } |
- 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:
grant_type: "refresh_token" refresh_token: "[refresh-token]" redirect_uri: "[redirect-uri]" client_id: "oauth-test-client" client_secret: "[client-secret]" |
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:
curl -i -H "authorization: Bearer [access-token]" https://test.mijndatamijnbusiness.nl/api/filings/mMeaU7cJR5C0LM8E80ZVKA |
Belangrijk: MDMB 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 MDMB-login niet akkoord is gegaan met de voorwaarden, dan zal de API een 403 Forbidden response teruggeven.