Software partners can request permission from Submission Portal users to act on their behalf through the OAuth2 integration. Below you will find the instructions for linking your software to Submission Portal.

1. Client registration

Before the OAuth integration can be used, a client needs to be configured by us in Submission Portal 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 Submission Portal 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 Submission Portal, where it can accept a number of permissions. If these are accepted, Submission Portal 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 Submission Portal API can be called.

The flow consists of the following steps:

1. The external application sends the user to Submission Portal'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 Submission Portal 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, Submission Portal 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 Submission Portal'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 Submission Portal, where the user can accept a set of permissions. If these permissions are accepted, Submission Portal 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 Submission Portal API.

The flow consists of the following steps:

1. The external application directs the user to the Authorization endpoint of Submission Portal 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 Submission Portal 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, Submission Portal 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 Submission Portal to obtain the access tokens: [base]/auth/realms/mdmb/protocol/openid-connect/token

The body of the request looks as follows:

As a response, Submission Portal 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, Submission Portal 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 Submission Portal login, the API will return a 403 Forbidden response.