Technische koppeling voorbereiden

Op deze pagina geven we een introductie in de techniek die SURFeduhub gebruikt. We geven een aantal handleidingen die je kunt gebruiken om je instellingsystemen geschikt te maken voor SURFeduhub Op de pagina 'technische koppeling realiseren', leggen we uit welke stappen je precies moet doorlopen om SURFeduhub te kunnen gebruiken.

OOAPI ondersteunen

SURFeduhub maakt gebruik van de OOAPI standaard voor de uitwisseling van informatie tussen jouw instelling, SURFeduhub, en (externe) data consumers. De OOAPI-specificatie is een standaard die beschrijft hoe onderwijsinstellingen data over hun onderwijs beschikbaar kunnen stellen, zowel intern als aan derde partijen. Daartoe beschrijft de OOAPI onder andere hoe bijvoorbeeld een opleiding, een vak of een persoon beschreven dienen te zijn.

Een OOAPI endpoint implementeren

Om je organisatie geschikt te maken voor SURFeduhub moet er op instellingsniveau een OOAPI endpoint beschikbaar zijn. Een OOAPI endpoint is een stuk software dat de OOAPI standaard implementeert, zodat het (externe) dataverzoeken kan afhandelen en de opgevraagde data in het juiste (OOAPI) formaat kan communiceren. Om een OOAPI endpoint te implementeren moet de instelling keuzes maken over hoe de eigen onderwijsdata vertaald kan worden naar het formaat zoals de OOAPI-specificatie beschrijft.

Elke onderwijsinstelling maakt ook eigen keuzes over de inrichting van haar IT-landschap, de gebruikte applicaties daarin en de wijze waarop onderwijsdata gemodelleerd en opgeslagen wordt. Daarom zal ook elke instelling zelf moeten bepalen hoe haar OOAPI endpoint het beste geïmplementeerd kan worden, zodat het past binnen het eigen IT-landschap.

De eerste stap die een instelling zal moeten zetten is inventariseren in welke systemen de te ontsluiten data zich nu bevindt en hoe die data zich verhoudt tot het formaat dat de OOAPI beschrijft:

Om instellingen toch een handvat te geven over de implementatie van een OOAPI endpoint, zijn er drie voorbeeldscenario’s uitgewerkt.

Scenario 1 – De instelling ontwikkelt zelf een OOAPI v5 endpoint

Als er meerdere verschillende (autoratieve) bronsystemen of applicaties zijn waar de data die beschikbaar gemaakt moet worden zich bevindt en (een deel van) de applicaties is niet al compatibel met de OOAPI v5 standaard, dan kan de instelling ervoor kiezen zelf software te (laten) ontwikkelen. Die software behandelt de binnenkomende dataverzoeken en bevraagt per verzoek de juiste (combinatie van) bronsystemen om de data te verzamelen, vertaalt die vervolgens naar het OOAPI-formaat en beantwoordt het verzoek. In een dergelijk scenario kan er ook voor gekozen worden om regulier (bijv. 1x per nacht) alle data uit de bronsystemen op te halen en te vertalen, waarmee in effect een kopie van alle data bijgehouden wordt specifiek tbv. de OOAPI.

Scenario 2- Combineren van bestaande OOAPI endpoints

Bronsystemen kunnen al compatibel zijn met de OOAPI v5 standaard. Het kan echter goed zijn dat niet alle benodigde data voor het OOAPI endpoint zich in één bronsysteem bevindt. In dat geval kan ervoor gekozen worden om een kleinere applicatie te (laten) ontwikkelen die de data per bronsysteem kan combineren. In sommige gevallen zal ook een Enterprise Service Bus (ESB) een dergelijke rol kunnen vervullen. Sommige instellingen kiezen er hoe dan ook voor om alle data-uitwisselingen via de ESB te laten verlopen om regie te houden op de eigen data.\

Scenario 3 – Bronsysteem is compatibel met OOAPI

Als alle benodigde data in één bronsysteem te vinden is (bijvoorbeeld in het SIS), dan kan het voldoende zijn als dat ene systeem compatibel is met OOAPI v5. In dat geval heeft de instelling minder werk en is het aan de leverancier van het bronsysteem om het compatibel te maken met OOAPI v5 (indien dat nog niet het geval is).

Afsluitend

Deze drie scenario’s zijn slechts voorbeelden. Elke onderwijsinstelling is anders en daarmee zal elke instelling zelf moeten bepalen hoe de OOAPI het beste geïmplementeerd kan worden binnen de instelling.

Authenticatie

SURFeduhub ondersteunt drie verschillende vormen van authenticatie om zich te authenticeren bij je endpoint:

• –OAuth 2 client credentials
• –HTTP Basic Authentication
• –Custom headers

Je endpoint zal één van deze vormen moeten ondersteunen, anders is het maken van een koppeling niet mogelijk.

TLS

–Je OOAPI endpoint dient beveiligd te zijn met TLS met een geldig certificaat.

Firewall

Indien je endpoint beveiligd is met een firewall zal er een IP reeks van SURF op de allow list gezet moeten worden. Neem contact op met surfeduhub@surf.nl voor de IP reeks.