VA:Aansluitproces Ketenpartijen

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken

Vroegtijdig Aanmelden mbo-symbol.png Vroegtijdig Aanmelden mbo: Aansluitproces Ketenpartijen

Deze pagina bevat informatie om als ketenpartij te kunnen communiceren met het vo-koppelpunt.

Algemene ontwerprichtlijnen

Berichten

  1. De berichten die verstuurd worden tussen de landelijke voorzieningen onderling en tussen de landelijke voorzieningen en de scholen zijn zo summier mogelijk in verband met privacy. Er wordt alleen informatie verstuurd waarvoor een grondslag en doelbinding beschikbaar is.
  2. Berichten worden per individuele aanmelding per student verstuurd, zowel de opgave van potentiële mbo-gangers als de opgaven aanmelding.
  3. Gegevens die nodig zijn om berichten goed te kunnen routeren worden door instellingen zelf gevalideerd en goed aangeleverd.

Uitwisseling

  1. Voor alle koppelpunten geldt dat berichten die niet valide zijn, voor zover het koppelpunt dit kan controleren, worden niet doorgestuurd. Het vo-koppelpunt retourneert een foutbericht met informatie over de geconstateerde fouten aan de afzender (zie Lijst met foutcodes).De afzender zal dit zelfde bericht niet ongewijzigd opnieuw aanbieden, dat wil zeggen, de afzender lost het geconstateerde probleem op.
  2. Als een bericht niet verwerkt kan worden door het vo-koppelpunt, bijvoorbeeld omdat er een ongeldig OIN wordt gebruikt, dan wordt dit vermeld in de log van het systeem en het bericht wordt vernietigd. Op basis van de aard en mogelijk de frequentie van voorkomen van de melding in de log zullen beheerders van het vo-koppelpunt contact opnemen met het verzendende systeem.
  3. De identificatie van onderwijsinstellingen in de berichten zelf gebeurt aan de hand van het BRIN4. Dit is het registratienummer van de erkenning van de onderwijsinstelling bij DUO (d.w.z. een juridische status), en wordt nu ook gebruikt als identificatie voor de onderwijsinstelling zelf.

Inhoud van een bericht

De opbouw van een verzoekbericht (request)

Een request dient ondertekend te zijn op basis van de Edukoppeling Transactiestandaard middels profiel 2w-be-s (2-way best effort signed).
Meer informatie over de Edukoppeling Transactiestandaard kan gevonden worden op Edukoppeling.nl

Klik hier voor de lijst met elementen, welke deel uit maken van de ondertekening.

  • De SOAP Headers
To

Bevat de URL van het afleveradres met het bijbehorende OIN.

  • Voor VO/VAVO LASsen (berichtenstroom potentiële mbo-ganger) zal het de URL bevatten van het gemeente-koppelpunt.
  • Voor het mbo-koppelpunt (berichtenstroom mbo-aanmelding) zal het de URL bevatten van het vo-koppelpunt met de OIN van de vo/vavo-instelling.


From Bevat de URL van de verzender met het bijbehorende OIN. Dit kan default ook anonymous zijn.
  • Voor VO/VAVO LASsen (berichtenstroom potentiële mb-ganger) zal het de URL bevatten van het LAS-endpoint.
  • Voor het mbo-koppelpunt (berichtenstroom mbo-aanmelding) zal het waarschijnlijk anonymous zijn met hierbij het OIN van de mbo-instelling.


Action

Hiermee wordt de operatie aangeduid. Deze moet overgenomen worden vanuit de WSDL.
Op dit moment zijn er 2 actions beschikbaar, welke van belang zijn voor berichtgeving naar en van het vo-koppelpunt:
http://vroegtijdigaanmelden.nl/v1_0/ontvangAanmeldbericht
http://vroegtijdigaanmelden.nl/v1_0/ontvangMBOGangerbericht

MessageId

Een random gegenereerd nummer, ter identificatie als er iets mis is gegaan met het berichtenverkeer binnen de keten.

Timestamp

De timestamp bevat minimaal het veld Created. Hiermee wordt de datum en tijd aangeduid van berichtcreatie.

Let op bij validatie binnen het vo-koppelpunt wordt gekeken of het bericht niet verstreken is op basis van dit veld. Volgens de specificaties (PvE) mag de huidige datum niet meer dan 2 dagen later zijn dan de creation date. Optioneel kan nog een expiration date time worden meegestuurd. Deze expiration date time moet aangehouden worden als het bericht gevalideerd wordt.

  • De SOAP Body

    Deze bevat de daadwerkelijke inhoud van het bericht conform de wsdl en xsd van het aanmeld en MBOgangerBericht.

De opbouw van een antwoordbericht (response)

Een response is ondertekend op basis van de Edukoppeling Transactiestandaard middels profiel 2w-be-s (2-way best effort signed).
Meer informatie over de Edukoppeling Transactiestandaard kan gevonden worden op Edukoppeling.nl

Klik hier voor de lijst met elementen, welke deel uit maken van de ondertekening.

  • De SOAP Headers:
To

Bevat de URL van het adres van de zender van het oorspronkelijke bericht met het bijbehorende OIN.

From Bevat de URL van de verzender met het bijbehorende OIN.
Action

Hiermee wordt de operatie aangeduid. Deze moet overgenomen worden vanuit de WSDL.
Op dit moment zijn er 2 actions beschikbaar, welke van belang zijn voor berichtgeving naar en van het vo-koppelpunt:
http://vroegtijdigaanmelden.nl/v1_0/ontvangAanmeldbericht
http://vroegtijdigaanmelden.nl/v1_0/ontvangMBOGangerbericht

RelatesTo

Dit veld bevat de messageId van het originele request.

Timestamp

De timestamp bevat minimaal het veld Created. Hiermee wordt de datum en tijd aangeduid van berichtcreatie.

Let op bij validatie binnen het vo-koppelpunt wordt gekeken of het bericht niet verstreken is op basis van dit veld. Volgens de specificaties (PvE) mag de huidige datum niet meer dan 2 dagen later zijn dan de creation date. Optioneel kan nog een expiration date time worden meegestuurd. Deze expiration date time moet aangehouden worden als het bericht gevalideerd wordt.

  • De SOAP Body

    Deze bevat de daadwerkelijke inhoud van het bericht conform de wsdl en xsd van het aanmeld en mbogangerBericht.

De inhoud van een ondertekend bericht

Klik hier voor de lijst met elementen, welke samen een ondertekend bericht vormen.

Binary security token

Dit bevat de publieke sleutel van het certificaat waarmee het bericht is ondertekend.

Digest value Op de Soapheaders en body wordt het sha256-algoritme toegepast om de verschillende velden te hashen. Canonicalisatie wordt toegepast om de namespace eenduidig te gebruiken.


Voorbeeld van Digest value

<ds:Reference URI="#id-A819ECE6A7D2AEB814153916000571753">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
<ec:InclusiveNamespaces PrefixList="gen soapenv v1" xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:DigestValue>SoGuntlVcJU73MFDXjrcMmFDp29kG+D5zcY53HdXI7s=</ds:DigestValue>
</ds:Reference>

URI verwijst in dit voorbeeld naar het element WSA Action element:

<wsa:Action wsu:Id="id-A819ECE6A7D2AEB814153916000571753" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">http://vroegtijdigaanmelden.nl/v1_0/ontvangAanmeldbericht</wsa:Action>
Signature value De som van alle digestvalues wordt genomen en dit wordt ook gehasht. Nadat het gehasht is, wordt deze waarde met behulp van de private sleutel geencrypt. Men kan de signature value decrypten dmv de publieke sleutel, welke meegestuurd wordt in het bericht.
Soapheaders Deze zijn hierboven beschreven in de opbouw van de diverse berichten.
Body Het daadwerkelijke bericht. Ter informatie staan diverse voorbeelden onder het kopje "Voorbeeldberichten" op deze pagina.


Info.gif Let op:
Op dit moment zijn het OIN en de URL van het gemeente-koppelpunt nog niet bekend. Zodra dit wel het geval is zal deze pagina worden bijgewerkt.

Validaties

Het vo-koppelpunt hanteert de volgende validaties voor binnenkomende berichten.

Op SSL-niveau

  • Er moet een geldig PKI-overheidscertificaat of OCW Digitaal Onderwijscertificaat (ODOC) worden gebruikt.
    Zowel het Root- als intermediate certificaten moeten worden vertrouwd (volledige Chain of Trust).
  • Het certificaat binnen het bericht:
    • moet ook een geldig PKI-overheidscertificaat of OCW Digitaal Onderwijscertificaat (ODOC) zijn;
    • moet hiërarchisch herleidbaar zijn tot de Staat der Nederlanden (PKI) of het ministerie van OCW (ODOC) als Root CA;
    • mag niet voorkomen op de van toepassing zijnde herroepingslijst (CRL);
    • mag niet verlopen zijn.


Info.gif Let op:
Bij nieuw aan te vragen certificaten wordt sterk aangeraden te kiezen voor een PKI-overheidscertificaat.
Dit omdat ODOC-certificaten geen onderdeel meer uitmaken van de aankomende Edukoppeling Transactiestandaard versie 1.3.

Ondertekening

De ondertekening van een bericht wordt gecontroleerd door het uitpakken van de SignatureValue (middels de BinarySecurityToken), waarna deze gedecrypt wordt tot een controleerbare DigestValue.

SOAP Headers

Soap Headers moeten aanwezig zijn en moeten waarden bevatten conform de Edukoppeling Transactiestandaard.

Body

De velden binnen de Body van het bericht moeten zijn ingericht conform het XSD.
De gebruikte Persoonsgebonden Nummers (PGN) moeten valide zijn (dit wordt gecontroleerd middels de Elfproef).

Timestamp

Deze ligt niet in de toekomst en is maximaal twee kalenderdagen oud.

Lijst met foutcodes

Het vo-koppelpunt geeft bij onjuistheden in binnenkomende berichten het volgende terug:

Foutcode Omschrijving Scenario Bron Opmerkingen
201 Ongeldig certificaat Bericht bevat geen geldig certificaat Programma van Eisen
202 Certificaat verlopen Certificate expired Programma van Eisen
203 Certificaat ingetrokken CRL Certificate revoked Programma van Eisen
204 Certificaat bevat een ongeldig OIN Certificate invalid OIN Programma van Eisen
205 Ongeldige afzender WSA FROM no OIN Programma van Eisen
206 Ongeldige ontvanger WSA TO no OIN Programma van Eisen
207 Ongeldige operatie ACTION is unknown Programma van Eisen
209 Ongeldige timestamp Timestamp expired Programma van Eisen
210 Ongeldige ondertekening Signing invalid Programma van Eisen
220 XSD fout Body invalid Programma van Eisen
301 Elfproef niet correct Invalid PGN Programma van Eisen
soap:Client.DK0000 no headers found no soapheaders Edukoppeling Transactiestandaard
soap:Client.DK0002 Niet geautoriseerd Not authorized Edukoppeling Transactiestandaard
soap:Client.DK0005 Wsa: to ontbreekt wsa TO missing Edukoppeling Transactiestandaard
soap:Client.DK0006 Wsa: action ontbreekt wsa ACTION missing Edukoppeling Transactiestandaard
soap:Client.DK0007 Wsa: messageID ontbreekt messageId missing Edukoppeling Transactiestandaard
soap:Client.DK0010 Andere headers header not allowed Edukoppeling Transactiestandaard
soap:Client.DK0011 Andere waarde in header Invalid value in WSA header Edukoppeling Transactiestandaard
soap:Client.EK0020 Wsa: from ontbreekt WSA FROM missing Edukoppeling Transactiestandaard

Voorbeeldberichten

Opgave van potentiële mbo-gangers (ontvangMBOgangerbericht)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://vokoppelpunt.vroegtijdigaanmelden.nl/v1_0/" xmlns:gen="http://vroegtijdigaanmelden.nl/v1_0/generiek">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:ontvangMBOGangerbericht>
         <gen:onderwijsvolger>
            <gen:PGN>114323234</gen:PGN>  Een PGN welke voldoet aan de voorschriften
         </gen:onderwijsvolger>
         <gen:postcodeHuisnummer>
            <gen:postcode>3145RR</gen:postcode>  Een valide postcode, formaat <9999AA>
            <gen:huisnummer>418</gen:huisnummer> Een huisnummer, formaat 'numeriek'
         </gen:postcodeHuisnummer>
         <gen:latendeInstelling>
            <gen:BRIN>00AA</gen:BRIN> Een valide BRIN, formaat <99AA>
            <!--Optional:-->
            <gen:onderwijsaanbiederID>123-ASD-123</gen:onderwijsaanbiederID>
         </gen:latendeInstelling>
         <gen:status>true</gen:status>  Een status welke voldoet aan de voorschriften
      </v1:ontvangMBOGangerbericht>
   </soapenv:Body>
</soapenv:Envelope>

Opgaven aanmelding (ontvangAanmeldbericht)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://vokoppelpunt.vroegtijdigaanmelden.nl/v1_0/" xmlns:gen="http://vroegtijdigaanmelden.nl/v1_0/generiek">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:ontvangAanmeldbericht>
         <gen:aanmeldingID>18EH00:12345678</gen:aanmeldingID>
         <gen:onderwijsvolger>
            <gen:PGN>123456789</gen:PGN>  Een PGN welke voldoet aan de voorschriften
         </gen:onderwijsvolger>
         <!--Optional:-->
         <gen:postcodeHuisnummer>
            <gen:postcode>2621AA</gen:postcode>  Een valide postcode, formaat <9999AA>
            <gen:huisnummer>12</gen:huisnummer>  Een huisnummer, formaat 'numeriek'
         </gen:postcodeHuisnummer>
         <!--Optional:-->
         <gen:latendeInstelling>
            <gen:BRIN>18EH</gen:BRIN>
            <!--Optional:-->
            <gen:onderwijsaanbiederID>003-AAA-454</gen:onderwijsaanbiederID>
         </gen:latendeInstelling>
         <gen:ontvangendeInstelling>
            <gen:BRIN>20GX</gen:BRIN>  Een valide BRIN, formaat <99AA>
            <!--Optional:-->
            <gen:onderwijsaanbiederID>003-AAA-454</gen:onderwijsaanbiederID>
         </gen:ontvangendeInstelling>
         <gen:status>LNI</gen:status>  Een status welke voldoet aan de voorschriften
      </v1:ontvangAanmeldbericht>
   </soapenv:Body>
</soapenv:Envelope>

Omgevingen

Er zijn 3 omgevingen beschikbaar:

  • Sandbox:

Deze omgeving is beschikbaar voor de leveranciers om de nieuwe functionaliteiten te ontwikkelen en om de functionele tests uit te voeren.
Om gebruik te maken van deze omgeving is een selfsigned certificaat nodig. Deze moet aangevraagd worden bij Stichting Kennisnet.

URL: https://vva-sb.vokoppelpunt.nl/vva/v1

  • Qualification:

Deze omgeving wordt gebruikt voor de compliancy (kwalificatie) testen.
Om gebruik te maken van deze omgeving is een PKI-overheidscertificaat nodig.

URL: https://vva-q.vokoppelpunt.nl/vva/v1

  • Production:

Deze omgeving is alleen beschikbaar voor leveranciers die gekwalificeerd zijn.
Om gebruik te maken van deze omgeving is een PKI-overheidscertificaat nodig.

URL: https://vva.vokoppelpunt.nl/vva/v1