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:

1. The name of the application. This will be displayed to the user when granting permissions (see step 2 of the flow).
2. 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 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:

 1. 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

2. 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.

3. 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]

4. 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:

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:

1. 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.

2. 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.

3. 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]

4. 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:

As a response, MDMB provides a JSON object containing the following tokens:

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:

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:

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.