Overslaan en naar hoofdcontent gaan

Aanleveren Portaal API Authenticatie (voorheen MDMB)

Support medewerker
  • Bijgewerkt

Inleiding

De Filing REST API maakt het mogelijk om rapportages geautomatiseerd aan te leveren aan SBR Nexus. Om de veiligheid en betrouwbaarheid van deze aanleveringen te waarborgen, ondersteunt de API twee verschillende authenticatiemethoden.

Welke authenticatiemethode gebruikt wordt, is afhankelijk van de manier waarop de software met de Filing REST API integreert.

  • OAuth 2.0 in combinatie met eHerkenning is bedoeld voor applicaties die namens een eindgebruiker handelen. Hierbij logt de gebruiker in via eHerkenning en geeft deze expliciet toestemming aan de applicatie om namens hem of haar de Filing REST API aan te roepen. De applicatie ontvangt vervolgens een OAuth Access Token waarmee de API kan worden gebruikt.

     

  • PKIoverheid (PKIo) certificaat-authenticatie is bedoeld voor server-to-server integraties waarbij geen interactieve gebruiker aanwezig is. De applicatie authenticeert zich met een geldig PKIoverheid-clientcertificaat via Mutual TLS (mTLS). Omdat hierbij geen gebruiker inlogt, moet de applicatie bij iedere API-aanroep expliciet aangeven namens welke gebruiker of organisatie wordt gehandeld.

 Afhankelijk van de gekozen integratie wordt één van deze authenticatiemethoden gebruikt.

 Nadat is bepaald welke authenticatiemethode voor de integratie wordt gebruikt, raadpleeg dan de API-documentatie voor een beschrijving van de beschikbare API-calls, request- en responseformaten.

API-documentatie: https://support.sbrnexus.nl/hc/nl/articles/360014653620-API-documentatie-om-je-software-te-koppelen-met-Aanleveren-Portaal-voorheen-MDMB

 

Ondersteunde authenticatiemethoden

 

Authenticatiemethode Toepassing Authenticatie Gebruikersidentificatie
OAuth 2.0 + eHerkenning Applicaties die namens een eindgebruiker handelen OAuth 2.0 Authorization Code Flow met Bearer Access Token Via de ingelogde gebruiker (eHerkenning)
PKIoverheid certificaat (Mutual TLS) Server-to-server integraties (Trusted Applications) Mutual TLS (mTLS) met een geldig PKIoverheid-clientcertificaat Via de X-External-Entity-Identification HTTP-header

Authenticatiemethoden in samenvatting

 

OAuth 2.0 + eHerkenning

Gebruik OAuth wanneer een gebruiker zich moet authenticeren en expliciet toestemming geeft dat de software namens hem of haar mag handelen.

Kenmerken:

  • eindgebruiker logt in via eHerkenning
  • gebruiker geeft toestemming aan de applicatie
  • API gebruikt Bearer Access Tokens
  • Refresh Tokens worden ondersteund
  • geschikt voor interactieve software

PKIoverheid (Mutual TLS)

Gebruik PKIoverheid-certificaten voor server-to-server integraties waarbij geen interactieve gebruiker aanwezig is.

Kenmerken

  • authenticatie via Mutual TLS (mTLS)
  • geen Bearer Token nodig
  • authenticatie gebeurt tijdens de TLS-handshake
  • gebruiker wordt geïdentificeerd via een HTTP-header
  • geschikt voor Trusted Applications

 

OAuth 2.0 met eHerkenning

Overzicht

De Filing REST API ondersteunt de OAuth 2.0 Authorization Code Flow.

Hiermee kan een gebruiker veilig authenticeren via eHerkenning en toestemming geven aan een softwarepakket om namens hem of haar de Filing API aan te roepen.

Na succesvolle authenticatie ontvangt de applicatie een Access Token waarmee de API kan worden aangeroepen.

OAuth Endpoints

 

Omgeving Base URL
Test https://test-aanleverenapi.sbrnexus.nl
Acceptatie https://acc-aanleverenapi.sbrnexus.nl
Productie https://aanleverenapi.sbrnexus.nl

 

De Authorization Endpoint en Token Endpoint bevinden zich onder deze omgeving.

Stap 1 - Clientregistratie

Voordat OAuth gebruikt kan worden moet een OAuth Client worden geregistreerd.

Hiervoor zijn de volgende gegevens nodig van de Client:

 

Eigenschap Omschrijving
Applicatienaam Naam van de applicatie die de authenticatie doet
Redirect URI(s) URI waarnaar de gebruiker wordt teruggestuurd na authenticatie
Omgeving Test, Acceptatie of Productie

 

Na registratie verstrekt SBR Nexus:

  • Client ID
  • Client Secret

Deze gegevens zijn benodigd voor het verkrijgen van Access Tokens.

Stap 2 - Authorization Request

De applicatie stuurt de gebruiker naar de Authorization endpoint 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. 

Parameters

Parameter Verplicht Omschrijving
response_type Ja Code
client_id Ja Client ID van de applicatie
redirect_uri Ja Geregistreerde redirect URI
state Nee Wordt gebruikt ter bescherming tegen CSRF-aanvallen
scope Nee Gebruik offline_access indien Refresh Tokens gewenst zijn

Stap 3 - Inloggen via eHerkenning

De gebruiker wordt doorgestuurd naar de inlogpagina.

Na succesvolle authenticatie:

  • wordt de gebruiker geïdentificeerd via eHerkenning;
  • worden de gevraagde rechten weergegeven;
  • kan de gebruiker toestemming geven aan de applicatie.

Na goedkeuring wordt de gebruiker teruggestuurd naar de Redirect URI.
De applicatie ontvangt:

  • Authorization Code
  • State (indien opgegeven)

Voorbeeld:

[redirect-uri]?code=[authorization-code]&state=[state]

Stap 4 - Access Token ophalen

De applicatie wisselt de Authorization Code om voor een Access Token.

  1. [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 Aanleveren Portaal 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"

 

Stap 5 - API aanroepen

Na het verkrijgen van een Access Token kan de Filing API worden aangeroepen.

Voeg de volgende HTTP-header toe:

Authorization: Bearer <access-token>

Voorbeeld

POST  https://test-aanleverenapi.sbrnexus.nl/api/reports

 Authorization: Bearer eyJhbGc...

Stap 6 - Access Token vernieuwen

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 bij het ophalen van een nieuw Access Token.

Algemene voorwaarden

 

Voor het verwerken van API-aanroepen controleert de Filing REST API of de gebruiker de meest recente algemene voorwaarden heeft geaccepteerd.

Wanneer dit niet het geval is, retourneert de API:

HTTP 403 Forbidden

De gebruiker dient eerst opnieuw in te loggen en de actuele voorwaarden te accepteren.

 

PKIoverheid certificaat (Mutual TLS)

Overzicht

Naast OAuth 2.0 ondersteunt de Filing REST API authenticatie via Mutual TLS (mTLS) met een PKIoverheid-clientcertificaat.

Deze authenticatiemethode is bedoeld voor Trusted Applications die zonder tussenkomst van een interactieve gebruiker rapportages aanleveren. Hierbij authenticeert de applicatie zichzelf met een geldig PKIoverheid-clientcertificaat tijdens de TLS-handshake.

In tegenstelling tot OAuth 2.0 vindt er geen gebruikerslogin plaats en wordt geen Bearer Access Token gebruikt. De identiteit van de gebruiker of organisatie namens wie de applicatie handelt, wordt daarom expliciet meegestuurd in een HTTP-header.

 

Werking van Mutual TLS (mTLS)

Bij Mutual TLS presenteren zowel de client als de Filing REST API tijdens de TLS-handshake een geldig certificaat.

De verbinding wordt uitsluitend tot stand gebracht wanneer:

  • het clientcertificaat geldig is;
  • het certificaat van de Filing API wordt vertrouwd;
  • de volledige certificaatketen valide is;
  • het certificaat niet is verlopen;
  • het certificaat niet is ingetrokken.

 Wanneer één van bovenstaande controles mislukt, wordt de TLS-verbinding geweigerd en wordt de API-aanroep niet verwerkt.

De API's maken gebruik van een Private Root CA-certificaat dat niet standaard wordt vertrouwd. Om een succesvolle TLS-verbinding tot stand te brengen, moet dit certificaat expliciet worden toegevoegd aan de truststore van de aanroepende applicatie. Het certificaat is beschikbaar via https://cert.pkioverheid.nl/ onder "Staat der Nederlanden Private Root CA - G1"

PKIo Endpoints

Gebruik onderstaande endpoints voor authenticatie via Mutual TLS.

Omgeving Base URL
Test https://test-aanleverenapi-pki.sbrnexus.nl
Acceptatie https://acc-aanleverenapi-pki.sbrnexus.nl
Productie https://aanleverenapi-pki.sbrnexus.nl

 

Let op

Deze endpoints ondersteunen uitsluitend authenticatie via een PKIoverheid-clientcertificaat. OAuth 2.0 Bearer Tokens worden op deze endpoints niet ondersteund.

 

Gebruikersidentificatie

Omdat bij Mutual TLS geen gebruiker inlogt, moet de applicatie bij iedere API-aanroep expliciet aangeven namens welke gebruiker en organisatie wordt gehandeld.

Hiervoor wordt gebruikgemaakt van de HTTP-header:

X-External-Entity-Identification

De waarde van deze header bestaat uit een Base64-gecodeerd JSON-document.

De aanroepende applicatie is verantwoordelijk voor de juistheid van deze gegevens.

JSON-structuur

Onderstaande JSON bevat de identificatiegegevens van de gebruiker namens wie de applicatie handelt.

{

  "firstName": "Piet",

  "familyName": "Postbus",

  "email": "Piet.Postbus@example.com",

  "organizationName": "Example Org",

  "organizationCocNumber": "00000012"

}

 

Veld Omschrijving
firstName Voornaam van de gebruiker
familyName Achternaam van de gebruiker
email E-mailadres van de gebruiker
organizationName Naam van de organisatie
organizationCocNumber KvK-nummer van de organisatie

Base64-encodering

Voordat de identificatiegegevens als HTTP-header worden meegestuurd, moet het JSON-document worden gecodeerd naar Base64.

Voorbeeld:

 }

Base64

ew0KICAgICJmaXJzdE5hbWUiOiAiUGlldCIsDQogICAgImZhbWlseU5hbWUiOiAiUG9zdGJ1cyIsDQogICAgImVtYWlsIjogIlBpZXQuUG9zdGJ1c0BleGFtcGxlLmNvbSIsDQogICAgIm9yZ2FuaXphdGlvbk5hbWUiOiAiRXhhbXBsZSBPcmciLA0KICAgICJvcmdhbml6YXRpb25Db2NOdW1iZXIiOiAiMDAwMDAwMTIiDQp9

Deze Base64-string wordt toegevoegd aan de HTTP-header.

X-External-Entity-Identification: ew0KICAgICJ...

Authenticatie in Postman

Wanneer de API met Postman wordt getest, configureer dan een clientcertificaat.

Ga naar:

Settings → Certificates

Voeg vervolgens toe:

  • Host: test-aanleverenapi-pki.sbrnexus.nl
  • Port: 443
  • PKIoverheid-clientcertificaat (.p12/.pfx of .pem)
  • Private key (indien van toepassing)

Postman zal het clientcertificaat automatisch meesturen tijdens de TLS-handshake.

Authenticatie in de API

Bij gebruik van Mutual TLS wordt geen Authorization-header meegestuurd.

Authenticatie vindt volledig plaats tijdens de TLS-handshake.

De API-aanroep bevat daarom uitsluitend de functionele headers, zoals bijvoorbeeld:

X-External-Entity-Identification: <Base64 encoded JSON>

Content-Type: multipart/form-data

 

Belangrijk

Voeg geen Authorization: Bearer-header toe wanneer gebruik wordt gemaakt van PKIoverheid (Mutual TLS).

 

 

Was dit artikel nuttig?
Aantal gebruikers dat dit nuttig vond: 0 van 0