Software partners can request permission from MDMB users to act on their behalf through the OAuth2 integration. Below you will find the instructions for linking your software to MDMB.
1. Client registration
Before the OAuth integration can be used, a client needs to be configured by us in MDMB for the external application. For this, we require the following information:
- The name of the application. This will be displayed to the user when granting permissions (see step 2 of the flow).
- The redirect URIs to which MDMB users will be directed. This prevents users from being directed to malicious websites and ensures that the authorization code is sent to the correct address. This can also be a pattern with wildcards (for example, "https://www.example.com/*").
With this information, we can configure a client on the test, staging, and production environments and share the client ID and secrets.
2. Flow
We use the OAuth 2.0 Authorization Code Flow for this:
https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type. In this flow, the external application sends the user to MDMB, where it can accept a number of permissions. If these are accepted, MDMB sends the user back to the external application and provides an "authorization code". This code allows the external application to request "access tokens" with which the MDMB API can be called.
The flow consists of the following steps:
1. The external application sends the user to MDMB's Authorization endpoint with the following format (in case of a 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
This contains the following information.
- The client identifier for the application
- the URI of the application to which MDMB should redirect the user and pass on the authorization code
- optionally a state string that is returned later, to prevent CSRF attacks
- optionally the "offline access" scope, which is used to ask the user if the application is allowed to act on behalf of the user not only at the moment, but also when he or she is not logged in
2. The user lands on a regular login page. After successfully logging in, a screen will be shown with the name of the client and the requested permissions.
3. If the user agrees, MDMB sends the user to the redirect URI. The authorization code and the state string are passed in the query parameters:
[redirect-uri]?code=[authorization-code]&state=[state]
4. The external application can now call MDMB's Token endpoint to obtain the access tokens: [base]/auth/realms/mdmb/protocol/openid-connect/token
De body van de request ziet er als volgt uit:
We use the OAuth 2.0 Authorization Code Flow for this purpose: https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type. In this flow, the external application directs the user to MDMB, where the user can accept a set of permissions. If these permissions are accepted, MDMB redirects the user back to the external application and provides an "authorization code." This code enables the external application to request "access tokens" for interacting with the MDMB API.
The flow consists of the following steps:
- The external application directs the user to the Authorization endpoint of MDMB in the following format (in the case of a 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 In this, the following information is provided:
- The identifier of the client for the application.
- The URI of the application where MDMB should redirect the user and pass the authorization code.
- Optionally, a state string that will be returned later to prevent CSRF attacks.
- Optionally, the "offline access" scope, which is used to ask the user if the application can act on their behalf not only at the moment but also when they are not logged in.
-
The user lands on a regular login page. After successfully logging in, a screen is displayed showing the name of the client and the requested permissions.
-
If the user agrees, MDMB redirects the user to the redirect URI. The query parameters carry the authorization code and the state string: [redirect-uri]?code=[authorization-code]&state=[state]
-
The external application can now call the Token endpoint of MDMB to obtain the access tokens: [base]/auth/realms/mdmb/protocol/openid-connect/token
The body of the request looks as follows:
grant_type: "authorization_code" code: "[authorization-code]" redirect_uri: "[redirect-uri]" client_id: "oauth-test-client" client_secret: "[client-secret]" |
As a response, MDMB provides a JSON object containing the following 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" } |
5. The access token can be used directly to call the API and has a lifespan of a few minutes. New access tokens can be obtained by calling the Token endpoint with the refresh token. If the user has granted permission for offline access, the refresh token can be used indefinitely as long as it remains unused for up to 30 days. In other cases, the refresh token also has a limited lifespan.
The request body looks as followed:
grant_type: "refresh_token" refresh_token: "[refresh-token]" redirect_uri: "[redirect-uri]" client_id: "oauth-test-client" client_secret: "[client-secret]" |
The response has the same format as in the previous step.
3. Use of access token
The access token is a JWT that can be used as a bearer token instead of the API key. To retrieve the data of a submission, for example, the following call can be made:
curl -i -H "authorization: Bearer [access-token]" https://test.mijndatamijnbusiness.nl/api/filings/mMeaU7cJR5C0LM8E80ZVKA |
Important note: When processing the call, MDMB requires the user to accept the latest terms and conditions. This is automated with the OAuth integration. If this is not the case, for instance, if the user did not agree to the terms during a previous MDMB login, the API will return a 403 Forbidden response.